Site Variables

Last Updated: Apr 9, 2021
documentation for the dotCMS Content Management System

When managing multiple websites it is sometimes necessary to record information specific to each site. Although values that are common to all sites can be added to the Host Content Type as additional fields, there are times when data is unique only to a few sites or different on every site. In these cases unique values that refer to specific sites are better stored in specific Site Variables.

Adding a Site Variable

To add a Site Variable to a site:

  1. Select the Control Panel -> Sites Tool from the navigation sidebar.
  2. Right-click on the Site you wish to add a varable to, and select Edit Site variables.
  3. In the Site Variables pop, click the Add New Site Variable button.
  4. Fill in values for each of the properties and then press the Save button.
  5. Flush the server cache.
    • Since Site Variables are intentionally not saved with the Site itself, it may be necessary to flush the server cache before you can access the new Site Variable from your Velocity code.


You must fill in all three properties in the Adding or Editing a Variable popup. The Name and Key fields restrict which characters may be used:

PropertyAcceptable CharactersDescription
NameAny displayable characters, including spaces.A label.
Not used or accessible via code.
KeyAlphanumeric and underscores only.The key used to access the variable from code.
ValueAny.The value of the variable.

The Adding or Editing a Variable popup

Referencing Site Variables using the Scripting API

To reference Site Variables using the Scripting API view the Site Variables section in the Scripting API.

Accessing Site Variables from Velocity Code

The value of a Site Variable can retrieved throught the built-in $host_variable Velocity object. Individual Site Variables are accessible as properties of the $host_variable object:


You must replace {key} in this notation with the Key value you assigned to the appropriate Site Variable. For example, if you have created a Site Variable with a key of local_site_id, you would access it as $host_variable.local_site_id.

Checking for Unset Variables

The $host_variable object will only be created if you have defined Site Variables on your site. Therefore, you should ensure that your code either uses appropriate Velocity notation to handle empty values (e.g. $!{host_variable.local_site_id}), or checks for the existence of the variable before using it, as in the following code:

#if( $UtilMethods.isSet( $host_variable.local_site_id )
    #set( $localId = $host_variable.local_site_id )
    #set( $localId = "defaultId" )

On this page


We Dig Feedback

Selected excerpt: