Session Variables and Cookies

A session variable is a name-value pair maintained for the duration of the session by the GAS. A session variable is accessible from the user agent, the application, and the GWC snippet-based rendering engine.

In order to make a session variable persistent between two runs of an application, you must store the session variable in an HTTP cookie. The cookie is a text-only string containing the name-value pair and is saved into the memory of your browser. The cookie is then sent back to the GAS on all future requests for the application.

Back to the top

Why Session Variables? Use Cases

There are a variety of reasons why you would want to introduce a session variable. For example:

You can have an application set a session variable and use it inside a template snippet, without having to design a form field or a static label in the form.
You can place a hidden field in an HTML form that will be sent along with other form data (and fetch them from the application) without having to design a form field in the 4GL form.
From the client-side front-end (CSF), you can use a session variable to hold data that can be used from inside a template snippet to keep a state between two page updates.
From the browser, you can save the session variable as an HTTP cookie to hold data that can be retrieved between two runs of an application by the same user. For example, to store the users preferences.

Back to the top

Working with Session Variables and Cookies

The way to share session variables between two runs of an application is to persist the session variable means of HTTP cookies. Therefore, Genero must provide a way to set and get session variables to and from cookies.

Create, Set, and Get Session Variables and HTTP Cookies

A session variable or cookie can be created and updated in the following ways:

From the GAS, an administrator can create and set HTTP Cookies in the configuration file.
From the application, a 4GL developer can set or get session variables through front-end functions.
From the templates (snippet-based rendering engine), a designer can prepare form variables with a snippet-based rendering engine function or CSF function and can access session variables through template paths.
From the User Agent (browser), a request can set session variables through form variables. A session variable can be created using a Client Side Framework function.

Session Variable / HTTP Cookie synchronization

Every session variable may not need to be put into an HTTP cookie; conversely every HTTP cookie value need not be put into a session variable.

The idea is to tag each session variable that has to be set into a cookie. The snippet-based rendering engine (with the GAS) would be in charge of maintaining the cookies/session variables synchronization. On incoming HTTP requests, the engine would update corresponding session variables; on outgoing HTTP responses, the engine would set changed cookies. Between the request and the response, the 4GL developer can update session variables. Therefore, updating an HTTP cookie is indirectly done by updating its session variables.

Back to the top

Build HTTP Cookies in the Configuration File

The main goal of cookies is to keep a state, through session variables, between two runs of an application by the same user. The number of cookies associated with an application should be constant.

You declare cookies for an application within the configuration file.

Examples of cookie declarations

<!-- session cookie -->
<HTTP_COOKIE Id="cookie1">
  <VARIABLE Id="var1" />
  <VARIABLE Id="var2" />
  <VARIABLE Id="var3" />
  <VARIABLE Id="var4" />
</HTTP_COOKIE>

<!-- persistent cookie that applies only to this application -->
<HTTP_COOKIE Id="cookie2" Expires="date" Domain="domain">
  <VARIABLE Id="var5" />
  <VARIABLE Id="var6" />
</HTTP_COOKIE>

<!-- secure persistent cookie with default variable value and constant value -->
<HTTP_COOKIE Id="cookie3" Expires="date" Domain="domain" Secure="TRUE" HttpOnly="TRUE">
  <VARIABLE Id="var7" />
  <VARIABLE Id="var8">Initial value</VARIABLE>
  <CONSTANT Id="constant1">A value</CONSTANT>
</HTTP_COOKIE>

Note: All cookies and all associated session variables will be shared between all applications.

Back to the top

Setting session variables with front-end functions

A set of front-end functions allows you to dynamically set and get session variables from within your Genero application. These front-end functions are:

session.getvar( varname ): Return the value of session variable called varname. Return an empty string if varname doesn't exist.
session.setvar( varname , value ): Set value value to session variable called varname and return 1 if successful, 0 otherwise.

Note: Setting a variable to an empty string is equivalent to deleting the variable.

Back to the top

Setting session variables with a snippet-based rendering engine function

To create a session variable (when there is no existing function with the same name), a snippet-based rendering engine function is provided.

makeSessionVarIDID(varName, varValue)

In the template itself, you would add this function using a line such as the following:

<input type="hidden" gwc:attributes="name makeSessionVarIDID('var1','value1')" />

When you use this function, the GAS first builds a page with a session variable, however it is not created in the application context yet. When the form is submitted by the User Agent to the GAS, the engine creates the session variable.

Note: Setting a variable to an empty string is equivalent to deleting the variable.

Back to the top

Setting session variables with Client Side Framework API

To create a session variable, a CSF function is provided.

gwc.capi.SessionVar(varName, varValue)

In the template itself, you would add this function using a line such as the following:

<input type="button" onclick="gwc.capi.SessionVar('var1','value1')" />

When you use this function, the CSF submits the variable to the GAS. The session variable is immediately created in the application context.

Note: Setting a variable to an empty string is equivalent to deleting the variable.

Back to the top

Access session variables using template paths

Session variables are held by a collection. As a result, there is a collection path to iterate through the full collection of variables, as well as a selector path to access a session variable by name.

application/meta/variables
application/meta/variable[<name>]
application/meta/variable/XDID
application/meta/variable/name
application/meta/variable/value
application/meta/variable/readOnly

Back to the top

Topics

Session Variable / HTTP Cookie synchronization

Examples of cookie declarations