Document number	Revision
DOCU13072	3

<include> Element - Schema Reference

<include> Element - Schema ReferenceDefinitionContent modelAttributesElementsSpecial elementsSamplesIncluding the Favorites pluginIncluding a custom .XML file from the Tweak folderIncluding custom .XML files using relative or absolute pathInclude a custom .XML file from the Tweak removing specific elements using the _remove attributeCreate custom attributes using merge variablesRelevant tools and utilitiesIncluded system filesMerge variables

Definition

Parent element(s): <schema>.

The <include> element can be used to include and merge additional .XML (Extensible Markup Language) files to be loaded and executed by Highstage.

Tip: The .XML files are used to directly configure the behavior and functionality of Highstage. You can advantageously split configurations into separate XML files to easily keep track of all configurations of the system in their own dedicated folders and files.

Content model

The specification of what elements, attributes and data that are available and allowed within the <include> element.

Attributes

This section introduces you to the XML attributes and values that are available and can be included within the <include> element.

Attribute	Description	Mandatory
name	Unique element name.	❌
src	Source path specifying the directory where the `.XML` source file is located.	✔️
<parameters>	Custom defined attribute(s) using merge variables.	❌
_remove	List of xpath expressions selecting specific schema elements that will not be included (use semicolon (;) to separate individual elements to prevent from being included).	❌

Elements

There are no available elements to be placed within the include element.

Special elements

There are no available special elements to be placed within the include element.

Samples

Including the Favorites plugin

The following sample illustrates how you can make use the the <include> element to enable the Favorites plugin in Highstage allowing users to 'favorite' individual search pages and items for easy future access from a dedicated page:


<include src="/ts/feature/favorites/favorites.schema.xml"/>

Note: Please refer to our documentation to read more about Favorites.

Including a custom `.XML` file from the Tweak folder

The following sample illustrates how you can include a custom .XML file located in the tweak > feature destination:


xxxxxxxxxx
<include src="/tweak/feature/sample.schema.xml"/>

Sample: You can download a sample of a standard .XML file directly from here.

Including custom `.XML` files using relative or absolute path

The following samples illustrates how you can include additional .XML schema files using absolute and relative path definitions.

Details: An absolute path refers to the same location in a file system relative to the root directory, whereas a relative path points to a specific location in a file system relative to the current directory you are working on.

Path relative to the folder containing the current schema file:


xxxxxxxxxx
<include src="sample.schema.xml" />

Absolute path:


xxxxxxxxxx
<include src="c:\...\sample.schema.xml" />
<include src="\\server\share\...\sample.schema.xml" />

Path relative to web application root folder:


xxxxxxxxxx
<include src="/tweak/sample.schema.xml" />
<include src="\tweak\sample.schema.xml" />

Include a custom `.XML` file from the Tweak removing specific elements using the _remove attribute

The following sample illustrates how you can include a custom .XML file and exclude specific elements and their contents from being included into the resolved schema.

In this example, we are excluding all occurrences of <form>, `<menu, and <main> elements, so that they are not included and resolved (regardless of existing in the included schema):


xxxxxxxxxx
<include src"/tweak/feature/sample.schema.xml" _remove="//main;//menu;//form" />

Create custom attributes using merge variables

You can establish new attributes on any <include> element by taking advantage of merge variables.

In this sample, we illustrate how a custom .XML file includes merge variables (@@[variable-name]) so that they can be declared and used directly in the <include> element as new available attributes.

In this example, we are establishing a structured way of creating new columns (with adjustable list entries) that will be displayed on items of the associated type:


x
<?xml version="1.0" encoding="utf-8"?>
<schema schemasyntaxversion="0.8">
    
    
    <type name="@@[type]">
        <column name="@@[column]" title="@@[title]" sqltype="varchar" sqlsize="512" sqlnull="0" sqldefault="('')" values="@@[values]"/>
        <form name="default">
            <subform name="@@[title]" title="@@[title]">
                <field name="@@[column]" />
            </subform>
        </form>
    </type>
    
    
</schema>

The following sample is defined in custom.schema.xml and illustrates how <include> elements makes use of the defined merge variables from the included schema file as available attributes.


xxxxxxxxxx
    <include src="/tweak/ranking.xml" type="doc" column="severity" title="Severity" values="Low;Medium;High" />
    <include src="/tweak/ranking.xml" type="doc" column="criticality" title="Criticality" values="None;Low;Moderate;High;Extreme" />

Resulting view in Highstage:

Relevant tools and utilities

Included system files

As an administrator (with a set userlevel of AdminRead/AdminWrite), you can access SYSTEM > SCHEMA > FILES to get a full overview of all .XML schema files that are included and loaded by Highstage. This includes standard system schema files as well as custom schema files.

Tip: Click on the FileUrl link associated with each included .XML file to see the XML schema file contents directly in your browser.

Merge variables

Merge variables (@@[<variable-name]) may be declared in schema .XML files that are included by other schema files. When resolved, all merge variables will be replated with attributes (with identical names) from the <include> element that includes those schemas.

In other words, it enables you to create new attributes in the <include> element and have them inserted and resolved in the included schema where similarly named merge variables are declared. This makes included schema files dynamic and resuable.

When the designated schema file is included using the <include> element, all merge variables will be replaced with corresponding attribute values as defined in the <include> element.

Important: Merge variables that do not have a corresponding <include> element attribute with identical name will result in schema load exception.

highstage_footer