Open topic with navigation

Symbols

Symbols are compound objects that you can create from basic components and parameterize by adding properties. Typical uses of symbols include:

• Callouts: Symbols can provide a standardized way of displaying callouts containing data about objects of interest.
• Repeaters: Symbols can be visual templates for displaying iterative data.
• Map markers: Map components require a symbol to display when marking locations.

The following video demonstrates the basics of defining symbols.

Creating Symbols

To create a symbol:

1. Add and style the desired components.
2. Group the components.
3. Right-click the group, choose Convert to Symbol, and specify a name.

Shortcut: Click the Convert to Symbol button in the right sidebar, as shown in the following figure:

To verify that the symbol is created, check the Symbols tab, which in the lower right corner of the Solution Builder main window. After the symbol is created, you can delete the group from the main window.

To edit a symbol, right-click it in the Symbols tab and choose Edit. A small layout dialog containing the symbol is displayed. Make your changes and click OK.

Adding Properties to Symbols

To dynamically change the appearance of symbols or the data that they display, you can add properties to symbols and bind them to properties of the components. To add properties to symbols, perform the following steps:

1. In the Symbols panel, select the symbol and select Modify > Edit Properties. The Symbol Parameters dialog is displayed. The left panel contains a list of data types and organizational elements. The right panel contains the symbol's current parameters.
2. To add parameters to the symbol, drag the desired type to the right pane.
3. To assign a name to the parameter, double-click the label and type the desired name.
4. (Optional) To specify a default value for the parameter, enter the desired value in the field.

The following video shows how to bind a symbol parameter to a property of one of its components.

Options for symbol parameters are as follows:

• bool: TRUE or FALSE.
• daterange: A start- and end-date pair.
• enum: A list of values. When an instance of the symbol is displayed, values from the list can be selected in the symbol instance's properties. To enter the list when defining the property, right-click the field.
• fill: Solid color or pattern to be applied.
• hbox: A horizontal row of properties. Drag and drop the row first, and then drop properties within it. Right-click the purple box to delete the row and all properties inside it.
• nodepath: A path to a data node.
• number: A floating-point number property.
• path: A path to a resource in the Solution Builder project.
• section: A collapsible Property Inspector section. The Symbol property always appears in the Symbol section.
• string: A one-line string property. Does not support line breaks.
• tabledata: A table.
• textarea: A text block. Supports line breaks.
• trigger: A Solution Builder trigger.
• vbox: A vertical column of properties. To create columns, add an hbox, then add a vbox to the hbox and drag fields into the vbox.

To control how a symbol's properties are displayed in the Property Inspector, you can add sections, rows (hboxes) and columns (vboxes) as shown in the following figures

Using Symbols

Symbol definitions are stored in .dg5 files, which define a single page in a project. To associate a symbol with a component that uses it (for example, to specify the symbol to be used as a marker on a map layer), set the component's Symbol property to a path pointing to the symbol definition, omitting the .dg5 extension. If the symbol is defined on the page where you are using it, simply specify the name of the symbol. If the symbol is located in the project's palette folder, the path syntax is palette/[subfolders, if any]/[page name]:[symbol name]. When specifying the page name, omit the .dg5 extension. For example, the correct path for a symbol named "mySym" that is defined in the palette/widgets.dg5 page is palette/widgets:mySym. If the symbol is defined in a project that was imported into the currently-open project's lib folder, the path syntax is lib/[project]/palette/[subfolders, if any]/[page name]:[symbol name]. For example, the correct path for a widget named "Fan East" that is defined in a page named Equipment.dg5 in the imported project named "HVAC" is lib/HVAC2/palette/Equipment:Fan East.

Callouts

A typical use for a symbol is to implement callouts. A callout is a small component that identifies or provides additional information about a component that is displayed in a layout. Callouts are implemented by associating the component with a symbol that is configured to display the desired information, either statically or when a user action such as clicking or mouseover triggers display. Callouts can also be used to create other effects, such as drop-down menus and pop-up dialogs.

To create a simple static callout for a single object, create a symbol with the desired content and styling and configure the objects Callout properties to display the symbol as desired. The following brief video shows you how.

To control when a callout is displayed and hidden, you bind its Show Trigger and Hide Trigger properties to the desired events. For example, to create a callout that is displayed when the user clicks a component and hidden when the user clicks its Close button, perform the following steps

First define the symbol that will be displayed as a callout.

1. Add a group to the stage and set its Layout property to vertical.
2. Add two text components to the group: a top one containing an "x" for the Close button and a bottom one containing information about the component. Style as desired. Example:
   
   
3. Select the group and convert it to a symbol. Verify that the new symbol is listed in the Symbols pane (behind the Outline), then delete it from stage.
4. In the Symbols pane, right-click the new symbol and choose Edit symbol.
5. From the main menu, choose Modify > Edit Properties. The Symbol Parameters dialog is displayed.
6. Add a trigger parameter to the symbol by dragging "trigger" from the Panel list on the left into the dialog.
7. Leaving the Symbol Parameters dialog displayed, go to the Outline, expand the symbol and select its first text component (the one containing "x").
8. Go to the Actions pane and click the expander. Bind the onClick event to the trigger that you added to the Symbol Parameters dialog.
9. Close the Symbol Parameters dialog and save your changes to the symbol.

Next, create an image component and configure its Callout properties to display the callout when the user clicks the image and to hide the callout when the user clicks the Close button, as follows:

1. Add an image component to the Stage and set its Image URL property to display the desired image file.
2. In the image components' Callout properties, set Symbol to the name of your symbol and choose Events.
3. With the image component selected, go to Actions and bind onClick to the Callout Show Trigger property, then close the binding dialog.
4. In Outline, expand the image component and choose its callout child.
5. In the callout's Symbol properties, click the trigger's blue dot and choose Bind. The binding dialog for the trigger is displayed.
6. Select the image component and bind the callout trigger to the image component's Hide Trigger callout property.

Go into Preview mode and verify that the callout displays when you click the image component and is hidden when you click the callout's Close button. The following video illustrates the process.