Symbol
The symbol component is a container that takes a path to a DGLux5 symbol that you have created or imported. Edits that you make in one place affect all instances of the symbol.
There are several ways to create a symbol and to enter the special symbol editing mode that lets you edit a symbol.
You can save symbols to the widget palette, or import symbols to the lib folder, to use them in different pages, projects, and user accounts. Unlike other widgets in the widget palette, editing a symbol that you drag from the widget palette affects the source symbol and all other instances, regardless of project. This is true only if you have can edit access to the symbol's source file.
Symbols are required when you create repeaters and callouts.
Four instances of a symbol component in DGLux5
Symbol Paths
If the symbol and the symbol component are located in the same DGLux5 page, the path is the name of the symbol.
If the symbol is located in the project's palette folder, the path is palette/[folders, if any]/[page name]:[symbol name]. The page name does not use a .dg5 extension. For example, palette/widgets:sym is a valid path, where palette/widgets.dg5 is the file and sym is the symbol name.
If the symbol is located in a project in this project's lib folder, the path is lib/[project]/palette/[folders, if any]/[page name]:[symbol name]. For example, lib/HVAC2/palette/Equipment:Fan East is a valid path, where Equipment.dg5 is the file, and Fan East is the symbol name.
See also: Widget Palette.
Video Tutorial: Introduction to Symbols in HTML5 Application Development DGLux5
Create a Symbol
You can create a symbol based on a group or a non-group component.
To create a symbol:
In the Outline or Document window, select the group or the non-group component.
Right-click the group or the non-group component, and select
Convert to Symbol.
Give the symbol a name, and click OK.
Look at the Outline. One instance of the symbol that you created has replaced the group or the non-group component that you converted.
Note
The symbol instance that appears when you first create a symbol has a name matching the unique name of the object that you converted to a symbol. If you want to rename the instance to make it clear it is a symbol instance, double-click the instance in the outline and rename it.
Click the Symbols tab to open the Symbols panel.
The Symbols panel contains a list of the symbols in this page. Click the symbol that you created to see a preview of it.
Note
After you have converted a group to a symbol, you cannot convert it back to a group. However, if you convert an object to a symbol by mistake, you can:
- Edit the objects that are inside the symbol by entering the symbol editing mode and changing properties.
- Copy the objects that are inside the symbol and paste them outside the symbol.
Add a Symbol Instance to the Page
To add an instance of a symbol to the page:
Click the Symbols tab to open the Symbols panel. Then, find the symbol in the list.
Edit a Symbol
To edit a symbol, you enter a special symbol editing mode. While in this mode, you can edit symbols only. Changes that you make in symbol editing mode affect all instances of the symbol.
You can edit symbols in two places: in the Document window and in a pop-up.
Document Window Method
To edit a symbol in the Document window:
Enter symbol editing mode using one of these methods:
Select any instance of the symbol, and then double-click that instance in the Document window.
Right-click any instance of the symbol in the Document window or Outline, and choose
Edit Symbol.
- Open the Symbol Parameters dialog.
When you are in symbol editing mode, items the Document window become gray, and the Outline changes to show the symbol component instead of the Stage contents.
Use the Outline and Property Inspector to edit the objects that are inside the symbol.
To exit symbol editing mode, double-click the Document window outside of the symbol.
Other instances of the symbol reflect the changes that you made.
Pop-Up Method
To edit a symbol in a pop-up:
To enter symbol editing mode, in the Symbols panel, right-click the symbol, and choose
Edit.
A pop-up opens that contains the symbol.
Use the Outline and Property Inspector to edit the objects that are inside the symbol.
Click Apply to apply your changes to the symbol instances and continue editing.
- When you are finished, click OK to close the pop-up.
Duplicate a Symbol
Sometimes, you might want to duplicate a symbol so that you can create a new symbol based on the old one. Duplicating a symbol copies all symbol parameters.
To duplicate a symbol:
Open the Symbols panel.
Right-click the symbol, and select
Duplicate.
The duplicate symbol now appears in the Symbols panel. You can rename it by right-clicking and selecting Rename.
Use Symbol Parameters
Sometimes, you might not want all instances of a symbol to be identical. Instead, you might want some properties of the objects inside the symbol to vary based on circumstances. You can do this by creating parameters for the symbol.
A symbol parameter is a special kind of property that you define. Symbol parameters can have different values for each instance of the symbol. After you define them, parameters appear in the Property Inspector. You can bind symbol parameters to properties of objects that are inside the symbol.
To use symbol parameters:
Open the Symbol Parameters dialog using one of these methods:
Select the symbol in the Symbols panel, and select Modify > Edit Properties.
Open the symbol in edit mode, and select Modify > Edit Properties.
Right-click an instance of the symbol in the document window or stage, and select Edit Properties.
The Symbol Parameters dialog appears.
The left panel contains a list of data types and organizational elements. The right panel contains the symbol's current parameters.
Drag the relevant elements from the left panel into the right panel.
In the right panel, double-click the label of each parameter to rename it.
If you want, set a default value for each parameter by entering the values in this pop-up.
- Create bindings from each parameter to the relevant property:
- In the Outline, select the relevant object within the symbol.
- In the Symbol Parameters dialog, hover over the property until you see a blue dot.
Drag the blue dot to the relevant property of the object.
- Exit symbol editing mode by double-clicking the Document window or clicking OK in the symbol editing pop-up.
Select an instance of the symbol, and in the Property Inspector, look at the Symbol property group.
The parameters that you created appear as editable properties.
Edit the properties in the Symbol property group.
Your edits affect each instance of the symbol individually.
Tips
- To delete a symbol parameter, right-click it in the Symbol Parameters dialog and select Delete.
- To create a collapsible section within the symbol properties, drag the section item from the left panel to the right panel, and then drag properties into the section.
- To create a row of properties, add the hbox item and then drag properties into the small, shaded box that appears.
- To create columns of properties, add the hbox item, then add vbox items within it, and add properties to the small, shaded vbox items that appear.
- To make a parameter default, right-click the parameter in the Symbols Parameter dialog and select Make Default. A default parameter is the parameter bound to when a binding is created by dragging and dropping on the symbol itself rather than on an individual property.
Items in the Symbol Parameters Dialog
These items are available for creating symbol parameters.
section
A collapsible Property Inspector section. The Symbol property always appears in the Symbol section.
Dragging a string property into a section
Sections in the Symbol Parameters dialog
Sections in the Property Inspector
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.
Dragging a boolean property into an hbox
hboxes in the Symbol Parameters dialog
hboxes in the Property Inspector
vbox
A vertical column of properties. Drag and drop an hbox first. Then drag and drop a vbox into the hbox. Finally, drag and drop data types into the vbox.
Dragging a vbox into an hbox
Dragging a boolean property into a vbox
vboxes in the Symbol Parameters dialog
vboxes in the Property Inspector
number
A floating-point number property.
string
A string property. Does not support line breaks.
textarea
A text property. Supports line breaks.
bool
A boolean value. Can be TRUE or FALSE.
enum
An enum property. Right-click the property to create a list. Items from the list can be selected in the symbol instance's properties.
path
A path in this DGLux5 project.
daterange
A DGLux5 date range.
trigger
A DGLux5 trigger.
fill
A DGLux5 fill.
tabledata
A DGLux5 table.
nodepath
A path to a data node.
Use a Symbol across Pages and Projects
You can re-use a symbol across pages and projects by saving it as a widget.
Delete a Symbol
To delete a symbol:
- In the Symbols panel behind the Outline, click the symbol.
- Click
Delete.
Symbol Properties
These properties affect the symbol component. By default, there is only one property for a symbol. To create more properties for a particular symbol, open the Edit Properties dialog for that symbol.
For a guide to using symbols, see Symbols.
Symbol components are also affected by Common Properties and by custom parameters that you define.
The Symbol properties in the Property Inspector
More Resources
Videos:
Community Forum discussions: