Skip to main content
System StatusContact Support
VersionOne Community

Canvas Session Properties and Variables

This feature is available in Ultimate edition only.

editions-u.png

Overview

Layouts and Widgets can both specify a Session property. This Session can be shared across multiple Widgets and Layouts, allowing a complete, multi-page user experience to be designed.

When a Canvas resource is requested, variable substitution happens several times during the lifespan of the request.

Generic Initialization

When a Layout or a Widget is requested, the following process flow is observed:

  1. Any Querystring arguments or POST data are added to the Session. On naming conflicts, POST data > Querystring.

  2. The definition is parsed, and any [$variables$] in the definition are replaced from the POST data and/or querystring.

  3. Any [=keywords=] in the definition are considered.

  4. The definition is JSON validated and loaded.

  5. The Session property is checked and a Session is established. If the Session property matches an existing Session, that Session is loaded.

  6. POST/querystring arguments are merged into the Session. On naming conflicts, POST data > Querystring > existing Session value.

  7. After the Generic Initialization, the following flow is specific to the requested resource type.

Layout

  1. The Layout content is constructed using the various options in the Layout definition.

  2. The final Layout is parsed one last time, and any new [$variables$] are replaced.

  3. The Layout content is delivered to the requestor.

Widget

Widgets are dynamic and flexible resources, but in regards to Variable replacement, the flow is always the same.

The Widget data is obtained using the various options in the Widget definition.

The data is parsed and any [=keywords=] are processed.

The data is parsed and any [$variables$] are replaced.

If the Widget has the variable_name option, the data itself will be added to the Session using the key defined by the variable_name option.

Variables vs. Keywords

There are two similar but distinctly different escape syntaxes supported by the Canvas API - Variables and Keywords.

Variables

Variables are identified using the [$varname$] escape syntax. When this pattern is encountered, the Canvas API will attempt to replace the token with the Session value identified by 'varname'.

Some variables may contain data structures, such as a list or a dictionary. When directly referenced by [$varname$], a string representation of that object will be returned.

If a variable contains a data structure, subelements can be accessed using the jsonpath notation, which is very similar to xpath.

GLOBAL Variables

A small set of global variables are defined for advanced developer use cases.

These variables are available at all times:

  • __PROJECT - Project of the current Canvas resource.

  • __COMPONENT - Component of the current Canvas resource.

  • __NAME - Name of the current Canvas resource.

  • __REPO - Repository of the current Canvas resource.

  • __PATH - Path of the current Canvas resource.

The following variables are only available if the Canvas is authenticated:

  • __CURRENT_USER_ID - ID of the current user.

  • __CURRENT_USER_FULL_NAME - Full name of the current user.

  • __CURRENT_USER_EMAIL - Email address of the current user.

  • __CURRENT_USER_TAGS - 'Tags' associated with the current user.

  • __CURRENT_USER_APPLINK - An authentication token for the current user. If passed on the url as applink to another CSK application, will attempt pass-thru authentication.

Keywords

Keywords are not variables - think of them as inline functions.

Keywords are a small list of specific functions executed when the keyword is encountered. In most cases, a [=keyword=] will, like a variable, be replaced by a value. However, instead of a Session variable, the keyword is replaced by the data generated by an internal function.

The following keywords are supported:

[=wrap=]

The 'wrap' keyword simply wraps a variable with a prefix and suffix.

[=wrap(myvar,"BEGIN", "END")=]

If the Session variable 'myvar' exists and has a value of 'foo', the preceeding statement would return

BEGINfooEND

[=session=]

The 'session' keyword will simply return a JSON representation of the current Session. Useful for temporary debugging on a Layout, or getting a current Session object for use in Javascript. (An alternative approach is the "session" Widget type.)

Take care in your script - Session is a dynamic structure. If the [=session=] keyword isn't wrapped in proper client-side error handling, it's inclusion could break your script.

[=widget=]

The 'widget' keyword allows a developer to include the data content of a widget within the content of another Layout or Widget. Useful for generating complete content on the server and delivering a single response to the client.

The syntax of the 'widget' keyword is simple: [=widget{args}=], where {args} is the full identification of a Widget. For example:

[=widget{"project" : "examples", "component" : "shared", "name" : "common.widget"}=]

The following shorthand is also accepted:

[=widget{"p" : "examples", "c" : "shared", "n" : "common.widget"}=]

Any additional properties provided within the args will be added to the Session of the target Widget.

[=layout=]

Just like the 'widget' keyword, the 'layout' keyword will include the complete content of another Layout.

The syntax of the 'layout' keyword is simple: [=layout{args}=], where {args} is the full identification of a Layout. For example:

[=layout{"project" : "examples", "component" : "shared", "name" : "common.layout"}=]

The following shorthand is also accepted:

[=layout{"p" : "examples", "c" : "shared", "n" : "common.layout"}=]

Any additional properties provided within the args will be added to the Session of the target Layout.

  • Was this article helpful?