Scope - AppDaddy-Software-Solutions-Inc/framework-markup-language GitHub Wiki

A widget's scope is analogous to a variable's scope in any standard programming language. If a variable by the same name, in this case by the same id, is defined locally, that variable takes precedence over a variable by the same name defined at a higher level in the scope hierarchy.

Scope is an important concept and is used extensively in data binding.

A widgets id must be unique within the scope in which it is defined. When a widget is referenced by its *id, the system only looks up the scope scope hierarchy to find it. The only exception to this rule is if the scope's id is used as part of the binding syntax.

Scope Hierarchy

The scope hierarchy is made up of both static and *dynamic scopes.

Static, or named scopes are SYSTEM, APPLICATION, USER and STASH. These are automatically generated by the system when the application is launched. These are explained in more detail below.

Dynamic scopes on the other hand are created based on the widget. The <FRAMEWORK/> widget, and multi-child widgets like <LIST/>, <GRID/>, <MENU/> and many others, by default, create each of their children within a unique scope.

A widgets scope can also be specified using the scope attribute in the widget's markup.

Named Scopes

SYSTEM

SYSTEM level scope values are addressable using {SYSTEM.attribute} binding syntax and exist over the lifetime of the system.

Name	Type	Description
connected	bool	Indicates status of the connection to the internet
scheme	string	Indicates status of the connection to the internet
domain	string	Indicates status of the connection to the internet
host	string	Indicates status of the connection to the internet
rootpath	string	File path to the application. Null on web.
version	string	The Framework Markup Language version.
platform	string	The base platform (Android, IOS, Web)
os	string	The operating system name
osversion	string	The operating system version
screenwidth	int	The width in pixels of the current display
screenheight	int	The height in pixels of the current display
mouse	bool	Indicates the presence of a pointer device such as a mouse
uuid	string	Generates a new guid when first bound

See it in Action

APPLICATION (GLOBAL)

APPLICATION level scope values are addressable using either {APPLICATION.attribute} or {GLOBAL.attribute} binding syntax and exist over the lifetime of the application.

APPLICATION scope is based entirely on the global.xml file on the root server. When the application is launched, the system attempts to find and download this file. Once downloaded, this file is parsed and deseraized like any other template page. It can contain any number of FML widgets. Adding visual widgets is, although syntactically correct, of little use since this template is never rendered on the display. Typically *global.xml would only contains variable widgets like <VAR/>, <INT/>, or <BOOL/>, etc) and/or data sources that the developer wishes to make addressable from anywhere in the application and persist across the lifetime of the app.

USER

USER level scope values are addressable using {USER.attribute} binding syntax. They are made up of a mix of both static and dynamic values set during authentication.

Static bindables are shown in the table below.

Dynamic bindables are set after the user successfully authenticates and are cleared again when logoff() is called. These values are set from the public claims segment of the json web token or jwt. For every claim a corresponding bindable is created by the same name.

Dynamic USER bindables are readonly.

Name	Type	Default	Description
connected	bool	false	Indicates is the user has successfully authenticated. On logoff() the value is reset to its default.
rights	int	0	Indicates the current rights level. This value is set after successfull authenticated and is taken from the rights value passed as part of the jwt's public claims segment. On logoff() the value is reset to its default.
langauge	string	english	Indicates the preferred langauge. This value is set after successfull authenticated and is taken from the language value passed as part of the jwt's public claims segment. On logoff() the value is reset to its default.
jwt	string		Stores the jwt after successfull authenticated. On logoff() the value is cleared.

STASH

STASH level scope values are addressable using {STASH.attribute} binding syntax and exist over the lifetime of the application.

STASH bindings are dynamic and operate much like cookies do on the web. They are created by way of the set() method.

STASH values are written to permanent starage and exist indefinitely or until cleared using the clear() method.