12 Customize Variables and Constants

Variables and constants store static values and expressions that are used in components and pages. For example, they might be used to store data that will be used in an action chain, to store input parameters for a form, and to store strings and values that will be used to define how pages and components in your app are rendered and behave.

To give a simple example, a dependency might use a constant to store the color or the text of a heading in a page. If the dependency developer has made the constant editable by extensions, you can configure the constant to change its value (and thus the heading's color or text). In addition to configuring variables and constants defined in dependencies, you can, of course, create additional variables and constants you may need to configure the pages and Layouts.

Both variables and constants are used to store values. Specifically:

• Variables are typically used to store values used within a page's UI or an action chain. For example, you would use a variable for an input text or a total when performing an action in the page like adding items to an order, but variables can also be used for property values like a text color or font size.
• Constants are typically defined in a dependency, and their values often don't change after they are set by the extension. For example, a dependency might define a constant like contactPageHeading that determines the text in a heading in a page. Your extension can write a value to the constant, and that value will be used every time contactPageHeading is used in your app. The default value of a constant can be static, but it could also refer to expressions that contain variables. If the expression contains variables, the constant's value would change when the variables change, and you can configure the constant to emit an onValueChanged event.

Variables and constants have a scope that defines its lifecycle. The scope is defined by where the variable or constant is defined, so if you create a variable in a page, it would have a page scope. When configuring dependencies, most variables and constants will have one of the following scopes.

Scope	Description
Page	Variables and constants with a page scope can be used by components and actions within the page, including dynamic containers, but are not accessible from within dynamic forms and tables. These are typically defined in the dependency and are listed in a page's Variables editor if they are editable or readable. For example, the dependency might define an editable constant that you can use to toggle the display of a component. You create and edit page-scoped variables in the page's Variables tab.
Layout (dynamic forms and tables)	Variables and constants with a Layout scope can be used by components and action chains within dynamic forms and tables, for example, within field templates. You create and edit them in the Layout's Variables tab. For example, you might use a variable in an expression in a field template. Dynamic containers use page-scoped variables and constants.
Action Chain	Variables that are created in an action chain can only be used in the action chain where it is created. You create and edit variables with this scope in the Variables tab of the action chain, not in the Variables tab for Layouts or pages.
Fragment	Variables defined at the fragment level can only be used within that fragment. You create and edit them in the fragment's Variables tab. Additionally a fragment, though referenced by an outer page, cannot directly reference variables defined in the page. However, a fragment developer can bind a fragment variable enabled as an input parameter to a page-level constant. For details, see Bind Fragment Input Parameters to Page Constants.

When creating field names for variables, if you want to use any special characters (period, colon, dash and space), you'll need to enclose it in bracket notation. For example, an object variable that contains a field called 'child.field' will need to be referenced as $variables.objVar['child.field'].

For each variable you must specify a Type property to define the type of data that is stored in the variable. Types are also either page-scoped or Layout-scoped. When defining the type for a variable, you'll usually want to choose one of the standard built-in types used to specify data that are a primitive type, a structure or a simple array or collection. If the built-in types don't meet your needs, you can create custom types and types based on an endpoint in the Types tab of your page or Layout.

Note:

If a dependency defines types that can be used in extensions, they will also be displayed in the Types editor tab, and you can select them in the Type dropdown list when you create a variable.

For more about using variables, constants and types in your extension, see Work With Variables, Types, and Constants in Part 4 Build an App UI or Fragment.