Directory variables are located at the site level and directory level, and can be an important asset to a site developer or administrator. Directory variables allow administrators the flexibility to define different variables, which may be applied to either the page in an <!--%echo var="[VARIABLE]" -->statement or to the XSLs. 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.
Directory variables can also be used to define a new image or media directory that users are placed in by default when browsing for an image or media file. This overrides the site setting for the image and media directory values. Directory variables are defined in name/value pairs. The syntax for the variable name is as follows:
- Image Directory: ox_ftp_image_root
- Media Directory: ox_ftp_media_root
- To skip files to publish: publish
- User defined directory variables are created in key/value pairs with the user creating
the text for both
The value to define an image or media directory is the path to the folder in which they will be placed. For instance: /academics/images. The value to exclude files from being published is; for example,skip:[EXTENSIONS,COMPOUND EXTENSIONS], replacing EXTENSIONS and/or COMPOUND EXTENSIONS with any file extensions or specific files that should be excluded. Note that they are separated with a comma and should not include spaces.
These variables have context — applying a directory variable to the “/academics” folder sets the value for that directory and all of the directories subordinate to it. Therefore, “/academics/biology” has this value defined, but a sibling directory such as the “/athletics” directory does not. However, this value is not set permanently, the value can be overridden further down in the directory structure by reusing the same name.
Since they are snippets of text, these directory variables can hold anything that a standard variable defined in a TCF can. Directory variables simply allow them to be stored in a contextual manner, where the value may change based on the current location. Some possibilities include:
- Path to a CSS file which may change a color scheme or background image based on the section of the site.
- Contact information for the maintainer of that portion of the website.
Both contextual configuration information and pre-populated variables are accessible in TMPL files when creating a new file, though it's not as likely that contextual configuration information will be echoed into a file.
Directory variables are defined per-directory using the same interface as other directory properties, such as access permissions and RSS feed settings.
Directory Variables can be configured by clicking on the Access icon for a site or directory. The Directory Variables section includes the following functionality:
- Viewing the inherited properties for folder
- Viewing the properties for the folder
- Adding properties (click New Property)
- Deleting properties (click the red minus sign)
Creating Image or Media Directory Variables
Two pre-populated variables that can be used during the new page creation process (along with TCFs).
1. Click New Property and define one of the following for the Property Name:
- ox_ftp_image_root: Redefines the default image directory in the WYSIWYG Editor, the default value of which is found in the site setup.
- ox_ftp_media_root: Redefines the default media directory in the WYSIWYG Editor, the default value of which is found in the site setup.
2. Define the Property Value as the path from the site root to the target image directory. For example:
/admissions/images or /athletics/baseball/images
Additionally a relative path from current directory can be used: ./ or ./images for example. This places the user into the target directory relative to the current directory they are in. Please note that all directory variables are inherited as new sub-directories are created. These are in effect until new settings for those variables are created in the sub-folders.
When the ox_ftp_image_root or ox_ftp_media_root are set for a given directory, a user is placed into that set location when they use the Insert Image or Insert Media tools of the WYSIWYG editor.
The publish directory variable can be used to skip the publish of files with a specific extension or with a compound extension. The system-level directory variable allows for skipping certain file extensions or compound extension names (including the extension) on publish. For example, “publish” can be used to ensure that XSL files don’t get published except with the manual publish of the individual page. In this case, it skips files with the defined extension on publish. Syntax:Directory Variable Name: publish
Directory Variable Value: skip:[EXTENSIONS,COMPOUND EXTENSION]
1. Click New Property and for the Property Name add: publish
2. Define the Property Value with the extensions to be skipped on publish. The list should be comma delimted and not contain spaces. For example:
In this example, any files ending in the extension of .xsl, .xslt, or .xml are not published. The compound extension of skp.pcf functions so that any files ending in .skp.pcf are skipped upon publish. This allows for specific files to be skipped. In this case the specific file or files need to be renamed to include the compound extension.
Creating a User-Defined Directory Variable
1. From the Content > Pages view, click the Access icon for the directory. This shows the Assign Directory Access screen. For Directory Variables two sections are displayed: Non-editable inherited values, and an editable list of entries for the current directory.
2. Directory variables are entered in name/value pairs. Enter a variable name on the left (for example, what would be used in an echo var statement <!--%echo var="NAME" --> ), and a value on the right (what that <!-- --> tag would be replaced with upon creation). Please refrain from naming variables with names that begin with "ox_" as these are reserved for future development purposes. To override a variable with a new value, simply reuse the variable name in the editable portion of the screen. The new value will replace the old when the variable's contents are accessed.
- Define a Property Name for the variable. This can be anything, but it must be referenced exactly in either the XSL or a TMPL.
- Define the Property Value to replace the variable in the templates for the directory.
3. Click the New Property link to add another directory variable or Save.
After saving the access preferences, the directory variables are immediately accessible in the current directory and all directories below it, including contextual configuration information and pre-populated variables.
Overriding Directory Variables for a Subdirectory
For example, a directory variable of department is defined for the artdept directory as "artdept".
After the directory variable was defined, a subdirectory called ceramics was created. Since the department directory variable is inherited with the creation of the subdirectory, it may be the case that the directory variable for the ceramics folder needs to be defined. When overriding inherited variables at the directory level, keep in mind that the Property Name must match exactly.
Define a variable's default value using the access button for the top of the site (found under the Setup tab), 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 TMPL files.