Directory Variables

Overview 

Directory variables allow administrators the flexibility to define different variables, which can be used to adjust functionality on a page, similar to how Page Parameters work, but across an entire directory or section of a site at once. As an example, if different areas of the school (academics, athletics, etc.) have different theme colors, but the rest of the templates are the same, the theme color can be defined as a directory variable and changed as needed for different sections of the site.

Directory variables can be adjusted at the site level and directory level through the respective Access Settings dialog boxes. In this dialog, the variables are defined in name-value pairs.

The Directory Variables section of the dialog allows users to:

  • View the directory variables that have been applied to the current folder recursively from a parent directory/site
  • Change the existing values of these applied directory variables
  • Add new directory variables to the folder using the Add button
  • Delete an existing directory variable with the X icon

Directory Variables in Access Settings Modal

Directory variables are always applied recursively, so editing a directory variable for the /academics directory, for example, will affect the value of that variable inside any subdirectories of /academics as well.

After declaring the variable and its value there, the value can be applied to a template file, for injection into pages upon their creation, or the value can be applied to XSL in order to affect more files at once.

Typically, directory variables are custom-made for each institution and their functionality may differ from implementation to implementation. The possibles are essentially endless, however, and more can be created at any time.

System Variables 

There are three directory variables included with every installation of OU Campus by default. They can be used to override the default image and video directories in the system and prevent certain file extensions from being published. These variables communicate directly with OU Campus' backend, and therefore only need to be adjusted in Access Settings, and do not require a TMPL/XSL component to be edited.

The three system variables will appear with the following names and accept the following values:

  • Name: Default Image Folder (formerly ox_ftp_image_root)
    • Value: root-relative or page-relative path to the desired image directory, no trailing slash (e.g. /campus-life/images or ./images)
  • Name: Default Media Folder (formerly ox_ftp_media_root)
    • Value: root-relative or page-relative path to the desired media directory, no trailing slash (e.g. /campus-life/videos or ./videos)
  • Name: Publish
    • Value: Add skip: and then make a comma-separated list of the file extensions that shouldn't be published (e.g. skip:xml,xsl,tcf,tmpl)

The Default Image/Media Folder directory variables will determine the default folders users will be dropped into when using the Insert/Edit Image and Insert/Edit Video tools in the WYSIWYG Toolbar, as well as the Images Gadget.

The Publish directory variable will prevent files ending in the defined extensions from being published as part of a multi-file publish (they can still be published individually). compound extensions, like skip.pcf, can also be used to prevent a specific subset of files with a certain extension from publishing. In this example, files ending in .skip.pcf (e.g. index.skip.pcf) will also not be published, even if the PCF file extension is normally allowed.

Creating New Directory Variables

Creating a new directory variable is a multi-step process, which is listed in detail below.To learn more, watch our Training Tuesday from August 2015, which also covers this process using a few examples.

The first step involves adjusting the Access Settings for the directory or site in question.

  1. Once there, click Add. This will give the user the option to either create an entirely new variable or select from a list of variables that have been inherited by this directory (including the three system variables).

    Directory Variables Dropdown
  2. If Create New Variable has been selected, users will need to add a Name and a Value for the variable.
  3. Save the access settings and exit the dialog.

Depending on how this directory variable will be used, and what kind of file is affected, there are two possible file types that can call the value of the directory variable.

Calling a Directory Variable with XSL

This method is used when the directory variable will be used in some way by the design of the page, such as adjusting a class applied to a <div> element, injecting information into the header or footer of a page, and many other situations.

  1. Travel to the ou-variables.xsl file located in the site. Typically, this file exists in /_resources/xsl/_shared, but the location may differ for each implementation.
  2. In this file, the directory variable needs to be declared using the format <xsl:param name="ou:[variable name]" />, where [variable name] corresponds with the Name field in the Access Settings dialog box from earlier.

    Directory Variables Declared in ou-variables.xsl
  3. Finally, travel to the XSL file in which the variable will be used.
  4. Bring in the value of the directory variable wherever it needs to go. The variable will be called with $ou:[variable name]. Examples could include <xsl:value-of select="$ou:[variable name]"/> or <img src="{$ou:[variable name]} />. Note the use of {} if the variable needs to be called inside an attribute.
  5. Travel back to a page in the desired directory and test the new variable's functionality. From here on out, the value of the variable can be changed at will from Access Settings.

Calling a Directory Variable with Template Files

Values of directory variables can be added into TCFs and TMPLs in order to have certain parts of a new page differ depending on where in the site the page is being created. Examples include having pages be "stamped" with keywords upon page creation, inserting assets into new pages, or using directory variables to determine page layout.

This method was originally used when OU Campus had not yet adopted the XML/XSL transformation process for webpages on staging, so adding directory variable values to an XSL stylesheet was not an option.

With PCFs and XSL stylesheets now the norm, this method can still be used for new pages, and it is still useful when the file being created does not undergo an XSL transformation. It is important to note that once the page has been created, the directory variable value will typically be hard-coded onto the page, and will not dynamically inherit new values for the variable if the value is changed in Access Settings or if the file is moved to a different directory.

  1. Travel to the TMPL into which the variable will be added.
  2. In the appropriate place in the file, add an echo statement with syntax <!--%echo var="[variable name]" --> to the file.

    Directory Variable Value Called in a TMPL
  3. Save the TMPL.

Since directory variables are plain-text values, these directory variables can hold anything that a standard variable defined in a TCF can. Notice also that the echo statements for directory variables are formatted in the same way as an echo statement the calls a variable defined in a TCF.

Alternatively, directory variables can be called into a TCF:

  1. Travel to the TCF into which the variable will be added.
  2. In the appropriate place in the file (most likely inside the <template> node), call the directory variable with {[variable name]}.

    Directory Variable Value Called in a TCF
  3. Save the TCF.

Notice that the syntax for calling directory variables in a TCF is the same as the syntax for calling the value of a <variable> node within a TCF.

Best Practices

Define a variable's default value at the site level first (through Setup > Sites > Site Access), and redefine it to have intended values further down in the directory structure. This eliminates the possibility of having an empty string ('') used during the variable substitution in TCF/TMPL files and ensures no directories are skipped over.