include Tag

Format: <include name="Filename" [/] >

Format: <include Filename>

Format: <include> heitml </include>

Purpose: The first and second format includes the content of the given filename. The include is performed statically, when reading the .hei file. The file may contain defines needed for the current page. The include tag may not be combined with other tags in a pair of <> brackets, e.g. combining

<include std.hei><include basic.hei>

to

<include std.hei;include basic.hei>

is not allowed.

The third format includes a file of which the filename can be calculated dynamically. The file is read in only at execution time. Anything you type between the opening and closing include tags is processed in HTML mode where the resulting string output is not sent to the browser, as usual, but used as the name of the file to be included. Dynamic include files underlie certain specific rules and restrictions as documented below. Note that in the current implementation dynamic include files must be preprocessed before being used.

Configuration: If the configuration option secure is switched on, there are some restrictions on the file name:

1. If configuration option includeall is switched off, the file name
1. must not contain "..", and
2. must not denote a symbolic link.
2. The file name must not be an absolute path.
3. The file name must have one of the following extensions: .hei, .heitml, .htm, .html, .asp, .htx or .xml.

The include tag uses the configuration parameter include which specifies an include path that is searched from left to right for a directory containing the filename given.

Special Restrictions for Dynamic Include Files

Dynamic include files are included during execution of the include tag. Since execution starts only after a complete page is read, a dynamic include file is interpreted as being attached at the very end of the current page (possibly following any previously included dynamic include files). This means

• a dynamic include file sees the definitions as they are at the end of the current page,
• definitions in the dynamic include file are not visible in the page itself, because definitions in heitml are visible only after the definition. It is however allowed to override a previous tag definition (unless it is defined as a class). So the normal way of calling a definition in a dynamic include file is to include an empty definition of a tag in the main page and then override the definition in the dynamic include file.
• stdinit routines inside dynamic include files are never executed. stdinit is executed during initialization, but dynamic include files are not present at this time.

Dynamic include files need explicit preprocessing. For preprocessing the page (called base page) a dynamic include file is going to be included into must be specified. Inside the dynamic include file only definitions from this page are visible.

It is allowed to use a dynamic include file within several pages provided they contain identical definitions as the base page. A dynamic include file sees the definitions contained in the base page.