metasys ui custom symbols technical bulletin · notation (json) layouts of the symbols, the...

Building Technologies & Solutions

www.johnsoncontrols.com

2020-02-24

Metasys UI Custom Symbols TechnicalBulletin

LIT-12013054

Release 10.1

ContentsContentsDocument introduction................................................................................................................. 3

Summary of changes..................................................................................................................... 3

Metasys UI Custom Symbols overview......................................................................................... 3

Custom Symbols creation workflow............................................................................................ 4

Folder structure................................................................................................................................... 4

Custom Symbols package structure....................................................................................... 7

Custom Symbols – file details.................................................................................................. 7

Symbol package JSON............................................................................................................ 10

Creating a new symbol..................................................................................................................... 11

Exporting a symbol to SVG.................................................................................................... 11

Refining SVG for use as a Custom Symbol.......................................................................... 11

Creating thumbnails............................................................................................................... 13

Creating supporting data for the symbol library.......................................................................... 14

Custom Symbol Library JSON (mandatory step)................................................................. 14

Creating language support.............................................................................................................. 16

Creating language JSON........................................................................................................ 16

Creating the property panel integration........................................................................................ 17

Creating a JSON entry (mandatory step)............................................................................. 17

Sample JSON for different property types........................................................................... 19

Creating dropdown property JSON....................................................................................... 21

Custom Behavior............................................................................................................................... 23

Creating JSON for Custom Behavior – csEditorMetaData.json.......................................... 23

Creating JSON for Custom Behavior – csSymbolMapData.json........................................ 24

Sample csSymbolMapData.json............................................................................................ 25

Symbol animation.............................................................................................................................. 26

Adding animation logic.......................................................................................................... 26

Two-state animation............................................................................................................... 27

Multistate animation.............................................................................................................. 28

Metasys UI Custom Symbols Technical Bulletin i

Contents

Multistage animation............................................................................................................. 29

Fill and stroke color animation.............................................................................................. 33

Importing Custom Symbols into Metasys UI............................................................................. 34

Metasys UI Custom Symbols Technical Bulletin ii

Document introductionThis document describes how to create Custom Symbols, which you can import in Metasys® UIOnline and Metasys UI Offline. The document outlines a step-by-step procedure to create newsymbols, including the configuration of Scalable Vector Graphics (SVG) and JavaScript ObjectNotation (JSON) layouts of the symbols, the creation of a mandatory folder structure, and thesetting of the necessary boundaries and protocols for the folder structure. It also covers the basicMetasys UI Online import steps.This document is intended for Metasys UI users who are familiar with symbol creation, and itassumes a working knowledge of web services and any applications you intend to interface within the Metasys network. Follow the process outlined in this document before you import CustomSymbols in Metasys UI Online and Metasys UI Offline. Refer to the Working with Symbols section inMetasys UI Online Help (LIT-12011953) or Metasys UI Offline Help (LIT-12012116) for more informationabout how to import symbols.

Summary of changesThe following information is new or revised:

• Updated Folder structure with figures.

• Provided additional examples throughout.

• Added Importing Custom Symbols into Metasys UI.

Metasys UI Custom Symbols overviewThe following is an overview of the steps required to generate Custom Symbols:

1. Create the Folder structure.

2. Create a new symbol.

3. Create supporting data for the symbol library.

4. Create language support.

5. Create the Property panel integration.

6. Create Custom Behavior.

7. Create the Default Animation.

8. Importing Custom Symbols into Metasys UI

The following sections outline these steps in detail with examples and a sample structure creation.

3Metasys UI Custom Symbols Technical Bulletin

Custom Symbols creation workflowComplete the following workflow to create Custom Symbols for a Metasys UI import.

Folder structureThe current implementation of Custom Symbols supports a three-level folder structure. Thefollowing image provides an overview of the folder structure.

Figure 1: Folder structure overview

Root folder: When you import the Custom Symbols .zip package in the Metasys UI, it is listed asCustom Symbols underneath Basic Symbols in the Symbols pane of the Graphics Editor. Upondrill-down, further layers of Custom Symbols open up.Level 1: This level contains folders and symbols such as region name folders, the Symbols folder,and several .json files, amongst others. In the Metasys UI, expand the Custom Symbols accordionto open the first level folders along with the symbols consistent with the zipped package that youimported.

Metasys UI Custom Symbols Technical Bulletin4

Figure 2: Level 1


Level 2: Expand the region name folders and the Symbols folder to see the Level 2 content. In theMetasys UI, expand the Level 1 folders to open the Level 2 folders along with the symbols consistentwith the zipped package that you imported.

Figure 3: Level 2


Custom Symbols package structureCreate a Custom Symbols package structure as follows:Create under the root folder:

• symbol-packs.json: This JSON defines the first category level that you want to create. SeeSymbol package JSON for more details.

Note: Creating the symbol-packs.json is a mandatory step, but it is optional to defineregion folders, or any other /<Level 1> folders, in symbol-packs.json.

• /<Level 1>: Make sure that the name of this Level 1 folder is identical to the name defined insymbol-packs.json.

• <Symbol data>: This is the list of files required for you to integrate Custom Symbols into thesystem directly under the root folder:

- /symbol/thumbnail/.png

- /symbol/.html

- Supporting JSON files for symbol library, property panel, language, and custom behavior.

- Supporting .js. for animation

Create under Level 1:

• <Symbol data>: This is the list of files required for you to integrate Custom Symbols into thesystem directly under <Level 1>:

- /symbol/thumbnail/.png

- /symbol/.html

- Supporting JSON files for symbol library, language, property panel, and custom behaviorfor all the symbols in the current level and all levels under it.

- Supporting .js. for animation for all the symbols in the current level and all levels under it.

• /<Level 2>: The name of this Level 2 folder should be the name that the user wants to display inthe Symbol Library.

- .html – for symbol SVG

- .png – for thumbnail

Custom Symbols – file detailsThe following table describes the files that are required for Level 1 and Level 2 folders:Table 1: File detailsFile name DescriptioncsAnimations.js Used to apply animation to Custom Symbols.csEditorMetaData.json Used to configure Custom Behavior in the Graphics

Editor.csPropertyLibrary.json Used to configure symbol properties.


Table 1: File detailsFile name DescriptioncsSVGModification.json Used to apply the Property panel configuration to the

symbol.csSymbolMapData.json Used to apply fill/stroke-related Custom Behavior

effects in the Graphics Viewer.customSymbolLibrary.json Used for symbol display in the Graphic Editor library.<language>.json Used for language strings. Each language has separate

JSON files. See Creating language support for moredetails.

The following is the sample file structure of Level 1 and Level 2 folders:

• regionName/

- symbolsCategoryFolder/

- Symbol/

- thumbnails/

symbol1.png

symbol2.png

symbol3.png

- symbol1.html

- symbol2.html

- symbol3.html

- csAnimations.js

- csEditorMetaData.json

- csPropertyLibrary.json

- csSVGModification.json

- csSymbolMapData.json

- customSymbolLibrary.json

- en-us.json

- ja.json


Figure 4: Sample file structure


Symbol package JSONAfter you create your symbols and region folders, create the symbol-packs.json file. This file actsas a registry of the region folders that contain your Custom Symbols. Only folders listed in this fileare inspected for Custom Symbols that you want to make available in the Graphics Editor library.The structure of this file is an array of strings, where each entry is one of the region folder names.For example, if region folders for Europe and Asia are defined in this package, the contents of thisfile should be:

["Europe", "Asia"]


Creating a new symbolExporting a symbol to SVGCreate your graphic in any tool that supports an SVG export, such as Adobe® Illustrator®,Microsoft® Visio®, Google® SVG editors, or CorelDRAW®.To export a symbol to SVG, complete the following steps:

1. Use shapes or images to create your graphics.

2. Export the graphics.

3. Select SVG as the file format.

4. If you used any images while creating the SVG, click the Embed option when a prompt displays.

5. Click Export.

6. Select a folder location to save the file.

7. Click Save.

Refining SVG for use as a Custom SymbolAfter you create the SVG file, complete the following steps to refine it:

1. Open the SVG file in any text editor, such as Notepad++, and remove all lines that containcommented code, that is blocks beginning with , to optimize the symbolsize. Use the following checklist to refine your SVG file in Notepad++:

- Does the symbol contain CSS style data?

- Yes: Convert style data to SVG attributes. See Table 2 for details.

- No: No action required

- Does the symbol contain width, height and viewBox attributes in an <svg> tag?

- Yes: No action required

- No: Add attributes (width=“WIDTH px” height=“HEIGHT px” viewBox=“0 0WIDTH HEIGHT”, where WIDTH and HEIGHT are the required width and heightof the symbol in pixels)

- Does the symbol contain an overflow attribute?

- Yes: Remove the attribute and its value


- Does the symbol contain <title> tags?

- Yes: Remove all title tags

2. Complete the sub-steps in the following table to convert inline CSS styles to SVG attributes, ifthe styles are stored in this format:<style>classname { property : value }</style>

Table 2: Convert inline CSS styles to SVG attributesStep Description Example1. Convert properties into SVG

attributesCSS : property : value

SVG : property =”value”2. Search: class=”classname”

in the entire document andreplace it with converted SVGattributes

Example:

CSS:

<style type="text/css">

<![CDATA

[ .st1 {fill:#febd21;stroke:none;stroke-linecap:round;stroke-linejoin:round;stroke-width:0.75}

]]>

</style>

SVG:

Before: <ellipse cx="15.7586" cy="826.131"rx="15.7586" ry="15.7586" class="st10" />

After: <ellipse cx="15.7586" cy="826.131" rx="15.7586"ry="15.7586" fill=”#febd21” stroke=”none” stroke-linecap=”round” stroke-linejoin=”round” stroke-width=”0.75” />

3. Complete the sub-steps in the following table to add different required attributes in the JSONdirectory:

Table 3: Add Attributes in the JSON DirectoryStep Description Example1. Jci-id: Add jci-

id=”symbolname” in main<svg> tag.#

jci-id="battery_electrical"


Table 3: Add Attributes in the JSON DirectoryStep Description Example2. Create a <g> tag to

complete data inside main<svg> tag, and add class=”symbolname”

Example:

<svg >

<g class="battery">

graphics content

</g>

</svg>3. Add fill=”#ffffff”

stroke=”#ffffff” attributeson <g> tag.

Note: This applies only if fill and stroke propertiesneed to be controlled from Property panel andCustom Behavior.

Example:

<g class="battery batteryGTag" fill="#D3D3D3"background-color="#D3D3D3" style="pointer-events:none">

4. Change the extension of the file from .svg to .html.

Creating thumbnailsTo create the thumbnails for the required SVGs in the UI, complete the following steps:

1. Export the symbol as a PNG from the source software.

2. Open Adobe Photoshop®, Snagit®, or any other graphics tool.

3. Create a new file with the dimensions 280 px x 280 px.

4. Import the image into the graphics tool.

5. Resize the image to fit the page.

6. Remove the background layers with white background.

7. Save or export the file as a PNG image.

8. Click Done.


Creating supporting data for the symbol libraryCustom Symbol Library JSON (mandatory step)This section describes the structure of customSymbolLibrary.json. This JSON isrequired to show the symbol in the Graphics Editor library. Create a JSON file named customSymbolLibrary.json. Ensure that the file name remains the same.Figure 5: customSymbolLibrary.json in the folder structure

The following table displays all the attributes with their required details.Table 4: Attributes for Custom Symbol libraryAttributename

Value Datatype I18N Dependency SVG Required Description

title SymbolCategoryFolder Name

String Yes N/A No Yes CategoryName isrequired.Without it,you cannotshow thesymbol withina category.


Table 4: Attributes for Custom Symbol librarycontentList Collection

of symbolsthat belongto this currentcategory

Array No Nameshould be"contentList"

No Yes Collection ofsame categorysymbols.

name Any symbolname

String Yes N/A No Yes Name is usedas a uniqueidentifier forthe entirefunctionality.

url Relative URLof thumbnailimage

String N/A Image shouldexist in thesame location

No Yes Thumbnailimagedisplays inthe librarythrough thisURL.

svgURL Relative URLof SVG symbol

String N/A HTML shouldexist inthe samelocation.

Yes Yes Same SVG isused whenyou dragsymbols onthe canvas.

symbolType numeric /binary /multiImageSymbol /patch /””

String N/A Use givenoptions only

Yes Yes

dragType Symbol String N/A Use givenoptions only

Yes Yes Used for dragand dropfunctionalityof symbols.

pointBindable

True/false Boolean N/A Use givenoptions only

Yes Yes Used forbinding optionavailable fromlayover panel.

keyData CollectionDefault pointbinding tosymbol

Array N/A Name shouldbe "keyData"

N/A Yes Only thispoint will beavailable forbinding in thepanel.

KeyName Any Name String Yes N/A Yes Key name willbe displayedin panel.

KeyPoint Only 1 Pointshort name

Array N/A Point ShortName

N/A No Used to bindany defaultpoint to asymbol.


Sample JSON

{ "symbolCategoryContent": [ { "title": "", "contentList": [ { "name": "HumidityValve", "url": "Symbols/Thumbnail/Humidity_Valve.png", "svgURL": "Symbols/Humidity_Valve.html", "symbolType": "numeric", "dragType": "symbol", "pointBindable": "true", "keyData": [ { "KeyName": "ValveOutputValue", "KeyPoint": [ "MA-D" ] } ] }

Note: The "title" key is required, but its value is optional. If you want to show a custom symbolwithin any of the categories, leave the title value empty.

Creating language supportCreating language JSONYou need the language JSON to add a new language string to a Custom Symbol. If you want tosupport several languages, you have to create a separate JSON for each language.Name your file using the ISO 639-1 language code for the language or region your file is for. Seethe following table for the recommended file name format:Table 5: ISO 639-1 Code.jsonLanguage ISO 639-1 code File nameEnglish En en-us.json

Czech Cs cs.json

JSON Structure

{ "key1": "value1", "key2": "value2" }

The structure of the file is a set of key and value pairs. The key for any entry should be the key namethat will be referred to in the code for your Custom Symbol (typically in English). The value shouldbe the translated value of that key in the language that the file applies to.For example:

{ "RoundDamper": "cs-RoundDamper", "RoundDamperTest": "cs-RoundDamperTest"


https://www.iso.org/standard/22109.html

}

Sample JSON for English user

{ "BasicSymbols": "Basic Symbols", "FloorPlan": "Floor Plan", "LinearGaugeVertical": "Linear Gauge"}

Sample JSON for Czech user { "BasicSymbols": "Základní symboly", "FloorPlan": "Půdorys podlaží", "LinearGaugeVertical": "Lineární měřidlo" }

Creating the property panel integrationCreating a JSON entry (mandatory step)You need this JSON to add the Property panel to a symbol. To control symbol attributes from theProperty panel, enter the symbol and its properties into csPropertyLibrary.json. Ensure thatthe file name remains the same.csPropertyLibrary.json structureThe following sample JSON is for a given property that creates the check box or radio button in theproperty panel.

{ "label": "propertyNameShowBorder", "inputType": "checkBox", "keyName": "ShowBorder", "defaultOffValue": "0", "defaultOnValue": "1", "selector": ".Border", "attr": "stroke-opacity", "defaultValue": "checked", "svgAttr": "isbordershown"}

The property has two default states, namely On and Off. The value for On is 1 and the value for Offis 0. The following table illustrates the relationship between the State and the Value of the property.Table 6: State and Value of the property keyProperty key State ValuedefaultOffValue Off 0defaultOnValue On 1

The following table displays all the attributes along with their required details.Table 7: Attributes for Property Panel IntegrationProperty type Attribute name Value Datatype I18N Dependency SVG Required DescriptioncolorPicker label KeyPropertyName String Yes No Yes KeyPropertyName is required.

Without it, you cannot show thesymbol within a category.

inputType colorPicker String No Name should be"inputType":????

No Yes Collection of input types.


Table 7: Attributes for Property Panel Integrationselector Class Name String No Name should be

"selector":????See JSON sampleabove for moredetails.

Yes Yes Class name is used to search forparticular html elements in SVGwhere properties were applied.

attr Fill/stroke String No Yes Yes Yes Display fill/stroke attributes forwhich you want to change thevalue.

defaultValue color propertyexample#FFFFFFF

hex N/A Yes Yes Yes Default values displayed are:true, false, 0,1, label, any colorvalue.

snd_selector Class Name String No Name should bethe same as classin SVG

Yes No Class name is used to search forparticular html elements in SVG,where properties were applied.

snd_attr Fill/stroke String No Yes Yes No Display Fill/Stroke attributes forwhich you want to change thevalue.

textBox label KeyPropertyName String Yes N/A No Yes KeyPropertyName is required.Without it, you cannot showsymbols within a category.

inputType inputType String No Name should besame


selector Class Name String No Name should besame as class inSVG

Yes Yes Class name is used to search forparticular html elements in SVG,where properties were applied.

defaultValue text String/Number Yes Yes Yes Default values displayed are:true, false, 0,1, label.

svgAttr Label oranyattribute

String No Yes Yes No Any attribute for which you wantto change the value.

dropDown label KeyPropertyName String Yes N/A No Yes KeyPropertyName is required.Without it, you cannot showsymbols within a category.

inputType dropDown String No Name should bethe same


Value [‘Hot’,’Cool’] Array Yes No Yes Yes Collection of values to bedisplayed in dropdown.

svgAttr Label oranyattribute


checkBox label KeyPropertyName String Yes N/A No Yes KeyPropertyName is required.Without it, you cannot showsymbols within a category.

inputType checkBox String No Name should bethe same


selector Class Name String No Name should bethe same as classin SVG

Yes Yes Class name is used to search forparticular html elements in SVG,where properties were applied.

attr Display/fill-opacity/stroke-opacity

String No Yes Yes Yes Display/fill-opacity/stroke-opacity attribute for which youwant to change the value.

defaultOffValue None/block/0

/1/true/false

String/number N/A Yes Yes No Default values displayed are:true, false, 0,1, label.

defaultOnValue None/block/0

/1/true/false

String/number N/A Yes Yes No Default values displayed are:true, false, 0,1, label.

defaultValue text String/Number N/A Yes Yes Yes Default values displayed are:true, false, 0 ,1, label.

svgAttr Label or anyattribute



Sample JSON for different property types

1. Fill color (background color)"SymbolName": [ { "label": "propertyNameBackgroundColor", "inputType": "colorPicker", "keyName": "Background Color", // Background color is the titledisplayed in property panel "selector": ".ClassName", // ClassName on <g> tag "attr": "fill", "snd_selector": ". ClassName", "snd_attr": "background-color", "defaultValue": "#D3D3D3", "colorComparisionAttr": "stroke", "colorComparisionSelector": ".rgb" } ]

2. Stroke color"SymbolName": [ { "label": "propertyNameBorderColor", "inputType": "colorPicker", "keyName": "Border Color", "selector": ".ClassName", "attr": "stroke", "defaultValue": "#DFDEDE", "svgAttr": "borderColor" } ]

3. Stroke width (border thickness){ "label": "propertyNameBorderThickness", "inputType": "textBox", "keyName": "Border Thickness", "required": true, "defaultOffValue": "0", "defaultValue": 1, "type": "border", "svgAttr": "border-thickness", "svgAttrValue": "data-border-thickness", "selector": ". ClassName", "attr": "stroke-width"}

4. Stroke show/hide (show border){ "label": "propertyNameShowBorder", "inputType": "checkBox", "keyName": "Show Border", "defaultOffValue": "0", "defaultOnValue": "1", "selector": ". ClassName",


"attr": "stroke-width", "defaultValue": "unchecked", "svgAttr": "isbordershown", "type": "borderbvb"}

5. Dropdown property sample{ "label": "propertyPipeType", "inputType": "dropDown", "keyName": "Pipe Type", "values": [ "chilledWaterSupplyKey", "chilledWaterReturnKey", "condenserWaterSupplyKey", "condenserWaterReturnKey", "hotWaterSupplyKey", "hotWaterReturnKey", "condensateKey", "steamKey", "gasKey" ], "defaultValue": "chilledWaterSupplyKey", "svgAttr": "selectedshape", "mainSvgAttr": "mainselectedshape", "selector": "path[bas-symbols='pipCol']", "attr": "stroke", "snd_selector": "path[bas-symbols='pipCol']", "snd_attr": "background-color"}


Creating dropdown property JSONcsSVGModification.json is a JSON that supports dropdown property change, as it storesdata of SVG with the respective dropdown list items. The JSON stores different data for circleKey,squareKey, and triangleKey items. When you change the dropdown item, you have to specify whichvalues have to be changed.To define the values for a dropdown, you must first define the symbol in thecsPropertyLibrary.json file with an appropriate name. Using the name, the values for thedropdown can be defined in csSVGModification.json using the structure described in Table 9.The structure starts with the symbol ID, which you specified in customSymbolLibrary.json.Table 8: DefinitionsName Definition

SymbolName Symbol name same as mentioned incsPropertyLibrary.json

dropdownKey1 Key name same as described in csPropertyLibrary.json

selector Value of ‘bas-symbols’ attribute on the tag to apply value of‘attribute’

attribute Attribute and selector to be updated


Table 9: JSON reference syntax and examplesSyntax for reference Corresponding examplesSymbolName,dropdownKey1, selector, andattribute

"SymbolName": { // same as mentioned incsPropertyLibrary.json "dropdownKey1": { "selector": {//bas-symbol=”selector” in html "attribute": "value to beassigned" },

further selectors and attributes underdropdownKey1

"selector2": {//bas-symbol=”selector” in html "attribute": "value to beassigned" },

"selector3": {//bas-symbol=”selector” in html "attribute": "value to beassigned" } },

dropdownKey2 with selector and attribute

"dropdownKey2": { "selector": {//bas-symbol=”selector” in html "attribute": "value to beassigned" },


"selector2": {//bas-symbol=”selector” in html "attribute": "value to beassigned" },

"selector3": {//bas-symbol=”selector” in html "attribute": "value to beassigned" }, }, }

SymbolName,dropdownKey1, selector, andattribute

"TempratureSensorAverageType": { "averagingKey": { "asTempJcid": { "jci-id": "temp_sensor_avg" },


"asTempImg": { "xlink:href":"img/AHU/HVACAirSensors/AirSensors_refs/Temprature-Sensor-(Average-Type).png" },

"asTempPath": { "d":"M32.072,15.101l72.376,6.008v10.294l-7.799,3.821l0.391,31.119h2.729v10.686lz" } },

dropdownKey2 with selector and attribute

"bulbKey": { "asTempJcid": { "jci-id": "temp_sensor_bulb" },


"asTempImg": { "xlink:href":"img/AHU/HVACAirSensors/AirSensors_refs/Temprature-Sensor-(-Bulb-type-).png" },

"asTempPath": { "d":"M46,1c6.611,0.553,13.217,1.198,19.836,1.638c12.941,0.858,25.898,1.487,38.828,2.495c2.451,0.19,6.393-0.644,6.535,3.618c0.137,4.051,1.832,8.979z" }, }, }


Custom BehaviorTo support Custom Behavior, enter the symbol and its configuration into csSymbolMapData.jsonand csEditorMetaData.json. Use the same symbol name in both locations.

Creating JSON for Custom Behavior – csEditorMetaData.jsonThere are 19 Custom Behavior options. You can select the required options for a particular symbol.If the behavior is required, assign binary 1 to the behavior. If the behavior is not required, assignbinary 0 to the behavior. Convert the binary values to hexadecimal values, and copy the convertedvalues to the csEditorMetaData file.The following section illustrates the binary to decimal conversion.Table 10: Custom Behavior propertiesSerialnumber Behavior name

1 "Show",2 "Hide",3 "ChangeColorFloodColor",4 "ChangeColorFill",5 "ChangeColorStroke",6 "ChangeColorText",7 "FlashFill",8 "FlashStroke",9 "FlashTextColor",10 "FlashFloodColor",11 "SpanColorFill",12 "SpanColorStroke",13 "SpanColorText",14 "RotateSpan",15 "RotateSpin",16 "RotateNormal",17 "ToolTip",18 "TextChange",19 "SpanColorFloodColor"

If a symbol supports Custom Behavior, the count value is 1, otherwise the count value is 0.Example: If a symbol supports Custom Behaviors 1, 2, 4, 5, 7 and 8, illustrated in the previous table,then the value for these Custom Behaviors is 1.To create and convert a binary value, complete the following steps:

1. Generate the binary value for the Custom Behavior as follows:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 191 1 0 1 1 0 1 1 0 0 0 0 0 0 0 0 0 0 0

Binary value = 1101101100000000000


2. Convert the binary value to a decimal value with a binary to decimal converter. Decimal value= 448512

3. Set the value as “All”: 448512

Sample csEditorMetaData.json:

{ "CS_AsiaHumidityValve": { "All": 448512 }

Creating JSON for Custom Behavior – csSymbolMapData.jsonYou need the csSymbolMapData.json to define which SVG element the Custom Behavior effectapplies to.Complete the following steps to assign an effect to an SVG element.

1. Create a new entry and insert the jci-id of the Custom Symbol.

2. Insert the Custom Behavior effect data."jci-id of the symbol": { CB effect json data}

The following table lists all Custom Behavior effects along with their properties and respective JSONtemplate changes, which are required to support the effects for the Custom Symbol. The table alsodisplays the Custom Behavior properties JSON that has to be added to csSymbolMapData.json.Table 11: Custom Behavior effects and propertiesEffect Property JSON template

fillStrokeColor

"ClassName": [ // Classname is a selector "fill", // attributes to be changed"stroke","fill-opacity","stroke-opacity"]},changeColorCustDef

textColor" ClassName ": [ // Classname is a selector "fill", // attributes to be changed "fill-opacity" ]

fillStrokeColor

"ClassName": [ // Classname is a selector "fill", // attributes to be changed"stroke","fill-opacity","stroke-opacity"]},changeColorSysDef



Table 11: Custom Behavior effects and properties

fillStrokeColor

"ClassName": [ // Classname is a selector "fill", // attributes to be changed"stroke","fill-opacity","stroke-opacity"]},flashCustDef


fillStrokeColor

"ClassName": [ // Classname is a selector "fill", // attributes to be changed"stroke","fill-opacity","stroke-opacity"]},flashSysDef


Sample csSymbolMapData.json

{ "HumidityValve": { "changeColorCustDef": { "fillStrokeColor": { "pipCol": [ "stroke", "stroke-opacity" ], "watCol": [ "fill", "fill-opacity" ] } }}

The following sample shows a state triangle symbol that has change color behavior withcustom-defined color. For this behavior, you set the fill and stroke attribute of the element with theclass name cbStateTriangle.

"state_triangle": { "changeColorCustDef": { "fillStrokeColor": { "cbStateTriangle": [ "fill", "stroke" ] }


}}

Symbol animationAdding animation logicThis section explains how to add animation logic to your Custom Symbols. You have to create aseparate JavaScript function for each animation that you want to add to a symbol.To support animation for the symbols you created, complete the following steps:

1. Go to customSymbolLibrary.json and ensure that <KEYDATA> exists."keyData": [ { "KeyName": "UnitStatus", "KeyPoint": [ "UNT-S" ] }

2. Create a JavaScript file as csAnimation.js that includes all supporting functions of animation.Note: The file name has to be identical.

3. Add an Immediately-Invoked Function Expression that registers animation code for symbols.

4. Add function blocks that support execution of animation on symbols.

5. Add a Custom Symbol animation function entry in core MapperObj to register the symbol foranimation.

6. Structure the csAnimation.js as follows:(function () {/** Function Block Entry Start Here Your Animation Function Block Function Block Entry End Here**/ var csMapper = MUI.SymbolFactory.MapperObj;var MapItem = MUI.SymbolFactory.MapItemFun;/** Mapper Block Entry Start Here Your Mapper Block Mapper Block Entry End Here**/ }.bind({})());


https://developer.mozilla.org/en-US/docs/Glossary/IIFE

7. Add a Mapper Block Entry in the above code structure for each symbol to support animation ingraphics.

Note: Copy and paste the following code snippets, and add them into the Mapper Block Entry.Only change the code highlighted in blue.

csMapper.push(new MapItem("<Please add symbol name on which you want to addanimation from customSymbolLibrary.json, it should be unique> ", "<symbol jci-idprovided in SVG >", this.symbolNameVariable));

For example: csMapper.push(new MapItem("CSVerticalRoundDamper","CS_Vertical_Round_Damper", this.VerticalRoundDamper));

Two-state animationTo support two-state animation with the image format base64, use the following code structure.

Note: Copy and paste the following code snippets, and add them into the Mapper Block Entry.Only change the code highlighted in blue.

this.<please add symbol name on which you want to add animation fromcustomSymbolLibrary.json, it should be unique> = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "<Please add symbol name on which you want to add animation fromcustomSymbolLibrary.json>", MUI.SymbolType.Binary, MUI.AnimationType.OnOff, [MUI.StateValuesType.Boolean]); points[0].AnimationSrc = [ ["Off", ".<Please provide class name from created SVG for which you want towork Off animation>"], ["On", ".<Please provide class name from created SVG for which you want towork On animation>"] ]; points[0].PointName = "<Please add KeyName i.e. <DefaultBindingKey>>"; points[0].MaxValueOffState = 0; this.SetAnimationPoints(points);};

Sample code:

//#region Supply Fanthis.CSReturnFan = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "CSReturnFan", MUI.SymbolType.Binary, MUI.AnimationType.OnOff, [MUI.StateValuesType.Boolean]); points[0].AnimationSrc = [["Off", "animateOff"], ["On", "animateOn"]]; points[0].PointName = "ReturnFanPrimaryStatus"; points[0].MaxValueOffState = 0; this.SetAnimationPoints(points); this.AfterAnimation = function(animationPoint) { var element, statusId, fanColor, currentElem, ellipseElem; ellipseElem = this.DomElem.find('ellipse[class^="point-status-color"]'); element = this.DomElem.find('image[class^="animate"]'); statusId = animationPoint.PointInfo.statusId;


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

fanColor = MUI.Control.fillColorToSymbol(this, '', animationPoint); currentElem = element.closest('svg'); currentElem.find('feFlood').attr('flood-color', fanColor); currentElem.find('feFlood').attr('flood-color-org', fanColor); ellipseElem.attr('fill', fanColor); }};//#endregion

Multistate animationTo support multistate animation with the image format base64, use the following code block andadd the entry custom-symbol=”true” in the SVG structure of the supported symbol.

Note: Copy and paste the following code snippets. Only change the code highlighted in blue.

this.<please add symbol name on which you want to add animation fromcustomSymbolLibrary.json, it should be unique> = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "<please add symbolname on which you want to add animation from customSymbolLibrary.json>", MUI.SymbolType.Binary, MUI.AnimationType.Img, [MUI.StateValuesType.PercentBased4]); points[0].AnimationSrc = [ ["Off", ".<Please provide class name from created SVG for which you wantto work Off animation>"], ["25%", ".<Please provide class name from created SVG for which you wantto work 25% animation>"], ["50%", ".<Please provide class name from created SVG for which you wantto work 50% animation>"], ["75%", ".<Please provide class name from created SVG for which you wantto work 75% animation>"], ["100%", ".<Please provide class name from created SVG for which youwant to work 100% animation>"] ]; points[0].PointName = "<Please add KeyName i.e. <DefaultBindingKey>>"; points[0].MinValueOffState = 0; points[0].MaxValueOffState = 100; this.SetAnimationPoints(points); };

Sample code:

this.csRoundDampper = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "csRoundDampper", MUI.SymbolType.Numeric, MUI.AnimationType.Img, [MUI.StateValuesType.PercentBased4_ClosedType]); points[0].AnimationSrc = [ ["Closed", "state0"], ["PerOpen25", "state1"], ["PerOpen50", "state2"],["PerOpen75", "state3"], ["PerOpen100", "state4"] ]; points[0].PointName = "DamperPrimaryValue"; points[0].MinValueOffState = 0; points[0].MaxValueOffState = 100; this.SetAnimationPoints(points);};


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

Multistage animationThe sample code for multistage animation is identical to the sample code used for Multistateanimation. However, make one additional entry: “Unique Name when 100% Animation andthen it supports many stages animation like 10%, 25%, 50%, 100%, it can support any availablecombinations.”

Note: Copy and paste the following code snippets. Only change the code highlighted in blue.

Sample code:

this.<please add symbol name on which you want to add animation fromcustomSymbolLibrary.json, it should be unique> = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "<please add symbol name on which you want to add animation fromcustomSymbolLibrary.json>", MUI.SymbolType.Binary, MUI.AnimationType.Img, [ MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean,MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean,MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean ]); //Stage1 points[0].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 1>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 1>"]]; points[0].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage1>"; points[0].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 1>]:first"; points[0].MaxValueOffState = 0; //Stage2 points[1].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 2>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 2>"]]; points[1].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage2>"; points[1].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 2>]:first"; points[1].MaxValueOffState = 0; //Stage3 points[2].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 3>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 3>"]]; points[2].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage3>"; points[2].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 3>]:first"; points[2].MaxValueOffState = 0; //Stage4 points[3].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 4>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 4>"]]; points[3].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage4>";


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

points[3].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 4>]:first"; points[3].MaxValueOffState = 0; //Stage5 points[4].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 5>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 5>"]]; points[4].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage5>"; points[4].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 5>]:first"; points[4].MaxValueOffState = 0; //Stage6 points[5].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 6>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 6>"]]; points[5].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage6>"; points[5].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 6>]:first"; points[5].MaxValueOffState = 0; //Stage7 points[6].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 7>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 7>"]]; points[6].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage7>"; points[6].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 7>]:first"; points[6].MaxValueOffState = 0; //Stage8 points[7].AnimationSrc = [["Off", "<Please provide class name from created SVGfor which you want to work Off animation for stage 8>"], ["On", "<Please provideclass name from created SVG for which you want to work On animation for stage 8>"]]; points[7].PointName = "<Please add KeyName i.e. <DefaultBindingKey> for stage8>"; points[7].AnimatorElemSelector = "[class^='<Please provide class name fromcreated SVG for which you want to work animation for stage 8>]:first"; points[7].MaxValueOffState = 0;this.SetAnimationPoints(points); this.AfterAnimation = function(animationPoint) { var animationOn = ".<Please provide class name from created SVG for whichyou want to work On animation for all stages>"; var animationOff = ".<Please provide class name from created SVG for whichyou want to work Off animation for all stages>";var pointStatusOn = _.countBy(_.filter(this.AnimationPoints, function(obj) { returnobj.State != null; }), function(obj) { return obj.State.AnimationStatus == "On"; }); var pointsBindedCount = _.filter(this.AnimationPoints, function(obj){ return obj.State != null; }).length; var pointStatusOnCount = parseInt(pointStatusOn["true"]); if (!(pointStatusOnCount > 0 && pointStatusOnCount <= 8)) pointStatusOnCount = 0; if (!(pointsBindedCount > 0 && pointsBindedCount <= 8))


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

pointsBindedCount = 0; this.DomElem.find('.<Please provide class name from created SVGfor which you want to work Off animation for all stages>).attr('display','none').css('display', 'none'); this.DomElem.find('.<Please provide class name from created SVGfor which you want to work On animation for all stages>).attr('display','none').css('display', 'none'); var allCoilsOn = this.DomElem.find('.<Please provide class name from createdSVG for which you want to work On animation for all stages>); var allCoilsOff = this.DomElem.find('.<Please provide class name fromcreated SVG for which you want to work Off animation for all stages>); var startIndex = 4 - Math.round(pointsBindedCount / 2); var totalCoilsToDisplay = $.grep(allCoilsOff, function(elem, i) { return i >=startIndex; }).slice(0, pointsBindedCount); $.each(totalCoilsToDisplay, function() { $(this).attr('display', 'block').css('display', 'block'); }); startIndex = 4 - Math.round(pointStatusOnCount / 2); var totalCoilsToDisplay = $.grep(allCoilsOn, function(elem, i) { return i >=startIndex; }).slice(0, pointStatusOnCount); $.each(totalCoilsToDisplay, function() { // $(this).attr('xlink:href',_.head(_.filter(animationPoint.AnimationSrc, { Id: "On" })).Url); $(this).attr('display', 'block').css('display', 'block'); }); };};

Sample code:this.CSHvacCoilsElectricCoil = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "CSHvacCoilsElectricCoil", MUI.SymbolType.Binary, MUI.AnimationType.Img, [ MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean,MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean,MUI.StateValuesType.Boolean, MUI.StateValuesType.Boolean ]); //Stage1 points[0].AnimationSrc = [["Off", "animateOff_Coil1"], ["On","animateOn_Coil1"]]; points[0].PointName = "ElectricHeatingCoil1Value"; points[0].AnimatorElemSelector = "[class^='ElectricCoil_1']:first"; points[0].MaxValueOffState = 0; //Stage2


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

points[1].AnimationSrc = [["Off", "animateOff_Coil2"], ["On","animateOn_Coil2"]]; points[1].PointName = "ElectricHeatingCoil2Value"; points[1].AnimatorElemSelector = "[class^='ElectricCoil_2']:first"; points[1].MaxValueOffState = 0; //Stage3 points[2].AnimationSrc = [["Off", "animateOff_Coil3"], ["On","animateOn_Coil3"]]; points[2].PointName = "ElectricHeatingCoil3Value"; points[2].AnimatorElemSelector = "[class^='ElectricCoil_3']:first"; points[2].MaxValueOffState = 0; //Stage4 points[3].AnimationSrc = [["Off", "animateOff_Coil4"], ["On","animateOn_Coil4"]]; points[3].PointName = "ElectricHeatingCoil4Value"; points[3].AnimatorElemSelector = "[class^='ElectricCoil_4']:first";; points[3].MaxValueOffState = 0; //Stage5 points[4].AnimationSrc = [["Off", "animateOff_Coil5"], ["On","animateOn_Coil5"]]; points[4].PointName = "ElectricHeatingCoil5Value"; points[4].AnimatorElemSelector = "[class^='ElectricCoil_5']:first";; points[4].MaxValueOffState = 0; //Stage6 points[5].AnimationSrc = [["Off", "animateOff_Coil6"], ["On","animateOn_Coil6"]]; points[5].PointName = "ElectricHeatingCoil6Value"; points[5].AnimatorElemSelector = "[class^='ElectricCoil_6']:first";; points[5].MaxValueOffState = 0; //Stage7 points[6].AnimationSrc = [["Off", "animateOff_Coil7"], ["On","animateOn_Coil7"]]; points[6].PointName = "ElectricHeatingCoil7Value"; points[6].AnimatorElemSelector = "[class^='ElectricCoil_7']:first";; points[6].MaxValueOffState = 0; //Stage8 points[7].AnimationSrc = [["Off", "animateOff_Coil8"], ["On","animateOn_Coil8"]]; points[7].PointName = "ElectricHeatingCoil8Value"; points[7].AnimatorElemSelector = "[class^='ElectricCoil_8']:first";; points[7].MaxValueOffState = 0; this.SetAnimationPoints(points); this.AfterAnimation = function(animationPoint) { var animationOn = ".animationOn"; var animationOff = ".animationOff"; var pointStatusOn = _.countBy(_.filter(this.AnimationPoints, function(obj){ return obj.State != null; }), function(obj) { return obj.State.AnimationStatus == "On"; }); var pointsBindedCount = _.filter(this.AnimationPoints, function(obj){ return obj.State != null; }).length;


attr('fill-org', state.FillColor); this.DomElem.find('[id^=' + 'Unique Name when 100% Animation Will Work fromSVG' + ']:first') .attr('fill-opacity', state.FillOpacity); this.DomElem.find('[id^=' + 'Unique Name when 100% Animation Will Work fromSVG' + ']:first'). //To Support Stroke .attr('stroke', state.StrokeColor); this.DomElem.find('[id^=' + 'Unique Name when 100% Animation Will Work fromSVG' + ']:first'). .attr('original-stroke', state.StrokeColor); };};

Sample code:

this.LightingCircleDaySensor = function() { var points = MUI.Control.SymbolAnimationBase.call(this, "LightingCircleDaySensor", MUI.SymbolType.Binary, MUI.AnimationType.FillStroke, [MUI.Boolean]); points[0].PointName = 'DaySensorValue'; points[0].MaxValueOffState = 0; this.SetAnimationPoints(points); this.Fill = function(animationPoint, state) { this.DomElem.find('[id^=' + 'animationpatch' + ']:first').attr('fill',state.FillColor); this.DomElem.find('[id^=' + 'animationpatch' + ']:first').attr('fill-org',state.FillColor); this.DomElem.find('[id^=' + 'animationpatch' + ']:first').attr('fill-opacity', state.FillOpacity); this.DomElem.find('[id^=' + 'animationpatch' + ']:first').attr('stroke',state.StrokeColor); this.DomElem.find('[id^=' + 'animationpatch' + ']:first').attr('original-stroke', state.StrokeColor); };};

Importing Custom Symbols into Metasys UITo import Custom Symbols into Metasys UI Online, complete the following steps:

1. Click the user menu icon on the Metasys UI.

2. Click Graphics Manager.

3. Click Tools in the panel on the left.

4. Click IMPORT CUSTOM SYMBOLS.

5. Click Choose File and then browse to and select the required .zip file.Important: An import overwrites existing Custom Symbols. Ensure that the .zip that youimport is all-inclusive. The file must be a .zip file and the file size must not exceed 1GB.

6. Click IMPORT.


jmeusbm

Highlight

jmeusbm

Highlight

jmeusbm

Highlight

7. Refresh the browser (Ctrl + F5) and refresh the Internet Information Services (IIS) Manager toresolve potential dictionary issues, and to ensure that animation and Custom Behavior workcorrectly.

For more information about how to import symbols, refer to the Working with Symbols section inMetasys UI Online Help (LIT-12011953) or Metasys UI Offline Help (LIT-12012116).For more information about how to refresh the IIS Manager, refer to the Troubleshooting section ofthe Metasys UI Technical Bulletin (LIT-12012115).


metasys ui custom symbols technical bulletin · notation (json) layouts of the symbols, the...

Documents