Canvas Metadata
One of the great power-user features of OmniGraffle is the ability to assign metadata to objects. Assigned metadata can then be retrieved and used in automating the construction and formatting of documents. Very powerful indeed!
This webpage describes the various canvas metadata properties and methods that are available for your use in creating automated publishing tools.
Metadata Properties
Every canvas has two basic metadata properties: id and name. The id and name properties can be used to identify a canvas.
id (Number r/o) • The unique identifier (within this document) of this graphic.
name (String or nil) • The name of this graphic, if any. The name appears (and can be edited) in the sidebar.
| Get Canvas by ID | ||
| 01 | function canvasWithID(canvasID){ | |
| 02 | for(i = 0; i < canvases.length; i++){ | |
| 03 | if (canvases[i].id === canvasID){ | |
| 04 | return canvases[i] | |
| 05 | } | |
| 06 | } | |
| 07 | errorString = "There is no canvas with id: " + canvasID.toString() | |
| 08 | new Alert('ERROR', errorString).show(function(result){}) | |
| 09 | throw new Error(errorString) | |
| 10 | } | |
| 11 | canvasWithID(1) | |
| Get Canvas by Name | ||
| 01 | function canvasWithName(canvasName){ | |
| 02 | for(i = 0; i < canvases.length; i++){ | |
| 03 | if (canvases[i].name.localeCompare(canvasName) == 0){ | |
| 04 | return canvases[i] | |
| 05 | } | |
| 06 | } | |
| 07 | errStr = "There is no canvas named: " + canvasName | |
| 08 | new Alert('ERROR', errStr).show(function(result){}) | |
| 09 | throw new Error(errStr) | |
| 10 | } | |
| 11 | canvasWithName('iPad Horizontal') | |
Notes and User-Data Keys
The Canvas class does not directly support the notes and userData properties used by graphics to store and retrieve data. However, the value of the canvas background property is a Solid Graphic that inherits the metadata properties and methods of a Graphic.
| Background Shape of Selected Canvas | ||
| 01 | document.windows[0].selection.canvas.background | |
| 02 | //--> [object Shape] | |
Since it is a Graphic, the background shape of every canvas supports the two basic Graphic metadata properties: notes and userData.
The notes property can store a description or other textual data related to the canvas.
notes (String) • Notes attached to this graphic.
userData (Object) • An object record of keys/value pairs of user data. {"keyName":"keyValue", etc.}
| Set Notes of Selected Canvas | ||
| 01 | cnvsBackground = document.windows[0].selection.canvas.background | |
| 02 | cnvsBackground.notes = 'How Now Brown Cow' | |
The metadata properties of a canvas can be viewed and edited within the Canvas tab of the information sidebar on both macOS (left) and iOS (right).
User-Data Keys are one or more user-defined pairs of key names and data values that are assigned to a graphic object. A key could be any type of identifier, such as a SKU or product number, or a person’s name. The key value can be any type of data expressed as a string.
Graphic Metadata Methods
Here are Graphic instance methods for getting and setting user data keys and values:
userData[keyName] (String) • Although not a method, this is how to get the user data string attached to this graphic for a given key.
setUserData(keyName, valueString or nil) (String) • Set the user data string attached to this graphic for a given key.
A function for setting user data:
| Set Canvas User Data for Key | ||
| 01 | function setCanvasUserDataForKey(key,value){ | |
| 02 | graphic = document.windows[0].selection.canvas.background | |
| 03 | graphic.setUserData(key,value) | |
| 04 | } | |
| 05 | setCanvasUserDataForKey('SKU','W123456789') | |
A function for getting user data. The result will be 'undefined' if no matching key is found:
| Get Canvas User Data for Key | ||
| 01 | function getCanvasUserDataForKey(key){ | |
| 02 | graphic = document.windows[0].selection.canvas.background | |
| 03 | return graphic.userData[key] | |
| 04 | } | |
| 05 | getCanvasUserDataForKey('SKU') | |
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.
DISCLAIMER