Perspective Component Properties

User Created Properties

Perspective has two distinct types of user-created properties: 

• Pre-defined properties in a component that has its own schema. We don't recommend creating additional properties to components with their own schema, although it is possible. In the event something should go wrong or inconsistencies occur, it's difficult to figure out if the problem is with a user-created property that's part of the component's schema or with a custom property in the Custom Category.
• Custom Properties fall under the Custom Category in the Property Editor. This type of user created property is unique, and is used to enhance functionality to a component through the use of data bindings and scripts. Custom properties created in the Custom Category will not result in any collisions with any pre-defined properties that are part of the schema of the component. Creating a custom property in the Custom Category is considered best practice. 

Property Data Types

Before you create a property, you must first understand the different property data types. There are three property data types available in Perspective's components: value, object, and array. When you create a new custom property, you must first select the appropriate property data type based on how you want the component to behave or appear. The table below describes each property data type.

Property Types
Value	A value is an single variable for the property. It has a 'key" and a "value". "Key" is the name given to the property, and "value" is the actual value of the property. Value types are as follows: Boolean - A true/false value. Numeric - An integer up to the maximum value for a long integer. String - A string of characters can be numeric, alpha, or a combination
Object	An object is a one or more values stored under one variable name. Objects are indicated by curly braces { }. In this example, the Object has three sub- properties.
Array	An array can hold many values under a single name, and you can access the values by referring to an index number. Array is indicated by square brackets [ ]. A good example of an array is the Thermometer component's default setup as shown in the example below. There is an array called "intervals" with three values, 0 through 2. Each of the array items is an object type that has three values: color (string), high (numeric), and low (numeric).
Dataset	The Dataset property type is not an option when changing a properties data type, it can only be used when a binding returns data in a dataset format. A Dataset lists the number of rows and columns [rowsxcolumns] and has an Edit Dataset icon that appears after a binding has been created. This icon brings up the Dataset Viewer panel and allows you to make changes to the raw data. Note that any changes will be overwritten the next time your binding polls. Datasets are generally only returned by SQL queries and Tag History bindings, though both have the ability to select from several different return formats. A good example is a table bound to a Historical Tag query like the image below. The following feature is new in Ignition version 8.0.5 Click here to check out the other new features Dataset properties now have an dataset viewer and editor in Perspective's Property Editor. Once a property is bound to a dataset, you can access the viewer by clicking on the Dataset Browser icon. With the Dataset Editor you can add and delete columns and rows, delete all rows, and copy information to or from the clipboard. The Dataset Editor icons and their corresponding actions are shown below.  Icon Action Add row Delete selected rows Add a column Delete selected column Delete all rows Add to clipboard   Paste from clipboard

Property Categories

Each Perspective component has a list of available properties. Each property is placed into one of several categories, and each property category groups the properties by some commonality. The property categories are described below. 

• Props - Properties that control the component's configuration and provides the runtime data for how the property appears and behaves in a session. See individual Perspective Components for a list of the properties and their descriptions. 

• Position - Properties defined by the component’s parent container control where the component is located inside the container. The available properties listed under this category depend entirely on the container type that the component is placed in. For more information, see the pages for each type of container.

• Custom - The Custom category was designed as an ideal location to add Custom Properties. To create a new custom property, all you need to do is select a property type such as Value, Object or Array. For example, if you want to add a single property, select "Value" and you'll see it has " key" and "value" objects. Rename "key", to give the property a unique name, and change the "value" by entering number or string

• Meta - Properties defined by the Perspective Module itself for common things like the component’s name, and if the component is visible.  

• Params - Only available on Views. This category of properties is used when passing parameters from one view to another view via navigation, or the Perspective - Embedded View component

The following image shows an example of the Property Editor for a Button component. Note that each property is listed under a category: Props, Position, Custom, and Meta. 

Add additional properties by hovering over an existing property and clicking the Add icon, then select Value, Object or Array, or by clicking the Add Property  icon at the bottom of the category.

Restricting Property Access

Perspective components have the ability to restrict access to properties from the app/browser. Property access settings do not restrict or inhibit built-in component interactions with bindings and python scripts. Instead they protect against malicious code execution in the browser. Normally a user can potentially execute arbitrary JavaScript code via developer tools (which generally are included with all web browsers) to interact with components and properties in the session. However setting property access level to Private or Protected will prevent such approaches, as browser-side script execution will be unable to access property values on the server side.

To understand what property access in Perspective is, you'll need to understand how the Document Object Model (DOM) works. In short, each active session is represented in a browser (which is the user interface side of the DOM) and on the Gateway (the back-end of the DOM). Interacting with components on the browser-side, such as writing to the text property on the text field, impacts the back-end and allows the gateway to react appropriately (i.e., trigger a property change script). 

When a property is set to Public, then arbitrary JavaScript execution can freely write to the back-end, which is likely undesirable in most cases. However, a property set to Protected will disregard any such write requests from the browser, meaning only the back-end is allow to write to the property (i.e, Bindings, component Script Actions, etc). However the browser-side of the DOM is still interactable, but the back-end will ignore such value changes. 

In this same example, setting a property set to Private will also disregard write attempts, in addition to remaining hidden from any read attempts made by the arbitrary JavaScript. 

One caveat property access is that the names of style classes are always visible and interactable from the browser, so style class names should not included sensitive information. 

Restricting Access to Component Properties

In the example below, we used an LED Display component to restrict access on the components 'value' property.
Restricting Access to Component Properties

1. In the Property Editor, select the property you want to restrict access on.

2. Right click on the property, select Access and choose the restriction level: Public, Private or Protected.
   
   
   
   

3. Once the restriction access is configured, the Property Editor will place a badge on any non-public property: Private , Protected , and System .
   
   

Writing to Private or Protected Session Prop

To write to a Private or Protected session prop,you can write to it through a scripting action, as shown below.

You can also use a property binding to write to a Private or Protected session prop. Remember to enable the bidirectional option.

Persistent Properties

By default, component properties and their values are saved with the project. Meaning that a property in a Perspective Session will initialize with a value matching the last saved value. This is why you can create a label with a static text value, save, and then see the same text value in the session. These properties are considered Persistent. 

Conversely, properties can be configured to not retain their value in the session, meaning they'll initialize without a value. These properties are not Persistent . These properties are denoted by the Transient  icon to the right of the property's value in the Property Editor. 

Changing the Persistent state of a property can easily be accomplished by right-clicking on a property in the Property Editor, and toggling the Persistent option. 

Persistence and User-Created Properties

User created properties missing the Persistent flag will not be saved in your project. Meaning, properties that are both user-created and not flagged as Persistent will be lost once the view containing the property is closed in the designer (not just the value, but the property itself), regardless of whether or not the project was saved. This is also true for launching a session, as the user created property that is not Persistent will not be present in the session. 

The one exception to this rule is if a binding was configured on the property. Binding configurations are always saved along with the component, and will execute in the session. The existence of a binding on a property will result in the property being re-created in the session. 

Bindings and Persistence

When configuring a binding on a property, the property will automatically be configured to not persist. The idea being that properties with bindings generally don't need to save their value along with the view: when a view is opened, all bindings will need to evaluate on startup, which means the last saved value on the property is likely to differ from the result of the binding.

Imagine a table component, with a binding on the table's data property. In most cases, you'll likely want the data in the table to be generated in the session from the binding, retrieving the most update-to-date results. In this case, it doesn't make sense to persist the dataset in the table along with the table, as it's just extra data that will quickly be replaced by the binding at runtime.

Bound properties default to a non-persistent configuration, but sometimes this isn't desirable. For example, Embedded View components have an empty state when their "path" property is blank. When a binding is placed on the path property, opening the parent view will result in the Embedded View quickly transitioning between the empty state and the loaded view, which can cause an undesirable "flash" as the binding evaluates. This can be prevented by configuring the property as Persistent, and configuring an initial path for the Embedded View (which can lead to an empty placeholder view), allowing for a controlled transition. 

Custom Properties

User-created properties may be added to any property category such as the Props, Position, Custom and Meta Property Categories to enhance functionality. The Custom Category was designed as an ideal location in the Propety Editor for users to create their own custom properties. These Custom properties allow components to store additional values which can be accessed by bindings and scripts. They are also important for passing parameters from one view to another. 

Creating Custom Properties

In the following example, we used the Thermometer component to add some custom properties in the Custom category. 

1. Custom Properties are created by clicking on the "Add Custom Property..." link, or by right clicking on a property in the Property Editor to bring up the Action Menu. There are three property types to choose from: Value, Object, and Array.
   
   

   
   
   

2. Several custom properties were created under Custom in the Property Editor showing each of the different property data types (i.e., value, object, and array).
   
   
   
   

3. In the image below, next to the Thermometer, three Text Fields were added to a view to write to each of the different custom properties in the Thermometer. Each of their binding paths are listed next to the fields which are bound to the same custom property so you can see the difference when the values changes on the labels.
   
   

   

Meta Properties

Meta properties are defined by the Perspective Module itself for common things like the component’s name, and if the component is visible. Every Perspective component features Meta Properties. Each property under this category is listed below. 

Params

Params are a category of properties that are used when passing parameters from one view to another view. The properties inside of the params category define parameters that can be passed in and out of a view. It's through the use of parameters that views interchange information with other entities such as a docked view, embedded view, or a page. To learn more about using parameters to pass properties across views, refer to Property Bindings in Perspective. 

Docked View

When configuring a page, it's possible to pass a value to a docked view. When you click on a docked view, you can specifiy one or more param properties in the View Parameters field of the view that is docked. If you have any param category properties defined on that view, this interface allows you to pass a value when you navigate to the configured page. To learn more, go to Configure Docked View Parameters.

Embedded View 

The embedded view component allows you to embed one view inside of another. The only way to pass a property across views is by passing a view parameter into an embedded view. Parameters can be defined as input, output, or both input/ouput. Once you have param properties configured on your views, the embedded view component provides you with access to these parameters. You have options on how to pass a property into an embedded view. How to set up passing a parameter depends on how you design your project. You can set up passing a property to an embedded view using a parameter with property bindings, Tag bindings, or even scripts. For more information on embedded views, refer to Pass a Property into an Embedded View Using a View Parameter and View Properties.

Page 

Passing parameters to a Page essentially means passing a URL parameter to a page. Parameters are used to allow a page to be mounted at a dynamic URL, allowing information in the URL to be interpreted as input parameters to the page’s primary view. A primary view can see whatever parameters are passed in, and components inside the view can bind or use the values in some useful way. 

The way you add parameters to the Page URL is by mounting the page at a special URL using a parameter replacement syntax like so:  <page> /:towerNumber. The dynamic URL mounting uses a colon to signify that a portion of the URL is meant to by dynamic and map to an input parameter on the page’s primary view. To learn more, go to Passing parameters (URL Parameters).

Search Filter

In the Property Editor search bar, you can search for component properties. Start typing in the search bar and the property list updates based on the text you enter. You can also set filter options to make the search case sensitive, or use wildcards, regular expressions, match from start, match exactly, and match anywhere. 

Bindings

Most properties have binding options. For more information on bindings, see Types of Bindings in Perspective. The image below shows the properties in the Property Editor that are set on a Cylindrical Tank component. There are Binding  icons to the left of each of the properties that appear when you mouse over them. If you have a Cylindrical Tank on your view and click the Binding icon for the "value" property, it will open the Binding window and you can set what the Cylindrical Tank component is bound to. In this example, the "value" property of the Tank is bound to the un10013 OPC Tag. 

Styles

A full menu of style options is also available for text, background, margin and padding, border, shape and other miscellaneous settings to adjust the appearance of your components. Style classes enable you to set up a particular look and feel (fonts, colors, borders, etc.) once and then apply it to multiple components.