ExSite defines seven global variables that are available in all programming contexts. All seven are hashes, and so can contain many other values and data structures. The variables are %config, %share, %session, %store, %cookie, %msg, and %token.
%config contains the system's configuration settings. These settings can usually be treated as constants that do not change. Configurations are subdivided into categories and settings, separated by period characters, like this:
category.subcategory.setting = value
You can nest your categories to any depth, including no categories at all. These settings are read into %config and stored as
$config{category}{subcategory}{setting} = "value"
Arrays of values can be defined using
category.subcategory.list += value1
category.subcategory.list += value2
which is stored as
$config{category}{subcategory}{list} = [ "value1", "value2" ]
The main (top-level) configuration categories include:
| Category | Details |
|---|---|
| site | basic identification information about this installation |
| server | web server settings |
| auth | security and authentication settings |
| form | settings that affect web forms |
| report | settings that affect reports and displaying data |
| content | settings that affect the CMS and web content |
Additionally, every plug-in module can import its own configuration settings, which implicitly go into a category named for the plug-in. For example, Calendar configuration settings are imported into $config{Calendar}{...}.
%share is a general-purpose shared-memory area for the current request. It is useful for sharing data between widely separated modules and routines. The main difference with %config is that %config's values are treated as constants that are the same on every request, whereas %share is more volatile, and the values change on each request.
Among the items that you might find in %share are:
| Item | Description |
|---|---|
| DB | database handle for the current request |
| Page | the current page being built |
| Content | the current content being viewed |
| ML | a markup object for generating HTML |
| UI | a UI object for generating complex HTML structures |
| Cache | results of recent database queries |
| input | various inputs that have been read from the query string and POST data |
| diagnostics | a list of warnings and error messages that have been logged for the current request |
| identity | information about the current user |
Developers are free to make use of any of these items, or to add any other items that might need to be shared across the system for this request. The only caveat is to be careful about naming your shared items, so that they don't collide with other values.
%session stores semi-persistent data for a particular user. This is useful for remembering things about a particular visitor for a short time. Session data is typically retained for one hour of idle time, although the session is continually renewed if the user remains active on the site. After one hour of no activity, the session is discarded and the data is deleted. This makes %session useful for keeping track of transient information about the visit, rather than permanent information about the visitor.
The %session hash is often used to track shopping carts and e-commerce flows, but it can also be used in some types of authentication, and in registration workflows to keep track of what options have been selected.
To remember something about the current visitor, simply set a key=>value pair in the %session hash, like so:
$session{preferred_language} = "English"
On subsequent requests, the %session hash will automatically be populated with these settings, for as long as the visitor remains active on the site. No other visitors will see those settings, as they will have their own private sessions with other values.
%cookie stores all cookies that are associated with the current request. These will typically include session IDs (see %session, above) and/or login tokens.
To issue your own cookies, simply add a value to the %cookie hash, like so:
$cookie{MyCookieName} = "my cookie value"
This will automatically issue a Set-Cookie header that will pass the cookie to your browser to be included in subsequent requests back to your web site. Similarly, you can remove cookies by deleting the values or setting the key to undef.
Cookies typically persist for the duration of the browser session (ie. until you close the browser or turn off your computer), although they can optionally be configured to be more persistent.
%cookie and %session are similar in that they track information for the current visitor. %cookie data is stored on the browser, while %session data is stored on the server. Because of that difference, cookies are less secure and less reliable. If security is important, a good practice is to use a cookie to store a tamper-proof token that references data that is securely stored elsewhere, such as in the session.
%store is a general-purpose storehouse for persistent data. There are many instances where you may want to remember something for a while. Simply add your item to the store, like so:
$store{$unique_key} = $value
and the store will hold onto it for a while, allowing you to read it back at a later time in the reverse way:
$value = $store{$unique_key}
Items placed in the store have an expiry time, after which they are cleaned out and discarded. By default, stored items will expire after 1 hour, although you can set your own expiries, and also set items to never expire.
The store is global—all requests can read all items in the score, so it is important to select unique keys when storing things. A good practice is to prepend a namespace to your key to keep your items clearly separated from others. The global nature of the store makes it useful for caching things that may be useful for different users or sessions.
The store is the underlying mechanism used for persistently storing sessions, caches, and configuration settings, among others. The Persistent Data Store app allows you to inspect its contents for system administration and debugging purposes.
%msg is a translation tool for system messages. Any time that code needs to issue a human-readable message (for example "Please check your email for confirmation"), you can wrap that message in the %msg hash for automatic translation:
$output = $msg{"Please check your email for confirmation."}
The message will be passed unaltered if the visitor is viewing an English page, but if they have chosen to use to a different language, the message will be translated first. (That is, the system will check the local translation dictionary to see if it has a better version of the message to use. If not, they will receive the English message regardless.)
By wrapping up your translatable texts in this way, you can easily make your code portable to any language you care to support.
Tokens are a key=>value store with some extra features that sometimes come in handy:
More information is provided in the Token module documentation.