Differences

This shows you the differences between two versions of the page.

--- dglux5_wiki:widgets_and_property_inspector:components:symbols:home [2019/07/17 19:17]
+++ dglux5_wiki:widgets_and_property_inspector:components:symbols:home [2021/09/20 15:03] (current)
@@ Line 1: / Line 1: @@
+{{indexmenu_n>12}}
+====== 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|create a symbol]] and to enter the special symbol editing mode that lets you [[#edit_a_symbol|edit a symbol]].
+You can save symbols to the [[dglux5_wiki:workspace_and_workflow:panels_and_menus:widget_palette|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 [[dglux5_wiki:widgets_and_property_inspector:repeaters:home|repeaters]] and [[dglux5_wiki:widgets_and_property_inspector:callouts:home|callouts]].
+{{:dglux5_wiki:widgets_and_property_inspector:dglux5_components_symbol_0.png?direct|}}\\
+//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: [[dglux5_wiki:workspace_and_workflow:panels_and_menus:widget_palette|Widget Palette]].
+----
+===== Video Tutorial: Introduction to Symbols in HTML5 Application Development DGLux5 =====
+<html>
+<left>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/tzO8iLb1Rfs" frameborder="0" allowfullscreen></iframe>
+</left>
+</html>
+More video tutorials are [[http://dglogik.com/videos|here]].
+----
+===== Create a Symbol =====
+You can create a symbol based on a [[dglux5_wiki:widgets_and_property_inspector:components:group:home|group]] or a non-group [[dglux5_wiki:widgets_and_property_inspector:essentials:home|component]].
+To create a symbol:
+  - <WRAP>In the [[dglux5_wiki:workspace_and_workflow:panels_and_menus:outline|Outline]] or [[dglux5_wiki:workspace_and_workflow:panels_and_menus:document_window|Document window]], select the [[dglux5_wiki:widgets_and_property_inspector:components:group:home|group]] or the non-group [[dglux5_wiki:widgets_and_property_inspector:essentials:home|component]].
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_3.png?direct|}}</WRAP>
+  - <WRAP>Right-click the group or the non-group component, and select {{:dglux5_wiki:27_icn-tool-convert-to-symbol.png?nolink|}} **Convert to Symbol**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_4.png?direct|}}</WRAP>
+  - <WRAP>Give the symbol a name, and click **OK**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_5.png?direct|}}</WRAP>
+  - <WRAP>Look at the Outline. One instance of the symbol that you created has replaced the group or the non-group component that you converted.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_6.png?direct|}}
+<WRAP info>===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.</WRAP></WRAP>
+  - <WRAP>Click the **Symbols** tab to open the [[dglux5_wiki:workspace_and_workflow:workspace_basics:home|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.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_7.png?direct|}}
+</WRAP>
+<WRAP info>===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.
+</WRAP>
+----
+===== Add a Symbol Instance to the Page =====
+To add an instance of a symbol to the page:
+  - <WRAP>Click the **Symbols** tab to open the [[dglux5_wiki:workspace_and_workflow:workspace_basics:home|Symbols panel]]. Then, find the symbol in the list.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_7.png?direct|}}</WRAP>
+  - <WRAP>Drag the name of the symbol to the [[dglux5_wiki:workspace_and_workflow:panels_and_menus:document_window|Document window]].
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_8.png?direct|}}
+An instance of the symbol appears on the Stage.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_14.png?direct|}}</WRAP>
+----
+===== 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 [[dglux5_wiki:workspace_and_workflow:panels_and_menus:document_window|Document window]] and in a pop-up.
+==== Document Window Method ====
+To edit a symbol in the Document window:
+  - <WRAP>Enter symbol editing mode using one of these methods:
+    * <WRAP>Select any instance of the symbol, and then double-click that instance in the Document window.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_9.png?direct|}}</WRAP>
+    * <WRAP>Right-click any instance of the symbol in the Document window or [[dglux5_wiki:workspace_and_workflow:panels_and_menus:outline|Outline]], and choose {{:dglux5_wiki:22_icn-state-edit.png?nolink|}} **Edit Symbol**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_10.png?direct|}}</WRAP>
+    * Open the [[#use_symbol_parameters|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.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_11.png?direct|}}</WRAP>
+  - <WRAP>Use the Outline and [[dglux5_wiki:widgets_and_property_inspector:property_inspector:home|Property Inspector]] to edit the objects that are inside the symbol.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_12.png?direct|}}</WRAP>
+  - <WRAP>To exit symbol editing mode, double-click the Document window outside of the symbol.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_13.png?direct|}}
+Other instances of the symbol reflect the changes that you made.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_14.png?direct|}}</WRAP>
+==== Pop-Up Method ====
+To edit a symbol in a pop-up:
+  - <WRAP>To enter symbol editing mode, in the Symbols panel, right-click the symbol, and choose {{:dglux5_wiki:22_icn-state-edit.png?nolink|}} **Edit**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_15.png?direct|}}
+A pop-up opens that contains the symbol.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_16.png?direct|}}</WRAP>
+  - <WRAP>Use the Outline and [[dglux5_wiki:widgets_and_property_inspector:property_inspector:home|Property Inspector]] to edit the objects that are inside the symbol.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_17.png?direct|}}</WRAP>
+  - <WRAP>Click **Apply** to apply your changes to the symbol instances and continue editing.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_18.png?direct|}}</WRAP>
+  - 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 [[#add_symbol_parameters|parameters]].
+To duplicate a symbol:
+  - <WRAP>Open the [[dglux5_wiki:workspace_and_workflow:workspace_basics:home|Symbols panel]].
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_0.png?direct|}}</WRAP>
+  - <WRAP>Right-click the symbol, and select {{:dglux5_wiki:93_icn-pi-duplicate.png?nolink|}} **Duplicate**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_1.png?direct|}}
+The duplicate symbol now appears in the Symbols panel. You can rename it by right-clicking and selecting **Rename**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_2.png?direct|}}</WRAP>
+----
+===== 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 [[dglux5_wiki:bindings:home|bind]] symbol parameters to properties of objects that are inside the symbol.
+To use symbol parameters:
+  - <WRAP>Open the Symbol Parameters dialog using one of these methods:
+    - <WRAP>Select the symbol in the [[dglux5_wiki:workspace_and_workflow:workspace_basics:home|Symbols panel]], and select **Modify** > **Edit Properties**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_19.png?direct|}}</WRAP>
+    - <WRAP>Open the symbol in [[#edit_a_symbol|edit mode]], and select **Modify** > **Edit Properties**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_20.png?direct|}}</WRAP>
+    - <WRAP>Right-click an instance of the symbol in the document window or stage, and select **Edit Properties**.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_21.png?direct|}}</WRAP>
+The Symbol Parameters dialog appears.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_22.png?direct|}}
+The left panel contains a list of data types and organizational elements. The right panel contains the symbol's current parameters.</WRAP>
+  - <WRAP>Drag the relevant elements from the left panel into the right panel.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_23.png?direct|}}</WRAP>
+  - <WRAP>In the right panel, double-click the label of each parameter to rename it.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_24.png?direct|}}</WRAP>
+  - <WRAP>If you want, set a default value for each parameter by entering the values in this pop-up.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_25.png?direct|}}</WRAP>
+  - Create [[dglux5_wiki:bindings:home|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.
+    - <WRAP>Drag the blue dot to the relevant property of the object.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_26.png?direct|}}</WRAP>
+  - Exit symbol editing mode by double-clicking the Document window or clicking OK in the symbol editing pop-up.
+  - <WRAP>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.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_27.png?direct|}}</WRAP>
+  - <WRAP>Edit the properties in the **Symbol** property group.
+Your edits affect each instance of the symbol individually.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_28.png?direct|}}</WRAP>
+<WRAP tip>===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.
+</WRAP>
+==== Items in the Symbol Parameters Dialog ====
+These items are available for creating symbol parameters.
+=== section ===
+A collapsible Property Inspector section. The [[dglux5_wiki:widgets_and_property_inspector:property_inspector:symbol:home|Symbol]] property always appears in the **Symbol** section.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_31.png?direct|}}\\
+//Dragging a string property into a section//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_29.png?direct|}}\\
+//Sections in the Symbol Parameters dialog//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_30.png?direct|}}\\
+//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.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_32.png?direct|}}\\
+//Dragging a boolean property into an hbox//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_33.png?direct|}}\\
+//hboxes in the Symbol Parameters dialog//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_34.png?direct|}}\\
+//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.
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_35.png?direct|}}\\
+//Dragging a vbox into an hbox//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_36.png?direct|}}\\
+//Dragging a boolean property into a vbox//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_37.png?direct|}}\\
+//vboxes in the Symbol Parameters dialog//
+{{:dglux5_wiki:widgets_and_property_inspector:components:symbols:dglux5_symbol_38.png?direct|}}\\
+//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 [[dglux5_wiki:workspace_and_workflow:projects_and_files:home|project]].
+=== daterange ===
+A DGLux5 [[dglux5_wiki:widgets_and_property_inspector:property_inspector:daterange:home|date range]].
+=== trigger ===
+A DGLux5 [[dglux5_wiki:bindings:#binding_from_an_event_property_to_a_trigger_property|trigger]].
+=== fill ===
+A DGLux5 [[dglux5_wiki:widgets_and_property_inspector:property_inspector:allcomponents:fill_stroke|fill]].
+=== tabledata ===
+A DGLux5 [[dglux5_wiki:dataflow:working_with_tables:home|table]].
+=== nodepath ===
+A path to a [[dglux5_wiki:workspace_and_workflow:panels_and_menus:data_panel|data node]].
+----
+===== Use a Symbol across Pages and Projects =====
+You can re-use a symbol across pages and projects by saving it as a [[dglux5_wiki:workspace_and_workflow:panels_and_menus:widget_palette#create_your_own_widget_library|widget]].
+----
+===== Delete a Symbol =====
+To delete a symbol:
+  - In the **Symbols** panel behind the Outline, click the symbol.
+  - Click {{:dglux5_wiki:24_icn-pi-trash.png?nolink|}} **Delete**.
+----
+====== ======
+{{page>dglux5_wiki:widgets_and_property_inspector:property_inspector:symbol:home&firstseconly&noreadmore}}
+----
+===== More Resources =====
+Videos:
+  * [[https://vimeo.com/112853289 | Introduction to Symbols]]
+  * [[https://vimeo.com/117195428 | Data Mapping / Data Actions with Symbols]]
+  * [[https://vimeo.com/116305987 | Drive Relativized Graphic Through Repeaters]]
+  * [[http://www.dglogik.com/index.php/videos/customize-column-charts | Customize Column Chart Series]]
+  * [[http://www.dglogik.com/index.php/videos/introduction-to-callouts | Introduction to Callouts]]
+  * [[http://www.dglogik.com/index.php/videos/custom-triggers-with-callouts | Custom Triggers with Callouts]]
+Community Forum discussions:
+  * [[https://muut.com/dglogik#!/dglux5:saving-a-symbol-as-a-widget|Saving a symbol as a widget in the palette]]
+  * [[https://muut.com/dglogik#!/faq:symbols-duplication|Creating a repeater]]
+----
+<WRAP left>[[dglux5_wiki:widgets_and_property_inspector:components:heat_map:home|Previous: Heat Map]]</WRAP>
+<WRAP right>[[dglux5_wiki:widgets_and_property_inspector:components:calendar:home|Next: Calendar]]</WRAP>