SPFE Documentation | Collections > SPFE Development > Structures

Structures

• Using a structure in a schema
• Adding a structure to processing scripts
• Using a structures file
• Rewriting namespaces
• Using CSS files from a structure

Structures are a topic type definition feature of the SPFE open toolkit. You can rapidly define a new topic type by plugging together existing structures or you can create your own structures to define multiple topic types. Structures package together schema components, processing script components, and style components required to support the authoring, publishing, and processing of common topic structures such as lists, tables, admonitions, and annotations.

An XML document consists entirely of nested element structures. In this sense, every element is a separate structure. However, in practice there are a number of higher level structures that recur at many places in a document type and across many document types. XML schema languges recognize this fact by providing features such as complex types and schema groups that encapsulate complex structures for reuse within and between schemas. Examples of such reusable structure include lists and tables. SPFE Structures take this concept one step further by packaging style and processing information with schema structures to allow you to plug and play structures into your topic type definitions.

Structures make it easy to create minimal topic types that contain the minimal markup required for a specific topic type for your business. Creating minimal topic types makes it easier to author content that meets your requirements and easier to define reliable processing for publishing your content in as many forms as required. It allows you to create topic models that express the specifics of the topic patterns that matter to your business. This supports greater automation and validation of content, which leads to greater consistency and quality, as well as supporting higher degrees of automation.

Using a structure in your topic type requires a slightly different procedure for schemas, scripts, and styles. (Eventually these differences will be eliminated by automation.)

 

Using a structure in a schema

A structure can provide schemas for authoring, presentation, formatting, or encoding.

To use a structure in a schema, you simply import the appropriate schema file from the structure directory.

<xs:include schemaLocation="http://spfeopentoolkit.org/spfe-ot/plugins/eppo-simple/structures/annotations/xslt/schemas/authoring/annotations-xslt.xsd"/>

However, to integrate the element structures defined by the structure schema into the your topic type schema, you need to use either the group or type defined in the structure schema in your topic type schema.

Each properly defined structure schema should define a schema group and a type (simple or complex) that contain the XML elements that make up the structure. The following example show the definition of the eppo-simple fig structure, which defines a complex type named fig and a group named fig, which is defined using the fig type:

    <xs:group name="fig">
        <xs:choice>
            <xs:element name="fig" type="fig"/>
        </xs:choice>
    </xs:group>


    <xs:complexType name="fig">
        <xs:sequence>
            <xs:element name="title" type="xs:string"/>
            <xs:element name="caption" minOccurs="0">
                <xs:complexType>
                    <xs:sequence>
                        <xs:group ref="paragraph" minOccurs="0" maxOccurs="unbounded"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
            <xs:group ref="fig-content"/>
        </xs:sequence>
        <xs:attributeGroup ref="conditions"/>
        <xs:attribute name="id" type="xs:NMTOKEN"/>
    </xs:complexType>

Note that the group defines an element named fig of type fig. This means that you can incorporate this structure in your schema either by including the group in the content model of an element or by defining a new element and giving it the type fig. The second approach would allow you to give the structure element any name you liked. Unless you have a good reason to change the name, however, it is better to use the group. In the following example, the group fig is included in the group text-general, which is a standard group in EPPO-simple that is used to define all the elements that can occur at the general text level of a topic types schema (that is, ordinary textual content inside a topic or section, but not in a list or a table or some other substructure that might have a more restrictive model. This illustrates how groups are used to build a schema by nesting structures (defined by groups) one inside the other.

    <xs:group name="text-general">
        <xs:sequence>
            <xs:choice maxOccurs="1" minOccurs="1">
                <xs:group ref="paragraph"/>
                <xs:group ref="fragments"/>
                <xs:group ref="fragment-ref"/>
            </xs:choice>
            <xs:choice maxOccurs="unbounded" minOccurs="0">
                <xs:group ref="paragraph"/>
                <xs:group ref="subhead"/>
                <xs:group ref="lists.ol-ul-ll"/>
                <xs:group ref="codeblock"/>
                <xs:group ref="fig"/>
                <xs:group ref="fragments"/>
                <xs:group ref="fragment-ref"/>
                <xs:group ref="table"/>
                <xs:group ref="object-ref"/>
                <xs:group ref="admonitions"/>
                <xs:group ref="comments-block"/>
                <xs:group ref="labeled-item"/>
                <xs:group ref="procedure"/>
                <xs:group ref="instructions"/>
            </xs:choice>
        </xs:sequence>
    </xs:group>

 

Adding a structure to processing scripts

The SPFE build process automatically constructs processing scripts for each step of the build. These scripts are assembled by including script fragments identified by the configuration files for topic types, object types, and structures. Structures are used to build topic types, so each topic type configuration should include the structure configuration for each type it uses. The following example define a topic type which included several structures. The scripts defined in the structure configuration files will be added to those defined for the topic type itself to create a complete processing script for the topic type.

    <topic-type>
        <name>{http://spfeopentoolkit.org/ns/spfe-docs}spfe-configuration-reference-entry</name>
        <aliases>
            <singular>Configuration setting</singular>
            <plural>Configuration settings</plural>
        </aliases>
        <structures>
            <structure>
                <name>eppo-core</name>
                <href>${SPFEOT_HOME}/plugins/eppo-simple/structures/eppo-core/config.xml</href>
                <rewrite-namespace>
                    <from>http://spfeopentoolkit.org/ns/eppo-simple</from>
                    <to>http://spfeopentoolkit.org/ns/spfe-docs</to>
                </rewrite-namespace>  
            </structure>
            <structure>
                <name>spfe-docs-core</name>
                <href>../../structures/spfe-docs-core/config.xml</href>
            </structure>
            <structure>
                <name>topic</name>
                <href>${SPFEOT_HOME}/plugins/eppo-simple/structures/topic/config-with-resolve-main.xml</href>
            </structure>
            <structure>
                <name>topic-set</name>
                <href>${SPFEOT_HOME}/plugins/eppo-simple/structures/topic-set/config-with-topic-set-toc.xml</href>
                <rewrite-namespace>
                    <from>http://spfeopentoolkit.org/ns/eppo-simple</from>
                    <to>http://spfeopentoolkit.org/ns/spfe-docs</to>
                </rewrite-namespace>  
            </structure>
        <structure>
                <name>graphic-record</name>
                <href>${SPFEOT_HOME}/plugins/eppo-simple/structures/graphic-record/config.xml</href>
            </structure>
        </structures>
        
        <scripts>
            <extract>
                <script>
                    <href>scripts/extract/schema-defs.xsl</href>
                </script>
                <script>
                    <href>${SPFEOT_HOME}/1.0/scripts/common/utility-functions.xsl</href>
                </script>
            </extract>
            <merge>
                <script><href>scripts/merge/merge-config-ref.xsl</href></script>
                <script><href>${SPFEOT_HOME}/1.0/scripts/common/utility-functions.xsl</href></script>
            </merge>
            <resolve>
                <script>
                    <href>scripts/resolve/resolve-config-ref.xsl</href>
                </script>
                <script>
                    <href>${SPFEOT_HOME}/1.0/scripts/common/utility-functions.xsl</href>
                </script>               
            </resolve>
            <present type="eppo">
                <script>
                    <href>scripts/present/eppo/present-config-ref.xsl</href>
                </script>
            </present>
            <toc>
                <script>
                    <href>../../topic-types/config-reference/scripts/toc/schema-toc.xsl</href>
                </script>
            </toc>
        </scripts>
    </topic-type>

 

Using a structures file

In many cases, you will want to define a common set of structures to be used across many different topic types. Rather than include those structures separately in each topic type configuration, you can define a structures configuration file, which is simply a list of structures. In the example above, the structures eppo-core and spfe-docs-core point to structures files rather than to individual structures.

 

Rewriting namespaces

SPFE makes use of namespaces when defining schemas. When you use a structure to define a topic type, you need to make sure that the structure comes in using the correct namespace. You can use a structure to bring in elements in the same namespace as your main schema or as a different namespace (see the graphic-record structure for an example of this). In most cases you will want the structures to become part of the current namespace.

This is not a problem for schemas, since you can use the chameleon schema pattern to define structures. This is what the EPPO-simple structure set does with most structures. Structures are defined without a namespace and take on the namespace of whatever schema they are included into. (The graphic-record structure is an exception to this. It is defined in its own namespace.)

XSLT scripts, however, do not support the chameleon pattern. Every xpath expression in a script is matched in a specific namespace. All scrips in the EPPO-simple structure sets that are paired with schemas that are in no namespace are match element names in the EPPO-simple namespace (http://spfeopentoolkit.org/ns/eppo-simple). If your schemas are in a different namespace, you need to tell the configuration system to rewrite the namespaces in those scripts to the namespace of your schemas. The SPFE docs are in the SPFE-docs namespace (http://spfeopentoolkit.org/ns/spfe-docs), so when the SPFE docs use an EPPO simple structure, they need to rewrite the namespace when they include the structure:

            <structure>
                <name>topic-set</name>
                <href>${SPFEOT_HOME}/plugins/eppo-simple/structures/topic-set/config-with-topic-set-toc.xml</href>
                <rewrite-namespace>
                    <from>http://spfeopentoolkit.org/ns/eppo-simple</from>
                    <to>http://spfeopentoolkit.org/ns/spfe-docs</to>
                </rewrite-namespace>  
            </structure>

 

Using CSS files from a structure

A structure can provide CSS files for both authoring and formatting output.

To use a CSS file from a structure, simply include it in your main CSS file:

@import url("http://spfeopentoolkit.org/spfe-docs/structures/annotations/spfe-build/style/authoring/annotations-spfe-build.css");

Selectors in a structure CSS file should be written to be as specific as possible to avoid conflicts with other CSS files.