a.williamson/BAT
1
0
Fork 0
forked from b.peck/BAT
Code Pull Requests Activity
Files
main
BAT/exchangeResources/Exchange+Resources+Style+Guide.md
a.williamson 58610c1e1a exchange work
2026-09-15 13:06:45 -05:00

1040 lines
47 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## Quick Reference
||||**Perspective**|**Vision**|
|---|---|---|---|---|
|||View / Window Nam|es*<br>View Name|Window Name|
|||Template Names*||Template Name|
|||Properties|propertyName|propertyName|
|**Viliti**||Component Names|ComponentName|ComponentName|
|**suazaon**||Page Names|page-name||
|||Fonts|Use font defaults|Use font defaults|
|||Theming|Built-In Theme Colors||
|||Style Class|style-class||
|**Resource Str**|**ucture**||exchange/<resource>/<item> - resourc<br>Exchange/<resource>/<item> - resourc|es that start lowercase<br>es that start uppercase|
||Project N|ames|project-name||
|**Project**|Project Ti|tles|Project Title||
|**Tags / UDTs**|Folders a|nd Tag Names|Exchange/ResourceName/TagFolder/Ta<br>Exchange/Resource Name/Tag Folder/T|gName or<br>ag Name|
|**Named**|Query Na|mes*|Query Name||
|**Queries**|Paramete|r Names|parameterName||
||Tabs v.s.|Spaces|Tabs||
||Project Li|brary|exchange.folder.script<br>exchange.folderName.scriptName||
||Variable|Names|variableName||
||Function|Names|functionName||
|**Python**|Class Na|mes|ClassName||
||Single-Lin|e Comments|# Single-Line Comment||
||Multi-Line|Comments|# Multi-Line<br># Comments||
||Single Lin|e Doc Strings|"""Single-Line Documentation String."""||
||Multi-Line|Doc Strings|Google’s Python Style Guide||
||Other co|de style choices|PEP-8||
||Table Na|mes|ex_<project name abbreviation>_table|_name|
|**Database**|ID Colum|n|id||
<!-- Start of picture text -->
OG tgritiortet<br><!-- End of picture text -->
2
VERSION 1.1.0
||Foreign Key Column Name|foreign_table_name_id|
|---|---|---|
||Column Names|column_name|
|**Alarm**<br>**i**|Names and Folders*|Exchange/Resource Name/Alarm Pipeline|
|**Notification**<br>**Pipelines**|Custom Properties|propertyName|
||Names and Folders*|Exchange/Resource Name/SFC Name|
|**SFCs**|Chart Parameters|parameterName|
||Block Names|BlockName|
||Names and Folders*|Exchange/Resource Name/New Group|
|**SQL Bridge**|Item Names*|Item Name|
||Names and Folders*|Exchange/Resource Name/New Report|
|**Reports**|Parameter Names|ItemName|
||Component Names|ComponentName|
|**WebDev**|Names and Folders|exchange/resource-name/example-resource|
|**Image Mana**|**gement**|exchange/resource-name/image-name.jpg|
|**Translations**||word<br>(single-word translations)<br>_translation_phrase<br>(multi-word translations)|
*Top level resources may use Title Case or PascalCase
<!-- Start of picture text -->
OG tgritiortet<br><!-- End of picture text -->
3
VERSION 1.1.0
# Table of Contents
|**Table of Contents**|**4**|
|---|---|
|**Ignition Exchange Best Practices**|**5**|
|General Guidance|5|
|Project Browser Resource Structure|5|
|Variable / Data Storage|6|
|Naming Conventions|7|
|Projects|7|
|Perspective|7|
|Tags|9|
|Vision|10|
|Code|11|
|Database|14|
|Named Queries|15|
|Alarm Notification Pipelines|16|
|Sequential Function Charts (SFCs)|16|
|SQL Bridge (Transaction Groups)|17|
|Reports|18|
|Web Development Module (WebDev)|19|
|Miscellaneous Designer Tools|20|
|**Before You Upload to the Exchange**|**22**|
|Things to check for:|22|
|Check the project export|22|
|Include the tags|22|
|Don’t forget database backups|22|
|Take notes of the steps taken when checking your project export|22|
|**Uploading to the Exchange**|**23**|
|Overview Section|23|
|Package Section|26|
|Helpful Notes|29|
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
4
VERSION 1.1.0
# Ignition Exchange Best Practices
When developing Exchange Resources, following the styles outlined below will help with consistency of naming conventions.
Having resources conform to these standards helps make resources easier to understand, explore, implement, and upgrade. These best practices should be adhered to unless it is not possible for the resource in question. We encourage you to follow the naming conventions outlined here, however these conventions are not required. **Consistent naming conventions are critical, regardless of what naming conventions you ultimately use** .
## General Guidance
### Project Browser Resource Structure
<mark>exchange/<resource>/<item> - resources that start lowercase Exchange/<resource>/<item> - resources that start uppercase</mark>
Views, Styles, Scripts, etc. **must** all be contained within an appropriately named folder. This allows easy imports into existing projects, where those project resources won’t overlap, interfere, or overwrite existing parts of a user’s project. It also allows for easy updates to Exchange resources for users when a new version is released. Look below to see which resource categories should start lowercase and which should start uppercase.
<!-- Start of picture text -->
Project Browser ax<br>a allly<br>>- fim Exchange<br>~ && Sequential Function Charts<br>> fam Exchange<br>~ Bi scripting<br>& Gateway Events<br>~~ f& Project Library<br>> {@ exchange<br>~ @ Perspective<br>& Session Events<br>~ i Styles<br>> fmm exchange<br>~ Wi Views<br>> fam Exchange<br><!-- End of picture text -->
<!-- Start of picture text -->
o<br>2g Transaction Groups<br>> iam Exchange<br>& Client events<br>~ Bwi<br>_<br>> mm Exchange<br>-<br>y fo Templates<br>>i Exchange<br>~ & Named Queries<br>> fm Exchange<br>~ B Reports<br>> jam Exchange<br>~ @ Web Dev<br>b+ exchange<br><!-- End of picture text -->
<!-- Start of picture text -->
OF automationinductive — www.inductiveautomation.com8002667798 |gnitionTh AY e/<br><!-- End of picture text -->
5
VERSION 1.1.0
### Variable / Data Storage
##### Temporary Client / Session Variables
<mark>View / Window Properties</mark>
<mark>system.util.getGlobals()['exchange']['resourceName']['clientId']</mark>
Temporary Gateway Variables (Persists Until Gateway Restart)
<mark>system.util.getGlobals()['exchange']['resourceName']</mark>
##### Long Term Storage
<mark>Database Tables</mark>
Avoid
<mark>Perspective Session Properties Vision Client Tags</mark>
Variables that are only expected to be used by a single client / session can often be stored in properties on views or windows. For items that need to be stored even when the view or window isn’t shown anymore, the globals dictionary at system.util.getGlobals() can be a great place to store these things. Data, objects, or variables intended to be used over multiple sessions can be stored in globals as well.
Although projects will often use Perspective session properties or Vision client tags for this type of storage, doing this for an Exchange resource limits the ability to import your resource into another project. Using just the variables suggested here will help ensure that importing your resource will be smooth when someone wants to use it in a separate project.
A scoping note on system.util.getGlobals():
Vision: In a Vision client, this is a dictionary inside the client, and there’s a separate dictionary for each client. For scripts running in the client scope, they’ll access the client globals dictionary. For scripts running in the Gateway scope, it’ll access the shared Gateway globals dictionary.
Perspective: the globals dictionary is always the shared Gateway globals dictionary. The same data is available from the Gateway scope and from sessions.
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
6
VERSION 1.1.0
## Naming Conventions
Consistent naming helps with projects feeling cohesive, and can also help to easily identify what type of object is being used just by looking at its name for certain resources.
### Projects
#### Project Names
##### <mark>project-name</mark>
Starting in Ignition 8.1.11, these should be lowercase and use dashes for multi-word names to be URL-friendly. Project names should only include letters, numbers, hyphens, and underscores. Please do not append the version number to the end of the project name, the version number can be managed through the Exchange during the <u>upload process.</u>
#### Project Titles
##### <mark>Project Title</mark>
These should be Human-friendly, with capitals and spaces as appropriate.
### Perspective
#### View Names
##### <mark>View Name</mark> or <mark>ViewName</mark>
Views can either be Title Case or PascalCase.. This gives view names an easy to read format.
#### Properties
##### <mark>propertyName</mark>
These should be camelCase, starting with a lowercase letter. This matches the style of the built-in properties on Perspective components.
#### View Properties
<mark>params.publicProperty</mark>
##### <mark>custom.privateProperty</mark>
For embedded views, put any property that’s intended to be used to configure the view as a property in the param category. Put properties that you create for internal use inside the view itself as a property in the custom category. This separation helps make it clearer
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
7
VERSION 1.1.0
which properties will just be used internally in the view and which are intended to be settings for the view.
#### Component Names
##### <mark>ComponentName</mark>
These should be PascalCase starting with a capital letter and capitalizing the first letter of each word. This provides consistency with the default component names.
#### Page Names
##### <mark>page-name</mark>
These should be lowercase and use dashes for multi-word names. This puts them in a format that’s URL-friendly.
#### Message Handlers
<mark>exchange.resourceName.handlerName</mark>
<mark>or exchange.resourceName.viewName.handlerName</mark>
Unique message handler names prevent collision with existing handlers. Using exhange.resourceName as a naming convention will identify the resource in console logs as well as facilitate unique naming. This is a recommendation and not a requirement for publishing a resource on the Exchange.
#### Fonts
Font sizes should match the default font sizes of most components, or take advantage of styling as appropriate. Matching defaults makes the resource fit stylistically inside projects that are using Ignition’s defaults.
#### Theming
Supporting themes is optional, but is a nice feature for users of your resource. When supporting theming, set colors to appropriate theme colors so Ignition’s theming can change the colors displayed as different themes are selected. Refer to the Ignition documentation for Built-In Theme Colors.
#### Style Classes
<mark>style-class</mark>
This should be lowercase with dashes for multi-word names. Style class naming and hierarchy should match the hierarchy of the Perspective views they belong to. If style class is used across multiple views, place the style class at the topmost folder that
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
8
VERSION 1.1.0
encompasses all views using it. If the style class is exclusively used in one view, create a folder named after the view name and place the style class within it. (See picture below for an example.)
<!-- Start of picture text -->
@ Alarm Notification Pipelines<br>‘a Sequential Function Charts<br>> B scripting<br>~ © Perspective<br>& Session Events<br>~ fe Styles<br>~ fmm exchange<br>~ fam resource-name<br>~ fam another-view.name<br>«® only-used-in-another-view-name<br>> fm viewname<br>«® only-used-in-view-name<br>(® used-in-multiple-views<br>~ &% Views<br>~ fam Exchange<br>~ fam ResourceName<br>@ AnotherViewName<br>@ ViewName<br>Qy Transaction Groups<br>> @vision Le<br>B named Queries<br>Reports<br>@ web Dev<br><!-- End of picture text -->
### Tags
For tag names and folders, you can use either PascalCase or Title Case. It’s nice that Ignition supports spaces in tag names and folders, and you may use this to your advantage to make your tags and tag folders more readable. However, you may find PascalCase to be a neater option for tag names. This structure also applies to UDT definitions.
Note that spaces in tag names may lead to property names with spaces specifically when using UDT bindings in Perspective. The designer will notify of this as non-standard, but doesn’t degrade performance or affect clients in any way.
Tag Folders and Names
<mark>Exchange/ResourceName/TagFolder/TagName</mark>
or
<mark>Exchange/ResourceName/Tag Folder/Tag Name</mark>
<!-- Start of picture text -->
inductive 8002667798 Th AY /<br>OU Ignition.<br><!-- End of picture text -->
9
VERSION 1.1.0
### Vision
#### Window Names
##### <mark>Window Name</mark> or <mark>WindowName</mark>
Window names can be either Title Case or PascalCase.
#### Template Names
##### <mark>Template Name</mark> or <mark>TemplateName</mark>
As with window names, template names can be either Title Case or PascalCase.
#### Properties
##### <mark>propertyName</mark>
These should be camelCase, starting with a lowercase letter. This matches the style of the built-in parameters on Perspective components.
#### Component Names
##### <mark>ComponentName</mark>
These should be PascalCase, with a capital letter and capitalizing the first letter of each word. This provides consistency with View Names and with Vision Component Names.
<!-- Start of picture text -->
ProjectBronser a-x<br>O Fite a<br>£9) Alarm Notification Pipelines<br>1, Sequential Function Charts<br>> Bi scripting<br>> @ Perspective<br>im Transaction Groups<br>> © vision<br>& client Everts<br>+ Biwindows<br>~ fam Exchange<br>~ fam Resource Name<br>Another window<br>Ci mainwindow ©<br>> €3 Templates<br>~ fam Exchange<br>~ fam Resource Name<br>fam Another Window<br>> fam Main window<br>#€3 Template For Main Window<br>€3 General Template For Multiple Windows<br>3 Named Queries<br>& repors<br><!-- End of picture text -->
<!-- Start of picture text -->
inductive — 8002667798 | iti “ /<br>automation — www.inductiveautomation.com gnition e<br><!-- End of picture text -->
10
VERSION 1.1.0
### Code
Having good names for variables, functions, and consistency with white space is important for readability and maintainability of code.
#### Tabs v.s. Spaces
Ignition’s editor uses tabs when the tab key is pressed. Therefore, tabs should be used for consistency, compatibility with code from other Ignition users, and maintainability.
#### Project Library
<mark>exchange.folder.script</mark>
<mark>exchange.folderName.scriptName</mark>
Scripts and folders in the project library should be all lowercase, and should be single words where possible.
#### Variable Names
##### <mark>variableName</mark>
These should be camelCase, starting with a lowercase letter. This is the style used in the Ignition user manual, to have consistency with property names. Note that this differs from PEP-8. Variable names that are being used to pass data to Ignition’s API functions should match the names of the arguments in functions where it makes sense. For example, if you’re defining a variable to pass to startDate in a function, call your variable startDate. Prefixing with another name may also make sense depending on your application, like processStartDate.
#### Function Names
<mark>functionName</mark>
These should be camelCase, starting with a lowercase letter. This is the style used in the Ignition user manual, to have consistency with Java method name conventions. Note that this differs from PEP-8.
#### Class Names
##### <mark>ClassName</mark>
CamelCase starting with an uppercase letter.
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
11
VERSION 1.1.0
#### Single-Line Comments
<mark># Single-Line Comment</mark>
Comments should start with a # followed by a space before adding the comment. Single-line comments should be placed one line above the code being explained.
#### Multi-Line Comments
<mark># Multi-Line</mark>
<mark># Comments</mark>
Each line should start with a # followed by a space to line up the starting word of each line.
#### Single-Line Documentation Strings
<mark>"""Single-Line Documentation String."""</mark>
Documentation strings are used for the first statement in functions, classes, and methods. These should appear after the _def_ line, have one additional indent from the _def_ line, and be wrapped in triple double-quotes on the same line as the comment itself. Each sentence should be terminated by either a period, question mark, or exclamation point.
#### Multi-Line Documentation Strings
"" <mark>"Multi-Line Documentation String.</mark>
<mark>Some Description.</mark>
<mark>Args, Returns, or Raises:</mark>
<mark>A description of what is returned.</mark>
<mark>Example: {foo: bar}</mark>
"""
Following the same guidelines as single line documentation strings, the main difference is the format (i.e., listing arguments, return format). Each description or summary line should be terminated by a period, question mark, or exclamation point. When writing more in the same comment block, there should be a blank line between the two descriptions. Each following line after the first, should start at the same indent spacing as the first quote in the first line. Each args, returns, or raises section title should end with a colon and the following description should be indented with tabs. Refer to Google’s Python Style Guide for more examples.
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
12
VERSION 1.1.0
Beginning with Ignition 8.1.32, custom project script functions that have docstrings defined in this manner are displayed via Ignition’s autocomplete.
#### Line breaks and other code style choices
For everything other than the items listed above, refer to <u>PEP-8. A number of naming</u> conventions in Ignition match PEP-8, and a number are different (like Variable Names and Function Names). When a choice isn’t covered in this style guide, use PEP-8 as a fallback reference.
<!-- Start of picture text -->
eee B= % exchange. resource nane. script<br>- 2 | selass classname: ~) fF © classine<br>(®) Nar Neicaton Pipcines 2° *"Single-Line Document Example explaining Classtane.**~ > fnctiontnclass<br>~ 2,Biseriing* Sequential Funcion chars 345 dot funetdontnclass(self1 Singie-Line coment explaining the Line of code below it ‘ functéonane<br>Ei Gateway Evers 6 print Hello world")<br>~ Bi Project ubrary 4<br>~ fa© exchangeresmuce ame ioef Functiontne(argueentOne,““"Wults-Line DocunentationargumentTwo)String<br>SSM srocner socuentation coment that<br>~ @ aPerspecvej Session Everts u3513, Arsewraps to another Tine<br>> bs soles 16 sxoumentOne: A boolean axsinent<br>» Views v7 SxourentTwo: Another boolean azgunent.<br>i Transacton Grou= 198 eturs<br>+ @vision cy Returns either True or False if the two argurents are both Trve,<br>» Bi named queries a<br>B reports 22 Classtane().functiontnctass(<br>B<br>26 Af srgumentone and argunenttwo:<br>Dretum True<br>22 alee<br>29” return False<br>2”<br><!-- End of picture text -->
### Database
Some database systems are case sensitive and some do not allow upper case in table or column names by default. The following standards will ensure consistent naming regardless of database platform. In general, use snake_case for naming all database objects. This means all lowercase with underscores between words for human readability. Hyphens or dashes are not accepted as names by all database platforms. Avoid numbers, sql keywords and special characters in names.
#### Schema Names
<mark>ex_resource_name</mark>
Schema names should start with ex followed by the Exchange Resource name to avoid sql import/create conflicts in pre-existing schemas.
<!-- Start of picture text -->
; s .<br>Ce Ignition’ /<br>automation — www.inductiveautomation.com by inductive automation e<br><!-- End of picture text -->
13
VERSION 1.1.0
#### Table Names
<mark>ex_<project name abbreviation>_table_name (ex_cm_contacts for example)</mark> Table names should start with "ex_" followed by the Exchange Resource's abbreviated project name to avoid sql import/create conflicts in pre-existing schemas.
#### ID Column
##### id
First auto-increment primary key column in all tables should be “id”. Being a primary key also allows Ignition’s database query browser to support the table fully, allowing users to edit fields with Ignition’s built-in tools. A consistent name for the primary key in all tables will aid in creating reusable components.
#### Foreign Key Column
<mark>foreign_table_name_id</mark>
Foreign key column names should be prefixed with the table name that the foreign key is referencing followed by “_id”. Thus making it easy to understand what table the foreign key ID is referencing.
#### Column Names
##### <mark>column_name</mark>
Use lowercase table names with no numbers or spaces.General Recommendations Stay consistent with column and table names. For example, do not use “order_no” for a column in one table and “order_number” in another table or “cust_number” in one place and “customer_number” in another.
<!-- Start of picture text -->
err | Table Name: |my_table Schema: test<br>gr Charset/Colation: [Defaulth v] [DefauitCo ©] Engine: {innoDa v]<br>Column Name Datatype PK NN UQ B UN Z AI G__ Defaul<br>vid INT 4MHUOoDooorDa<br>> column_a VARCHAR(45) OQodcooonouod<br>> column_b VARCHAR(45) Ooudcdoaoogod<br>© column_x VARCHAR(45) Ooodgoangaodag<br>> column_y INT OQoOoOoodgonvgunu ug<br>oooao00n0odao gd<br><!-- End of picture text -->
<!-- Start of picture text -->
Tay inductive oe cnson Ignition<br><!-- End of picture text -->
14
VERSION 1.1.0
### Named Queries
#### Query Names and Folders
##### <mark>Query Name</mark> or <mark>QueryName</mark>
Named queries can be either Title Case or PascalCase.
#### Parameter Names
##### <mark>parameterName</mark>
Use camelCase, starting with a lowercase letter. These are often used in scripts and component properties, so matching Python variable names and component property name convention makes sense.
<!-- Start of picture text -->
Project Browser ax<br>a a Exchange/ResourceName/QueryName<br>@ Alarm Notification Pipelines % Settings | Authoring | © Testing<br>4 Sequential Function Charts Database Connection Query Type<br>> G scripting <Default> + S| Query ’<br>> @ Perspective<br>8 Transaction Groups [yrameters<br>> © Vision Type Name Data Type +<br>~ B Named Queries value myValueX String 8<br>~ fmm Exchange Value myValueY Inta<br>PP Cercenare ~Reportsfam ResourceName |<br>@ web Dev<br>Query<br>1 SELECT column_a, column_b<br>2 FROM my_table<br>3 WHERE column_x = :myValueX<br>4 AND column_y = :myValueY<br>5<br><!-- End of picture text -->
### Alarm Notification Pipelines
Pipeline Names and Folders
<mark>Exchange/Resource Name/Alarm Pipeline</mark>
or
<mark>Exchange/ResourceName/AlarmPipeline</mark>
Alarm pipeline names can be either Title Case or PascalCase.
<!-- Start of picture text -->
inductive — 800.2667798 | iti \\ /<br>RICMELG | Seneca gnition\.<br><!-- End of picture text -->
15
VERSION 1.1.0
#### Custom Properties
##### <mark>propertyName</mark>
Use camelCase, starting with a lowercase letter. This matches the convention used in
built-in properties when accessed through Alarm Pipelines in expression or script blocks.
<!-- Start of picture text -->
Project Browser Bl _ X Pipeline Blocks<br>OF A<br>~~ @) Alarm Notification Pipelines r<br>~ fam Exchange<br>PT Catrreinenae #4~Sequentialfam ResourceName Function Charts | Is itd Tapo 0<br>> Bi scripting pi seerrovery[E<br>> @ Perspective ‘linus<br>Tag Browser ax<br>+Q CS | defauit vie<br><!-- End of picture text -->
### Sequential Function Charts (SFCs)
#### SFC Names and Folders
<mark>Exchange/Resource Name/SFC Name</mark>
or
<mark>Exchange/ResourceName/SFCName</mark>
SFC names and folders can be either Title Case or PascalCase.
#### Chart Parameter Names
##### <mark>parameterName</mark>
Use camelCase, starting with a lowercase letter. These are often used in scripts and component properties, so matching Python variable names and component property name convention makes sense.
#### SFC Block Names
##### <mark>BlockNames</mark>
Use PascalCase, starting with a capital letter and capitalizing the first letter of each word. Keep block names short and concise and avoid using multiple word names when possible.
<!-- Start of picture text -->
OF inductiveautomation —— 8002667798 www.inductiveautomation.com | gnitioniti “ e/<br><!-- End of picture text -->
16
VERSION 1.1.0
<!-- Start of picture text -->
Project reer ax<br>Q 4A<br>~ @ Alarm Notification Pipelines 7 ; 7<br>fam Exchange<br>> fm ResourceName ®<br>~~ ¢y Sequential Function Charts<br>~ fam ResourceName<br>| a SFCName 2 BlockName<br>> EB scripting<br>Tag Browser+- Q S defautt avesvii |, ><br>Tags UDT Definitions 4<br>Taa Value<br><!-- End of picture text -->
### SQL Bridge (Transaction Groups)
Transaction Group Names and Folders
<mark>Exchange/Resource Name/New Group</mark>
or
<mark>Exchange/ResourceName/NewGroup</mark>
Transaction group names and folders can be either Title Case or PascalCase.
#### Item Names
<mark>Item Name</mark> or <mark>ItemName</mark>
Item names can be either Title Case or PascalCase.
<!-- Start of picture text -->
Project ronser ax<br>a A Transaction Group > Enabled © Disabled<br>> . Execution Disabled<br>@ Alarm Notification Pipelines<br>> &% Sequential Function charts eee<br>» scripting ItemS Name SoureeV... | Latched... | Mode Target Name DataType ‘Properties<br>> @ Perspective ® OPCTagitem Item NAN NAN UseUse group’sgroup's modemode Read-onlyOPC_Item ‘StringString<br>+ 2 Transaction Groups z<br>[]> ©~ ~fapVisionCaltamcocenfapExchange Resource Name | unrItemAbays NameExpression Items SourceValueignore trigger (®) Latched Value | TargetName Data Type Properties i<br>BB Named queries Friggered Expression Items<br>Reports Tem Name. Source Value | Latched Value | Target Name Data Type Properties<br>© Expression Item NA NA Read-only ined<br><!-- End of picture text -->
<!-- Start of picture text -->
inductive 2002667798 | iti ‘ /<br>Nee Soman gnition’s<br>Dy inductive automation<br><!-- End of picture text -->
17
VERSION 1.1.0
### Reports
Report Names and Folders
<mark>Exchange/Resource Name/New Report</mark> or
<mark>Exchange/ResourceName/NewReport</mark>
Report names can be either Title Case or PascalCase.
#### Parameter Names
<mark>ItemName</mark>
Report parameters are uppercase with no spaces for multi-worded names. This format matches the default naming convention when adding new parameters.
#### Component Names
##### <mark>ComponentName</mark>
Component names should be PascalCase, starting with a capital letter and capitalizing the first letter of each word.
<!-- Start of picture text -->
a al oy<br>> aa Sequential Function Charts,<br>> Bscrtie L<br>+ @ respecte<br>G Session Events .<br>+ Be+ Viewste tare .EB 7<br>+ menrnnane<br>@ Anotherview'iame<br>+ Dviewvame<br>+ Broct @ = 4<br><!-- End of picture text -->
### Web Development Module (WebDev)
#### Source Names and Folders
##### <mark>exchange/resource-name/example-resource</mark>
Web Dev should be lowercase with dashes for multiple words. This format ensures that referencing the resource is web friendly.
<!-- Start of picture text -->
inductive — 800.2667798 | iti \\ /<br>automation — www.inductiveautomation.com gnition e<br><!-- End of picture text -->
18
VERSION 1.1.0
<!-- Start of picture text -->
Poet rower ax<br>a TA MtPuenos dose +) EQerbied (itera TPS Ree eraton .<br>> @) Alarm Notcabon peines def doGet~ request, session)<br>»> dyB Sequenvalscripting ancton chars Respondusing anytoofantheincomingfollowingHTTPkeysrequest. Formlate your response as a dictionary<br>> @ Perspective hte’ HTML source as a string<br>»» @vsionSj Tansacton Groups son’ A python dictionary sich will be encoded as ‘application/json’ data<br>B named queries ile’ A file path to send as the response<br>» G reports “bytes” A byte[] to send back. Mime type will be ‘application/octet-stream’<br>> @weboev Af not specified<br>7 moctorae<br>Vm roacecune esponse’ Any Any 3 type of f plainplain texttext response<br>contentType* The mine type of the response. Needed only if ambiguous<br>Aagunents<br>Tequest: A dictionary with information about the inconing web request<br>context: A reference to the Gateway's context object<br>data: The data on the zequest. If the content type 45 application/}son,<br>val be a Python structure (list or dictionary). If not, will either be<br>headersPlain(dict):textAvalues dictionaryor a rawwerebytereturnedof array.headerfor: valuethe sanepairs.header,If multiplevalues will be in a tuple.<br>parans (dict): A dictionary of URL paroneters. If multiple values were<br>returmed for the sane paraneter, values will be in a tuple<br>xenainingPath (stz): The xenainder of the URL after this resource<br>renotendor (str): Returns the IP adaress of the client.<br>renoteliost (stx): Returns the fully qualified nane of the client<br>schene (Stz): Retuans the nane of the schene used to make this request<br>de. “http’ or ‘netps<br>servietRequest: The underlying Java HttpServletRequest object<br>ServletResponse: The underlying Java HttpServletResponse object.<br>session: A dictionary that will be persistent across multiple requests<br>‘ron the sane session. If authentication is required, will have a “user<br>attribute containing information about the authenticated user, and a<br>retryAttenpts” attribute with the nusber of attegpts nade<br>2 retum {"html'; ‘<htnl><bodjoHello World /body></htal>")<br>@ crampleresource x<br><!-- End of picture text -->
### Loggers
Logger names should use dot separation to create a logging hierarchy, indicating where in the project the logger is used. To match the convention of other loggers used in the Ignition gateway, any logger name elements preceding the final period should be camelcase, and the logger name at the end should be PascalCase. Keep in mind that only the final logger name is shown on the logs, but a mouseover event will show the entire logger name.
It is recommended that loggers are called via scripts in the Project Library instead of directly on views, which can be difficult to find. In other words, scripts containing loggers should be called from views.
<!-- Start of picture text -->
exchange.resourceName.parseData.ConversionError Time Message<br>EE ConversionError 28,Jun2023 10:32:03, Cannot parse variable to expected type: Str<br><!-- End of picture text -->
<!-- Start of picture text -->
inductive 800.2667798 | niti n,/<br>automation — www.inductiveautomation.com g Dy inauctiveI 10automation e<br><!-- End of picture text -->
19
VERSION 1.1.0
Logger naming convention
<mark>exchange.resourceName.LoggerName</mark>
<mark>exchange.resourceName.script.scriptName.LoggerName</mark>
For projects with a large number of scripts in the project library, it may be appropriate to show an abbreviated path to the script. For instance, if the path to the script is “Exchange/MyResource/Utilities/ParseData”, a useful logger name would be “exchange.resourceName.script.utilities.parseData.ConversionError”
### Miscellaneous Designer Tools
#### Image Management
<mark>exchange/resource-name/image-name.jpg</mark>
Images uploaded using the Image Management should be uploaded under a folder hierarchy that starts with a folder named "exchange" followed by another folder named after the resource name. Folders and image names should be lowercase and use dashes between words. Image names should be meaningful and accurately represent the image.
<!-- Start of picture text -->
ll Image Management - o x<br>a@aciaQ@ @iF m®<br>Current Folder _exchange/resource-name/<br>e<br>ignition-ic..<br>Q Tip: You can drag images and folders into this window for easy uploading.<br><!-- End of picture text -->
#### Translation Manager
<mark>word</mark> (single-word translations)
<mark>_translation_phrase</mark> (multi-word translations)
If the translation key is a single word, the key should match the word being translated. If translating a group of text, start the key with an underscore and replace spaces in the key with underscores.
<!-- Start of picture text -->
inductive 8002667798 | iti ,/<br>AULoMatION _wmcntreetomaon.com gnition’.<br>by indetve automation<br><!-- End of picture text -->
20
VERSION 1.1.0
<!-- Start of picture text -->
‘Trandlation Manager 5x<br>Languages Translation Terms Qu<br>(All) + Key English (Alternate) Spanish +<br>English | @® _translation_phrase This is a multi-word text translation. Esta es una traduccion de texto de varias palabras. |»<br>[Spanish Dm word word palabra<br>a<br>a<br>*<br><!-- End of picture text -->
<!-- Start of picture text -->
F ‘ eye<br>inductive 8002667798 | nition: /<br>automation — wwwanductiveautomation.com g by indetve automation e<br><!-- End of picture text -->
21
VERSION 1.1.0
# Before You Upload to the Exchange
When your resource is finalized, there are a few steps that should be taken before uploading the resource to the Exchange. The purpose of checking your own resource is to make the process as smooth as possible and get your resource published on the Exchange in a timely manner. Following the steps below will insure this and help mitigate uploading incomplete or broken resources which will result in the resource being rejected until the issues are resolved.
### Things to check for:
#### Check the project export
If the resource to be uploaded is a project export, check that everything that needs to be included in the project was exported correctly. This can be done by importing the exported project into a brand new project and verifying that the resources works as expected.
#### Include the tags
Does the resource require tags and/or user defined tags (UDTs)? If the resource requires tags, make sure to export the necessary tags and/or UDTs. Then follow the same procedure as <u>Check the project export</u> and make sure all the tags needed in the project are included in the tag export.
#### Don’t forget database backups
Does the resource reference a predefined table structure or include example data? Include the necessary database dumps when uploading to the Exchange and make sure to state the database vendor (i.e., MySQL, MSSQL, PostgreSQL, etc.) being used in resource description and custom installation instruction step when uploading to the Exchange.
Take notes of the steps taken when checking your project export
When uploading your resource to the Exchange, there will be a section for Custom Installation Instructions. This is where you will give step-by-step instructions on how to set-up your resource to ensure that users get started correctly. It is important to understand that the Ignition experience level of users downloading resources from the Exchange vary from beginners to intermediate so it is important to be as clear and concise as possible.
<!-- Start of picture text -->
i tive 300.266.7798 rf bed ,/<br>OU Ignition.<br><!-- End of picture text -->
22
VERSION 1.1.0
# Uploading to the Exchange
The following steps go over best practices for uploading a project to the Exchange. For each section of the Exchange upload process, please fill out the following to the best of your ability.
### Overview Section
#### Visibility
Unless the project is a private project and not intended for public use, it is recommended that the visibility of the project is set to Public (Visible to everyone).
<!-- Start of picture text -->
Visibility Public (Visible to everyone) ~<br>publish<br><!-- End of picture text -->
#### Title
The title should be short, concise, and identify the functionality and/or purpose of the project being uploaded. In most cases, if this is a project being uploaded, the title can match the project title given for the project. The resource title should be formatted in Title Case.
<!-- Start of picture text -->
Title Perspective User Management fa]<br><!-- End of picture text -->
#### Tagline
The tagline is a short description that accompanies the title to give users a better general understanding of the functionality of the project. This should be a one sentence, short description of the project and should not match the title.
<!-- Start of picture text -->
Tagline User Management tool for Perspective projects<br><!-- End of picture text -->
#### Description
The description expands upon the tagline to give a more detailed explanation of the project, how it is meant to be used, what types of people would benefit from this resource, etc.
<!-- Start of picture text -->
inductive — 200.2667798 laniti \\ /<br>automation — wwinductiveautomation.com gnitione<br><!-- End of picture text -->
23
VERSION 1.1.0
<!-- Start of picture text -->
Description | Bo J 32 i=<br>This Perspective User Management tool allows users to add, edit, and remove users and roles<br>from the Gateway.<br>c a detailed description of your resource. Include information likehow you<br>envision it being used, what types of people might benefit from this package, any<br>relevant industries, etc<br><!-- End of picture text -->
#### Resource Type
Choose the best resource type from the drop down that best describes the type of resource that is being uploaded. Then choose a skill level that best fits the complexity of installation and use.
<!-- Start of picture text -->
Resource Perspective View ’ Beginner +<br>Type<br>Choose a primary resource type that Choose a skill level that best describes<br>best describes your resourc the complexity of installation and use<br><!-- End of picture text -->
#### Background Image
The background image is an optional step for adding a color and design to the background of the Exchange resource card and page.
<!-- Start of picture text -->
Backgroundvena © 960035930<br>ustomize the background of your resource with a colorful desi<br><!-- End of picture text -->
#### Category
The category section is used for filtering Exchange resources. In order to ensure that the resource being uploaded gets proper exposure on the Exchange, select up to 3 categories that best match the resource provided.
<!-- Start of picture text -->
inductive — 8002667798 | iti “ /<br>Nee Soman gnition’s<br>by inductive automation<br><!-- End of picture text -->
24
VERSION 1.1.0
<!-- Start of picture text -->
Category Alarming Analytics Connectivity Dashboard<br>Diagnostics Edge Computing Enterprise HMI<br>vortacs HOT/MQTT MES Maintenance<br>Mapping/GIs Mobile Monitoring<br>Reporting SCADA Scripting Security<br>Simulation Trending/Charting Utility<br>Resources are displayed by category. Select up to<br>3 categories.<br><!-- End of picture text -->
#### Contact the Developer
Enabling the Contact the Developer functionality allows users to directly email the resource developer with any questions or concerns about the resource. There are two options to choose from. The first option being “Let contributors contact me about all my exchange resources”, will allow all visible resources uploaded in your account to be available for contact. The second option “Let contributors contact me about this resource”,will only enable this feature for the resource that is currently being uploaded.
- **Note** : Your email address will not be shown to users that are attempting to contact you. If someone chooses to contact the developer, you will receive an email with the question and the user’s email address. You will then have the ability to contact the user directly.
<!-- Start of picture text -->
Contactthe —_Let contributors contact me about all my exchange resources ©<br>Developer<br>Let contributors contact me about this resource ©<br>This feature allows contributors to contact you via email directly from the resource page<br><!-- End of picture text -->
#### Tags
Tags are another way for the resource to gain exposure on the Exchange. With the ability to create up to 10 tags, these tags will help the resource show up in the results when those tags are used as keywords in the search bar.
<!-- Start of picture text -->
inductive 8002667798 | iti AY /<br>automation — www.inductiveautomation.com gnitions<br><!-- End of picture text -->
25
VERSION 1.1.0
<!-- Start of picture text -->
Tags<br>: Tag: ke y s( mo arc Cc ul 10 ta<br>User Management x Users x<br><!-- End of picture text -->
#### Images & Screenshots
Images and Screenshots, though optional, are highly encouraged to be included with the resource. Images, for example project views, give users a better understanding of the project that cannot be explained in the title and description alone.
<!-- Start of picture text -->
Images&<br>Screenshots<br>@<br>Drop files here to upload<br>(up to 10mb)<br>Or choosea fle<br><!-- End of picture text -->
### Package Section
The package section is where the resource files will be uploaded and information about Ignition and module requirements are defined.
#### Version
Unless uploading a subsequent package version, this package version should be Version 1.0.0 and any subsequent updates will be auto-incremented unless specified by the uploader.
<!-- Start of picture text -->
Version 1 oO oO<br><!-- End of picture text -->
#### Ignition Platform
The Ignition version should be the minimum version needed in order for the package being uploaded to be installed and run correctly. If unsure, select the Ignition platform version in which the package was developed with.
<!-- Start of picture text -->
inductive — 8002667798 | iti “ /<br>automation — wwwinductiveautomation.com gni Ione<br><!-- End of picture text -->
26
VERSION 1.1.0
<!-- Start of picture text -->
Ignition Platform 81 * 3 ~<br>Choose the minimu f Ignition required<br><!-- End of picture text -->
#### Release Tagline
The release tagline summarizes the changes that were made to the package version being uploaded. A title will be needed for the initial release version as well.
<!-- Start of picture text -->
Release Tagline _nitial release fa}<br>Create a short but descriptive tagline to help identify what changes were made in this version.<br><!-- End of picture text -->
#### Release Notes
The release notes give a more detailed explanation of the changes in the package version. Use this area to expand on the release tagline, give more information about the version, and explain how this version will impact the resource. The release version is required even for the initial release version, but may not include as much detail as subsequent version releases of the package.
<!-- Start of picture text -->
ReleaseNotes = B J i= 15<br>Initial release<br>Listwere madedetailed andreleasehow theynotes willexplainingimpactwhat changedin this version. Think about what improvement<br>the resource.<br><!-- End of picture text -->
#### Required Modules
If the resource requires any modules to be installed in order for the package to work correctly, select the required modules by expanding the accordion for the Inductive Automation Modules, Cirrus Link Solutions MQTT Modules, and/or Sepasoft, Inc. MES Modules.
<!-- Start of picture text -->
Required . .<br>Modules Inductive Automation Modules Vv<br>Optio<br>Cirrus Link Solutions MQTT Modules for Ignition Vv<br>Sepasoft, Inc. MES Modules for Ignition Vv<br>Choose any modules that are required when using this resource<br><!-- End of picture text -->
<!-- Start of picture text -->
inductive 8002667798 | iti AY /<br>AULoMatION _wmcntreetomaon.com gnition’.<br>by indetve automation<br><!-- End of picture text -->
27
VERSION 1.1.0
#### Maker Edition
Maker Edition is a non-commercial, personal use only version of Ignition which is intended for hobbyists, students, and individuals. If the package being uploaded is intended for Maker Edition or will run in Maker Edition, enabling this option will let users know the package can be installed for their Maker Edition version of Ignition.
<!-- Start of picture text -->
Maker Edition Let people know this resource is Maker Edition compatible.<br>fora This optionis unavailable for resources requiring unsupported Maker Edition modules<br>Learn more about Ignition Maker Edition™<br><!-- End of picture text -->
#### Other Requirements
If there are other required items that need to be installed for your resource to work they need to be listed in the Other Requirements section. If there are no additional requirements for your resource this field can be left blank.
<!-- Start of picture text -->
Other +<br>Requirementspron List any other extemal or custom requirements as separate line item<br><!-- End of picture text -->
#### Package Files
Upload all files here that will be needed to ensure your project works as expected. This includes your project backup, tag files, etc.
<!-- Start of picture text -->
Package Files<br>B®<br>Drop files here to upload<br>(up to 10mb)<br>Or choose a file<br>Uploaded files<br>UserManagement.zip 08.97KB X<br>Identifying common file types will help to reducethe complexity of installatior<br><!-- End of picture text -->
#### Custom Installation Instructions
Detailed instructions are highly encouraged for resources as they assist the users that download your resource in understanding how to utilize your resource. These instructions
<!-- Start of picture text -->
inductive 8002667798 | iti AY /<br>Nee Soman gnition’s<br>Dy inductive automation<br><!-- End of picture text -->
28
VERSION 1.1.0
should include any necessary steps around uploading your resource and any required modules as well as instructions on how to utilize your resource once it is installed.
- **Note:** If you already have detailed documentation for your resource please note it here and include the documentation file in the Package File upload.
<!-- Start of picture text -->
Custom Installation Instructions Optionc<br>**Please Note: Managing users and roles outside of the Gateway may allow others to exploit the<br>security of your Gateway. Please refer to our Ignition Security Hardening Guide on ways you can<br>secure the Perspective User Management view from being used for malicious reasons.<br>https: //inductiveautomation.com/resources/article/ignition-security-hardening-guide#step--define-<br>application-security .<br>Provide clear and concise documentation to help other people understand how to install yo<br>files.esource.InstallationThis is onlyinstructionsnecessaryfor knownif you havefile typesselectedwill be “other”automaticallyas your filetypegeneratefor any uploaded<br><!-- End of picture text -->
### Helpful Notes
- The Exchange will automatically generate a readme file from the information you have entered in the Resource Description and Custom Installation Instructions during the upload process
- If publishing your resource in a non-English language we encourage you to include a dropdown that allows your project to be displayed in your native language as well as English. This will increase community access to your project.
- As shown above, capitalized top level resources can be Title Case or PascalCase. Title Case increases readability, matches the default format from the Ignition Designer when creating new resources, can differentiate the resource name from the sub-resources like component names, and creates files on disk with spaces. PascalCase avoids spaces in filenames on disk, is still fairly readable, matches resource names from sub resources like component names, and is preferred by some Ignition users. Both are acceptable choices.
<!-- Start of picture text -->
inductive — 8002667798 | iti “ /<br>Nee Soman gnition’s<br>by inductive automation<br><!-- End of picture text -->
29
VERSION 1.1.0
View Git Blame Copy Permalink