Overview

Fragments are small portions of documents that are stored in XML files separate from your primary documents so that they can be reused. For example, if you are creating several pieces of curriculum for a course fragments give you the ability to share scripts, footers, or even equations between documents.

The main structure of a fragment includes two primary elements. The first portion of a fragment is the documentation itself, which lives in an XML file that's separate from your primary document. The actual XML code that defines the fragment must be included inside a fragment element instead of a document element. Fragments can include all content types that could be placed into a standard <section> or <sectionNoTitle>. For example, the following fragment includes a paragraph.

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns="http://resources.qdexapps.com/schema/v1/QDocument.xsd">
    <p>This paragraph lives in a fragment.</p>
</fragment>

To include this fragment in a document, all you have to do is add an include element into your document where appropriate, and specify the name of the fragment. For example, if the fragment is in an XML file called "fragment.xml" then you would include it in your main document, using the following element:

<include src="fragment.xml"/>

Documentation

The primary example of content that can be stored in a fragment for use between documents is standard textual documentation. In the following example, the content of the second paragraph of the first section is contained in a separate fragment:

document.xml

<!-- Section 1 -->
<section name="section1">
    <title>Fragments</title>
    
    <p>This text is included in my core document.</p>
    <include src="fragment1.xml"/>
</section>

fragment1.xml

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns="http://resources.qdexapps.com/schema/v1/QDocument.xsd">

    <p>This is in my first fragment</p>

</fragment>

which results in the following app after parsing.

included-fragment.jpg
 

Header and Footer Fragments

Another common use case for fragments is for common headers/footers. For more information on headers/footers please refer to the Structure Guide. For example, the following code creates a footer, and includes it in this document:

document.xml

<?xml version="1.0" encoding="utf-8" ?>
<document xmlns="http://resources.qdexapps.com/schema/v1/QDocument.xsd" name="myDocument">

<!-- Meta Data -->
<metadata>
  <title>Fragments</title>
  <creator>Peter Martin</creator>
  <abstract>An example document that illustrates how to include fragments in a document.</abstract>
</metadata>

<footer>
  <include src="fragment2.xml"/>
</footer>

fragment2.xml

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns="http://resources.qdexapps.com/schema/v1/QDocument.xsd">
    <p>
      <style>
        <foreground color="red"/>
        <horizontalAlignment>center</horizontalAlignment>
        <textAlignment>center</textAlignment>
      </style>
        This is my footer. It lives in a fragment
    </p>
</fragment>

Which looks like the following when the document is rendered

 
header-footer-fragment.jpg
 

Script Fragments

One other useful application for fragments is a common repository for Lua scripts. In the following example, I have created a fragment that contains a function that can be used to draw an arbitrary square on a plot. With the fragment included at the base level of the document, any of the scripts in the document gain the ability to call the drawSquare function and pass it a data series and the square properties. In this example, the button creates a square using the fragment:

document.xml

<!-- Section 1 -->
<section name="section1">

    <xyPlot name="myPlot" xmax="10" xmin="0" ymax="10" ymin="0" xauto="fixed"  yauto="fixed">
        <series name="Series" manual="true"></series>
    </xyPlot>

    <button name="myButton" content="Draw Square">
        <onClick>
            drawSquare(myPlot.Series, 8, 8, 5, 5);
        </onClick>
    </button>
</section>

fragment3.xml

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns="http://resources.qdexapps.com/schema/v1/QDocument.xsd">

  <script>
    function drawSquare(series, width, height, x, y)
    series:Add(x - width/2, y + height/2);
    series:Add(x + width/2, y + height/2);
    series:Add(x + width/2, y - height/2);
    series:Add(x - width/2, y - height/2);
    series:Add(x - width/2, y + height/2);
    series:Update();
    end
  </script>
</fragment>

which generates the following plot when the button is pressed.

 
script=fragment.jpg