Shape data¶

A diagram can carry more than pictures. Give each pump a flow rate, each task an owner, each piece of equipment a status, and the drawing becomes something you can search, sort and export as a table.

You only need this page if that sounds useful. Plenty of diagrams are just boxes and arrows, and that's fine.

Three words turn up throughout:

• A field is a named piece of information, such as Owner.
• A value is what you enter for one shape, such as Alex.
• A default is the value a new shape starts with.

Fields belong to a library shape. Every copy you place gets those fields and then keeps its own values.

Start here¶

1. Right-click a shape in the Library panel and choose Edit Shape Data…. The library window opens with that shape selected on its Shape Data tab.
2. Click Add Field at the upper right, enter a name, and choose a type. For example, add an Owner text field and a Status choice field.
3. Set a starting value if you want one, then click Save. For a built-in or downloaded library, leave Sync all placed shapes (just above Save) checked to update matching shapes already in this document.
4. Drag a copy onto the diagram. You can also double-click the library shape to place it in the centre of the current view.
5. Right-click the placed shape and choose Edit Shape Data. Click a value to edit it. Press Enter or move to another cell to finish.
6. Save your diagram as usual. There is no separate Save button for each cell.

Hover over the small i icons beside the title and the sync option for an explanation. Add Field stays visible while you scroll through the fields.

Choose a field type¶

Leave a value blank when it is unknown. Blank is different from zero or No. Changing a unit label does not convert existing numbers.

A field's type can't be changed once the field exists, so values already entered stay valid.

Number limits¶

For a number field, turn on Min or Max and enter the limit. Leave Allow this value on to include the limit itself. Turn it off when the value must be strictly above the minimum or below the maximum.

For example, a minimum of 0 with Allow this value off requires a positive number. Invalid entries show a message and keep the previous saved value.

Renaming a field or choice¶

Edit its existing name. Existing values stay attached to it. Renaming the choice “In progress” to “Under way” keeps that selection when a diagram accepts the update.

Names that only look different still count as the same name. Capital letters, extra spaces, full-width letters and invisible characters are ignored when checking whether two shared fields, or two choices in one field, match.

Deleting an option is different from renaming it. If an update would make an existing value invalid, the app asks you to resolve the problem first. It does not quietly replace your entries.

Give every shape in a library the same fields¶

Right-click the library heading and choose Shared Fields…, or open the library window, select Library Settings, and click the Shared Fields tab. Shared fields apply to the library's current shapes and to shapes added to it later.

• Add Field opens a small dialog for one field. Enter its name, type and starting value, then click Add Field.
• Edit… changes one field's name, starting value or rules.
• Remove removes a field from every shape in the library.

Each of these asks you to confirm with OK, then saves right away, separately from the window's own Save. Closing the window with Cancel does not undo it.

If you have unsaved changes on a shape, click Save or Cancel first. The Shared Fields tab says so and keeps its buttons dimmed until then.

If some shapes already have a field with exactly the same name and settings, adding it as a shared field simply shares it: those shapes use the shared field and the rest gain it. If they have a field with that name but different settings, the app tells you how many shapes differ. Make the settings match, or choose another name.

For example, give every equipment shape an Owner and an Installation date. Then right-click just the pump shape to add its Flow rate field.

On a shape's Shape Data tab, a shared field is labelled Shared field and can't be renamed or removed there. You can give that shape a different starting value: one pump can start at 50 litres/min and another at 100. Set it back to the shared starting value to follow future shared defaults again. Click Edit in Shared Fields to change the field itself.

If the library or an affected shape is protected, the shared fields are shown read-only. Removing a shared field removes it from the library's shapes; existing diagrams keep their saved fields and values.

Edit values in a diagram¶

There are two panels, and each belongs to its own document window.

One shape: the Shape Data panel¶

Select a shape and use the Shape Data panel (Cmd+Alt+7, or Window ▸ Panels ▸ Shape Data ▸ Show). Editable cells can be changed directly. Read-only cells are dimmed. Making a field read-only keeps its value. The shape's automatic ID cannot be edited.

A whole page: Page Data¶

Page Data shows every shape on the page as a table. It starts hidden. Choose Window ▸ Panels ▸ Page Data ▸ Show, or press Cmd+Alt+8. It remembers whether you last used it below the diagram or in a separate window.

• Search for shapes or values with the search box.
• Filter to shapes that have data with the filter button beside the search box: choose Only shapes with data.
• Sort by type by clicking the Type heading. That column shows what each shape is, such as a library shape's name (Box) or Text. You can search for a type name too.
• Find a shape by selecting its row and clicking Show on Diagram, the button beside the filter.

Use View in the Page Data header to expand the table, show the diagram and table together, open a separate window, or hide it. To dock a floating table, choose View ▸ Dock Below Diagram, or drag its title bar until the pointer reaches the bottom edge of the canvas and release when the blue line appears.

Drag the divider above Page Data down to leave just its header visible, and back up to see the table again. You can also double-click the Page Data title: it collapses to its header, and a second double-click reopens it at the height you last used.

When a value can't be saved¶

A dialog keeps what you typed and explains why. Correct the value and click Save Value, or choose Cancel Edit. If the shape's data changed during your edit, copy your entry before cancelling, then review the current value and edit again.

Switching to another document does not redirect an unfinished edit.

Bring library changes into an existing diagram¶

Editing a library's fields does not change diagrams you have already drawn. You bring changes in when you choose to, and each of these can be undone in one step.

For one library shape, right-click it in the Library panel and choose Sync All Placed Shapes. This updates matching shapes on every page of the current document. It keeps values you entered, updates unused starting values, and adds new fields. It also gives the shapes the library's current connection points and text region, even if you moved a shape's points in the diagram. Connectors stay attached to points that still exist; a connector end on a removed point is released where it is. Locked shapes, and shapes whose change would release a locked connector, are skipped. Other documents are left alone.

While you edit a built-in or downloaded library shape, its Shape Data tab has Sync all placed shapes, checked by default. Leave it checked to update this document when you save the library's fields or connection points. Uncheck it to save only the library changes. Undo in the document does not undo the library save.

When you open a diagram or import a library, the app checks for changed fields and defaults. If it finds any, it shows Shape data updates available:

• Review… shows which library shapes have changed.
• Sync applies the changes while keeping values you entered.
• Later leaves the diagram as it is.

From a data panel, choose Data Actions ▸ Sync from Library…. Choose selected shapes, the current page, or the whole document, then preview and confirm. Values you entered are kept; other values use the new defaults. Connection points and text position is checked by default; uncheck it to update only data. Locked shapes are skipped.

Sync is a one-time update, not an ongoing link. It changes fields, values, connection points and text position, never artwork. Fields removed from a library stay in existing diagrams so their data is not lost.

Replacing values you entered, on purpose¶

Use Data Actions ▸ Reset Values to Library Defaults…. Choose the scope and fields, review what will change, then click Reset Values. This is the one command that replaces values you typed, so use an ordinary sync when you want to keep them. Reset can also be undone in one step.

Put a library's fields back the way they came¶

If you have saved changes, Restore appears to the left of Add Field on a shape's Shape Data tab, and Library Defaults appears in the same place on Shared Fields. Each asks for confirmation, then removes fields you added and restores changed field settings and starting values. Unsaved edits in that editor go too.

Shapes already in your diagrams keep their fields and values. You can continue editing and click Save; on an individual shape, Sync all placed shapes controls whether that save also updates matching shapes in this document.

Library Defaults affects only the shared fields. Individual shape settings are kept, except defaults for shared fields that are removed. If a shape's own field was merged into a shared field you added, the library's version of that field comes back.

Copy the table into a spreadsheet¶

In Page Data, choose Data Actions ▸ Copy Table ▸ All Rows, then paste into a spreadsheet such as Numbers. You get the table as you see it: the rows your find text and filter leave, in the order you sorted them, with the Shape and Type columns followed by one column per field. Number fields put their unit in the heading, such as Cost (AUD).

Copy Table has been tested with Numbers. Other spreadsheets may treat some values differently.

Selected Rows copies only the shapes selected in the diagram. A selected shape that your filter hides is not in the table, so it is not copied either.

The same two commands are in the menu bar under Edit ▸ Copy Page Data Table, with keyboard shortcuts:

They work whenever Page Data is showing, docked or in its own window, even while you are working in the diagram. They are dimmed while Page Data is hidden, because there is no table on screen to copy. If a copy cannot be made, the message appears on the window that holds the table.

A few things are worth knowing before you paste:

• Copying first finishes any cell you are editing. A valid edit is saved to the diagram and copied; an invalid one stays put for you to fix, and your clipboard is left alone.
• Numbers are written the way your Mac's region writes them, so 12.5 becomes 12,5 where the decimal mark is a comma.
• Line breaks, tabs and quotation marks inside a value stay inside its cell.
• Text that starts with =, +, - or @ gets an apostrophe in front, so Numbers shows it as text instead of running it as a formula. So does text a spreadsheet would quietly change into a different number, such as 00123 or a very long account number. Numbers shows that apostrophe in the cell. It is not pretty, but it is better than a postcode losing its zeroes.
• Yes / No fields are copied as the words you see, not as true and false.

A spreadsheet still makes up its own mind about some text, such as 1/2. If exact values and types matter, export JSON instead.

Two fields with the same name, or a field named like the Shape or Type column, get a few characters of their identifier after the heading, such as Status (ab12), so you can tell the columns apart.

A very large table is not copied in part. If it has more than 4,096 fields, or would be more than 8 MB of text, SimpleDiagrams tells you and leaves your clipboard alone. Use the find text to list fewer shapes, or export CSV.

Export the data¶

In Page Data, choose Data Actions ▸ Export CSV or Export JSON, then choose the current page, selected shapes, or the whole document. Exports ignore the find text, filter and sort order, and include every shape in the scope you chose.

CSV is for saving a spreadsheet file. JSON includes field definitions, types and stable identifiers for other software, and preserves the original text of every value. Exporting does not change the diagram.

Whose fields are they?¶

You can add fields to any library, including the ones that come with the app and ones you downloaded. For those, your fields are kept on this Mac beside the library: the library itself isn't changed, so it can still be updated, and exporting it does not include your additions. Fields in a library you made are part of that library.

Either way, a diagram stores the fields and values it uses, so it opens complete on another Mac. Back up your Mac as well as your diagram files to keep your personal library settings.

See Changing a library you didn't make for everything else you can adjust in a built-in or downloaded library.

If something can't be edited or updated¶

• A field is read-only: the library's creator has protected it, or the shape itself is locked.
• A library changed while an editor was open: reopen the editor to review the current fields. Your diagram's saved values are kept.
• Your changes conflict with a newer library: open its data editor. Copy any text you need before choosing Restore (or Library Defaults on Shared Fields).
• An entry breaks a new rule: correct the entry or keep the old definition for now. An update is never partly applied.
• Library changes saved, but shapes not updated: the library save succeeded. Resolve the reported problem and sync again. The diagram keeps its previous definitions until the update succeeds.
• The library is missing: existing diagram fields and values remain saved in the document.

Libraries that carry shape data need SimpleDiagrams 5.0.5 or later; see Files and formats.