#INCLUDE

Synopsis

<!--#INCLUDE FILE="filename"-->

Description

The #INCLUDE directive allows you include text within a CSP page from an external text document.

For an example using #include, refer to the http://localhost/csp/samples/textinclude.cspOpens in a new tab sample page.

Server-side include directives give you a way to insert the content of another file into a file before the CSP server processes it. To insert a file into an .csp file, use the following syntax:

<!-- #include VIRTUAL | FILE="filename" -->

The virtual and file keywords indicate the type of path you are using to include the file, and filename is the path and file name of the file you want to include. Included files do not require a special file name extension; however, it is considered good programming practice to give included files an .inc extension to distinguish them from other types of files.

Use the virtual keyword to indicate a path beginning with a virtual directory. For example, if a file named Footer.inc resides in a virtual directory named /Myapp, the following line would insert the contents of Footer.inc into the file containing the line:

<!-- #include virtual ="/myapp/footer.inc" -->

Use the file keyword to indicate a relative path. A relative path begins with the directory that contains the including file. For example, if you have a file in the directory Myapp, and the file Header1.inc is in Myapp\Headers, the following line would insert the contents of Header1.inc into your file:

<!-- #include file ="headers\header1.inc" -->

Note that the path to the included file, Headers\header1.inc, is relative to the including file; if the script containing this #include statement is not in the directory /Myapp, the statement would not work. CSP detects changes to an included file and will force recompilation of the page which includes that file. Changing the application configuration may change the location of the a file representing a CSP page or included in a CSP page. Therefore, all pages will be recompiled after a CSP configuration change.

Including Files: Tips and Cautions

An included file can, in turn, include other files. A .csp file can also include the same file more than once, provided that the #include directives do not cause a loop. For example, if the file First.csp includes the file Second.inc, Second.inc must not in turn include First.csp. Nor can a file include itself. CSP includes files before executing script commands. Therefore, you cannot use a script command to build the name of an included file. For example, the following script would not open the file Header1.inc because CSP attempts to execute the #include directive before it assigns a file name to the variable name.

<!-- This script will fail -->
 <script language="cache" runat="server">
  set name=header1_".inc"
 </script>
<!-- #include file="#(name)#" -->

Scripts commands and procedures must be entirely contained within the script delimiters <SCRIPT> and </SCRIPT>. That is, you cannot include a file within script delimiters and you cannot open a script delimiter in an including .csp file, then close the delimiter in an included file; the script must be a complete unit. The include directive may also be used within rule files just as they are within .csp files. The same restrictions concerning use of #include within script delimiters applies to rules files.