Using Data Variables

Data variables have long been part of OmniGraffle; however, there is a little-known variable, <%UserData%> which gives OmniGraffle Pro users access to project-level details and metadata entered into the Note inspector.

This chapter provides you with a basic overview of the data variables available in OmniGraffle Standard, and shows OmniGraffle Pro users how to go beyond the basics.

1. Select the Text tool.
2. Click on the canvas to create a text object.

3. Enter the following:

   <%Canvas%>

4. Press the Escape (Esc) key to accept the variable as the text.

When you press the Escape key, the variable displays the name of the current canvas. If you double-click on the text object, OmniGraffle displays the <%Canvas%> variable.

If you change the name of the canvas in the Sidebar (or in the Canvas Data inspector, if you have OmniGraffle Pro), the variable instantly updates to reflect the new canvas name.

The core set of data variables include are listed in Table 1.

• Current Date (<%Date%>) — inserts the current date. This particularly handy when you want to “stamp” a document you’re exporting or printing with today’s date.

• Document Creation Date (<%CreationDate%>) — inserts the date that the document was originally created, according to the document XML.

• Document Modification Date (<%ModificationDate%>) — inserts the date that the document was last saved, according to the document XML.

If you are using one of the date variables, you can customize the format of the date using the variables listed in Table 2.

For example, to get a date such as 2016-10-05 08:37:30 -0700Z, you could use the following variable string:

<%date %Y-%m-%d %H:%M:%S %zZ %>

For example, let’s say that you are creating a floorplan of your house or apartment. In the Units inspector, you can set the Ruler Units to feet (ft), and the Scale to something like 1 in = 1 ft to get accurate (to-scale) floorplans, using lines and the Line Length variable to display the dimensions.

Every field of the Document Data inspector has a like-named variable. This also includes the metadata pop-up menu, which lets you add details about the project, including a list of Authors, Organizations, Languages, Keywords, or Projects. And while the metadata you enter in the rows beneath the pop-up menu can be singular, you can enter as many as you’d like.

The Document Data inspector’s variables are not accessible via the Edit ▸ Insert Variable menu, and are shown and listed here:

• <%Subject%> — Displays the Subject of the field.

• <%Copyright%> — Books and software are protected by copyrights, and you can label your projects with a similar copyright statement.

• <%Version%> — If needed, enter a version number for your project. This can be helpful for working on projects that are synced and shared among team members by having them iterate the version string whenever a change is made.

• <%Description%> — Enter a brief description about the project.

• <%Comments%> — Use the Comments field to enter a little more information about the project; more than you would enter in the Description field.

• <%Authors%> — Here, "Authors" is used loosely to define the people associated with the project. The people you list in the rows underneath can be designers, engineers, architects, and so on.

• <%Organizations%> — This could be the name of your company or the name of the client this project is related to.

• <%Languages%> — Here you can specify the languages within the project. For example, if you are prototyping an app that will be localized in other languages, you can list those here.

• <%Keywords%> — You can add metadata to your projects when Keywords is selected in the pop-up menu. There’s no limit to the number of keywords you can assign to your project. When you use <%Keywords%>, each keyword you assign to a project is displayed on its own line.

• <%Projects%> — Used for assigning a name to the project you are working on. You can assign more than one project name in the list; each one is displayed on its own line when the variable is called.

Using the UserData Variable to Access Key-Value Pairs (PRO)

If you have OmniGraffle Pro, you can enter details about specific objects in your projects using the Note inspector, and then—with the use of variables—apply that information to the objects on the canvas.

The Note inspector looks fairly innocuous, there’s the Name field at the top which is bound to the <%GraphicName%> variable. There’s a Note field, where you can enter information about the object. The information you enter here is displayed whenever you hover over that object with the mouse. (There is no variable for accessing the Note field.)

The <%GraphicName%> variable displays the name of the object, and is not dependent on having OmniGraffle Pro. If you have OmniGraffle Standard, you can assign names to objects in the Sidebar instead of in the Note inspector.

To learn more about naming objects in the Sidebar, see Changing Canvas, Layer, and Object Names in the Sidebar, earlier in this guide.

Accessing Key-Value Pairs with the UserData Variable

At the bottom of the Note inspector is an area where you can assign key-value pairs to individual objects in your project. A key-value pair is similar to the listings you find in a dictionary, where the word you look up is the key and its definition is the value. You can use the <%UserData%> variable to call upon the key and use its value as the label of an object or line.

Using the previous image as an example, bucket02 is the key, and Article Bucket is the value. To display the value (Article Bucket) as the label for an object, you would use the following variable:

<%UserData bucket02%>

Using Multiple Key-Value Pairs on the Same Object

You don’t need to limit the number of key-value pairs you assign to an object to just one pair. For example, if you are working on a website design, you might want to devote a canvas in your project to hold detailed color swatches you plan to use on the site. You can then use the keys to identify color spaces, and the values to display the appropriate color value.

The variables used as the object labels are as follows:

<%GraphicName%>

HEX: <%UserData HEX%>

RGB: <%UserData R%>,<%UserData G%>,<%UserData B%>

In this example, create a single object on the canvas, add the variables (shown above) as the text label for the object, and then use the Note inspector to assign the hexadecimal and RGB color values as key-value pairs. With those details in place, duplicate the swatch as many times as you need, and align them using the Smart Guides or with the Alignment inspector. Finally, use the Fill inspector to change the fill color for each object, and then apply the color values in the Note inspector.

A similar technique could also be used to create a highly detailed network diagram. For example, you could note the IP addresses for servers, switches, and firewalls, the make and model of each piece of gear, the location of the equipment, and more.

Look for ways to leverage key-value pairs and call upon them using the <%UserData [key]%> variable.

Similarly, some variables allow you to nest them together within a single set of angle brackets. For example, you can combine the Page Number and Total Pages variables together as follows to display the range of pages within your project:

<%# of %TotalPages %>

Not all variables, however, can be nested; for example, <%CanvasNumber of %TotalCanvases %> does not work. Instead, you’ll have to chain those together as follows:

<%CanvasNumber%> of <%TotalCanvases%>