Previous ION Script User's Guide: ION Script Tag Reference Next

ION_INCLUDE

The ION_INCLUDE tag inserts the contents of another ION Script, text, or HTML file into the current ION Script document. These file types are handled by ION Script as follows:

The file extension of the included file determines whether ION Script treats the file as text, ION Script, or HTML. The ION Extensions field on the Files tab of the configuration utility specifies extensions that are to be considered ION Script files, and the Text Extensions field specifies extensions that are to be considered text files.


Note
ION Script does not support HTTP proxies. Therefore, ION_INCLUDE can only be used to include files that are accessible without a proxy. If your system resides inside a firewall that uses a proxy for accessing Web sites outside the firewall, you cannot include a Web page that resides outside the firewall.

Syntax

<ION_INCLUDE
SRC="url"
[ASTEXT={"TRUE" | "FALSE"}]
[PRE={"TRUE" | "FALSE"}] />

Attributes

ASTEXT

If the file to be included contains HTML tags or text that contains characters used in HTML, and you want these characters displayed as text (such as a code listing) rather than being rendered as HTML, set this attribute to TRUE. By default, ION Script converts special characters such as < and >, to character entities so that they will not be interpreted as HTML by the browser. Setting this attribute to TRUE prevents ION Script from converting special characters to character entities. See Example 1 for an example of the effect of the ASTEXT attribute.

Note that ASTEXT has no effect on included ION Script files.

PRE

Determines how the included file is treated by the ION Script parser:

The default value is TRUE, but this default can be changed on the "Format" tab of the configuration utility (Windows) or the "Format" section of the .ionsrc file (UNIX). See Use <PRE> with Text Files. For an example illustrating the effect of the PRE attribute, see Example 1.

SRC

The URL of the file to include. See Specifying URLs. The type of file to be included is identified by its extension. This attribute can contain a variable. By default, the following file extensions are recognized by the ION Script parser:

Table 5-8: SCR Extensions 

Table 5-8: SCR Extensions 
File Type
Extension
Text
.txt
ION Script
.ion

The configuration utility or .ionsrc file can be used to define additional extensions for each file type. See Text Extensions.

HTML Mapping

The ION_INCLUDE tag is not converted to HTML, and therefore does not accept any other attributes.

Examples

For these examples, assume we have the same file saved with three different filenames: includefile.txt, includefile.html, and includefile.ion. The file contains the following text: 

<ION_SCRIPT>  
<ION_BODY>  
   <H1>This is an HTML heading</H1>  
   <ION_EVALUATE EXPR="5+5" DISPLAY="TRUE"/>  
</ION_BODY>  
</ION_SCRIPT>

Example 1

Include the file includefile.html as pure HTML: 

<ION_SCRIPT>  
<ION_BODY>  
   <ION_INCLUDE SRC="file://includefile.html" />  
</ION_BODY>  
</ION_SCRIPT>

This results in the following page:

 

Figure 5-5: Output of ION_INCLUDE's Example 1

Figure 5-5: Output of ION_INCLUDE's Example 1

Example 2

Include the HTML file as a text file, so that the HTML is not rendered as HTML by the browser, and ION Script tags are not evaluated by the ION Script parser.This can be accomplished by adding ASTEXT="TRUE" to the ION_INCLUDE tag: 

<ION_SCRIPT>  
<ION_BODY>  
  <ION_INCLUDE SRC="file://includefile.html" ASTEXT="TRUE"/>  
</ION_BODY>  
</ION_SCRIPT>

This results in the following page:

 

Figure 5-6: Output of ION_INCLUDE's Example 2

Figure 5-6: Output of ION_INCLUDE's Example 2

If we also use PRE="TRUE" in our ION_INCLUDE tag, we get the following page:

Figure 5-7: Output of ION_INCLUDE's Example 2 (PRE="TRUE")

Figure 5-7: Output of ION_INCLUDE's Example 2 (PRE="TRUE")

Example 3

Include the file includefile.txt. 

<ION_SCRIPT>  
<ION_BODY>  
   <ION_INCLUDE SRC="file://includefile.txt" />  
</ION_BODY>  
</ION_SCRIPT>

Assuming .txt is listed as one of the Text Extensions in the configuration utility or .ionsrc file, the file is automatically treated as a text file. If the configuration option Use <PRE> with Text Files is turned on, this results in the following page. Note that this is the same as including the HTML file with ASTEXT="TRUE" and PRE="TRUE":

Figure 5-8: Output of ION_INCLUDE's Example 3

Figure 5-8: Output of ION_INCLUDE's Example 3

Example 4

Include the file includefile.ion: 

<ION_SCRIPT>  
<ION_BODY>  
   <ION_INCLUDE SRC="ion://includefile.ion"/>  
</ION_BODY>  
</ION_SCRIPT>

Assuming .ion is listed as one of the Text Extensions on the "Files" tab of the ION Script Configuration utility (Windows) or in the "Files" section of the .ionsrc file (UNIX), the file is automatically treated as an ION Script page:

 

Figure 5-9: Results of ION_INCLUDE's Example 4

Figure 5-9: Results of ION_INCLUDE's Example 4

  IDL Online Help (March 06, 2007)