Riverwatcher Active Content Environment

RACE Documentation:

INCLUDE - Including files, or the results of a command line call, within RACE scripts

  • FILE - The path and name of a file to include.
  • CMD - The path and name of a shell command to execute.
  • DIR - The path and name of a directory to include
  • LOCATION - The url to the resource over the network to include
  • SEPARATOR - Delimiter to use when using the DIR functionality.
  • QUOTE - Quote character to use when using the DIR functionality.
  • ASIS - When present, and RACE code returned by the tag will not be executed.
  • OUTPUT - When present with the CMD functionality, the content of the tag will be passed to the command as its standard input.
The include tag retrieves data from an outside source and inserts it into the currently executing script. There are 3 resource types available through this tag: files, directories, and shell commands. These are defined by using one of the three attributes file, dir, or cmd (respectively).

If the FILE attribute is set, the contents of the specified file will be included into the active RACE stream. If the asis attribute is set, the included data will not be parsed as RACE code. If the specified file is not found or the RACE / Apache user doesn't have permissions to view it, $system.error will contain an appropriate error.

If the DIR attribute is set, the tag will return a delimited list of files in the specified directory. The separator and quote attributes determine the list format, and results can be easily placed in an array for further processing.

If the CMD attribute is set, include will execute the specified shell command from the directory containing the currently executing RACE script. If the optional OUTPUT attribute is set, the include tag becomes a balanced tag, and it's body will be passed to the command as standard input.

In order to use the DIR attribute, it must be enabled in the web server's configuration file. For Apache, you need to have the following line in the httpd.conf file:

RACEAllowFileActions List

Setting the RACEAllowFileActions value to "All" will enable the DIR attribute as well. For more information on configuration directives, please refer to the Apache run-time configuration directive section.

Example - Using "header" and "footer" templates

<include file="header.race">
<!-- page content -->
<include file="footer.race">

This allows the developer to place the majority of a website's layout in header and footer files, to simplify development and additions to the site. This can be extended easily to a full site templating system with little effort.

Example - Creating a simple file browser

<define var="$directory">/my_files/</define>
<define var="@myfiles"><include dir="<$directory>"></define>
<for key="file" list="(<@myfiles>)">
  <if test="<$file> != '.' && <$file> != '..'">
    <li><a href="<$file>"><$file></a> (<file action="get" name="<$file>" property="size"> bytes)</li>

  <li><a href="photo.jpg">photo.jpg</a> (12083 bytes)</li>
  <li><a href="photo02.jpg">photo02.jpg</a> (14402 bytes)</li>
  <li><a href="readme.txt">readme.txt</a> (7550 bytes)</li>

note: This reads in the files of a directory and outputs them in a formatted, hyperlinked list.

Example - Running shell commands

<include cmd="wc" output>one two three four</include><br />
<define var="$file">readme.txt</define>
<define var="$perms">755</define>
<include cmd="chmod <$perms> <$file>">

0 4 18

note: This just executes a couple example commands. First, a call to "wc" (wordcount) using the output attribute and balanced form. Then, running "chmod" over a file with a defined set of permissions. Note that RACE will need to have execute permissions to run these commands. Check to find any problems that arise.

RACE Documentation

Copyright 2009 Riverwatcher, Inc. Hosting by Riverwatcher Studios