Overview

Import or include xml files in another skin xml.

Import or Include

Skin files have the ability to import or include files into the skin markup using the <import> or <include> tags.

Note: These tags can only be used in a skin xml which contains a window ID.  You cannot import or include files in a file that is already imported or included.

The concept is to move all of the common markup into files that are smaller and easier to manage, to minimize the amount of work required to create new skin files and to make it easier to maintain and modify existing skin files. Example:

<import>myfile.xml</import>

The <import> or <include> tag  should be added to the <controls> section of the xml. The elements defined in the imported file will overlay elements which are defined previously in the xml, so the location of the <import> tag is significant.

Two of the most commonly imported files are "common.window.xml", which defines elements common to most or all windows, and "common.time.xml", which defines the display of the date and time on each window.

Conditional include

As of v 1.3.0 beta, skins may import files conditionally using the <include> tag

Conditional <include> makes it easier for skinners to develop skins with the ability to customize the GUI presentation (layouts, optional elements, etc.). For example, conditional <include> can help by adding skinnable behavior that provides for end-user selection between window layout "A" vs. "B". Skin designers can build the skin xml for option A and for option B separately (in two different xml files) and then conditionally include one xml file over another, based on a skinnable end-user selection using Skin Settings.

Conditional <include> functionality adds the condition attribute to the <include> tag as follows:

<include condition="expression">file.xml</include>

where expression is any valid skin expression or skin setting that evaluates to a boolean. If the result is "true", the xml file is included. If the result is "false", the xml file is not included. If the expression cannot be properly evaluated (e.g. the result is not a boolean), the file is not included, and a debug statement is written to the log.

When you want to include one of two different files, you can code <include> twice: the first specifying the "true" condition, and the second specifying the "false" condition. Alternatively, you can use the otherwise attribute of the tag to specify the file to be included when the condition is "false":

<include condition="expression" otherwise="false_file.xml">true_file.xml</include>

Example:

<include condition="#skin.tvguide.rows.is_short">mytvguide.8rows.xml</include>
<include condition="#(not(#skin.tvguide.rows.is_short))">mytvguide.10rows.xml</include>

where #skin.tvguide.rows.is_short is controlled by a togglebutton, checkbutton, or menubutton on the relevant skin-settings panel within MP. Using the otherwise attribute, the example above could instead be coded as follows:

<include condition="#skin.tvguide.rows.is_short" 
         otherwise="mytvguide.10rows.xml">mytvguide.8rows.xml</include>

See also: Skin Expressions