Quark XML Author 10.0 — System Admin Guide

Quark XML Author Structure Overview

The Quark XML Author Structure (XAS) is the Quark XML Author equivalent of an XML schema file, in that it defines the allowed components of a document, and their relationships to each other. Quark XML Author uses the XAS to provide more flexibility than would be present with a standard XML Schema Definition (XSD) or Document Type Definition (DTD). This chapter presents an overview of the XAS structure. Subsequent chapters will discuss how each component in an XAS is constructed.

XML Declaration and Processing Instructions

Because the XAS is an XML document, it must begin with an XML declaration, as shown below:

<?xml version="1.0" encoding="utf-8"?>

Defining Multiple Namespaces

The root element defines the default namespace so that you don't need to specify it for each element you define. However, each attribute, emphasis, and element definition can specify additional namespaces that will override the default namespace within the documents that are based on the XAS.

Root Element

The root element for the XAS is XpressSchema. Its required attributes are defined in below table. 

<b>Table: Schema Root Element Attributes and Values</b>

Attribute

Value

xmlns:xsi

http://www.w3.org/2001/XMLSchema-instance

xsi:schemaLocation

urn:xpressauthor:XpressSchema ../Schemas/XpressSchema.xsd

External Entities

The DTD ENTITY declaration and entity references can be used to link separate documents into a single Quark XML Author Schema. The schema validation is still supported but first all the different entities are combined into one file before validating it. An example is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE link [
  <!ENTITY secattributes SYSTEM "SecurityAttributes.xas">
  <!ENTITY emphattributes SYSTEM "EmphasisAttributes.xas">
  <!ENTITY mediaattributes SYSTEM "MediaAttributes.xas">
  <!ENTITY emailattributes SYSTEM "EmailNotificationAttributes.xas">
  <!ENTITY miscattributes SYSTEM "MiscellaneousAttributes.xas">
  <!ENTITY tableattributes SYSTEM "tableAttributes.xas">
  <!ENTITY topLevelElements SYSTEM "topLevelElements.xas">
  <!ENTITY localMediaElements SYSTEM "LocalMediaElements.xas">
  <!ENTITY slideElements SYSTEM "PowerPointSlideElements.xas">
]>
<XpressSchema xmlns="urn:xpressauthor:xpressschema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" defaultNamespace="urn:us:gov:ic:msp" xsi:schemaLocation="urn:xpressauthor:xpressschema ../schemas/XpressSchema.xsd">
  &secattributes;
  &emphattributes;
  &mediaattributes;
  &emailattributes;
  &miscattributes;
  &tableattributes;
  <Emphasis>
    ......
  </Emphasis>
  <Elements>
    ....
  </Elements>
  &localMediaElements;
  &slideElements;
  <Elements>
    ....
  </Elements>
  &topLevelElements;
</XpressSchema>

Definition Order

Document components are declared in reverse hierarchical order. That is, the document's root node is the last item declared in the document. The root element's immediate children are declared just above it, and their children just above them, and so on, with elements that can contain no other elements declared before any others. Emphasis styles are referenced by elements, so they are defined above the element definitions. Both emphasis definitions and element definitions reference attributes, so attributes comprise the first section of the XAS.

Attributes

Of course, an XML document is composed of more than just elements, and a Quark XML Author document is no different. Elements have attributes which contain metadata describing the document and its contents. In the XAS, attributes are declared separately from elements, and are then referenced in each element definition.

Like child elements, attributes must be declared before the element to which they will be applied. For this reason, Attribute are defined at the beginning of the XAS

Emphasis Styles

The next section of the XAS defines Emphasis styles. Each emphasis style can also reference attributes, but they, in turn, will be referenced by elements. This section is therefore located below the Attributes section, but above the Elements sections.

The structure of the file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
  <XpressSchema xmlns="urn:invision:XpressSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="urn:invision:XpressSchema ../Schemas/XpressSchema.xsd" defaultNamespace="urn:invision:enduserdoc">
    <Attributes>
      <!-- Individual attribute definition elements and child elements -->
    </Attributes>
    <Emphasis>
      <!-- Individual emphasis definition elements and child elements -->
    </Emphasis>
    <Elements>
      <!-- Individual element definition elements and child elements -->
    </Elements>
  </XpressSchema>

Elements

The below figure shows a simple element structure.

In defining the RevisionHistory element and the elements that make up its structure, the first item defined would be RevisionRemark. Next, Revision would be defined, and would reference RevisionRemark as a required child element, and specify how many are permitted. Finally, RevisionHistory would conclude the definition, and would reference Revision as a required child element, and specify how many are permitted.

Comment Lines

It can be helpful to isolate the various elements and attributes that will be used according to category. This makes it easier to read the XAS later, and can help prevent difficulties such as declaring components in the wrong order. Doing this is not required, nor is there a 'right' way to do it. However, the following categorization method has been shown to be very useful:

  • Attributes. Metadata attributes for elements and emphasis styles are defined first. Elements and emphasis styles may share attributes.

  • Emphasis. Each type of emphasis is declared and defined. If you have a complex set of Emphasis requirements, you may want to break this section down further.

  • Miscellaneous Elements. These are all the elements other than list, table, and media elements that can be contained by top-level elements.

  • List Elements. This section will contain any element that can be a part of a list but can't be a child of any other element type.

  • Table Elements. This section will contain any element that a Table element comprises.

  • Media Elements. This section will contain any element that relates specifically to media elements.

  • Container Elements. Elements that can contain almost every other type of document component, but can themselves also be contained by top-level elements, are placed in this section. For example, sections and subsections of a chapter might be defined here.

  • Top-Level Elements. The elements which are container elements for the rest of the elements in the document class, but are themselves children to the root element, are declared here, followed by the root element itself.

A file using this method of categorization might look like the one shown below.

<?xml version="1.0" encoding="UTF-8"?>
<XpressSchema                xmlns="urn:invision:XpressSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="urn:invision:XpressSchema ../Schemas/XpressSchema.xsd" defaultNamespace="urn:invision:enduserdoc">
  <Attributes>
    <!--   Element Attributes   -->
  </Attributes>
  <Emphasis>
    <!-- Emphasis Styles -->
  </Emphasis>
  <Elements>
    <!-- Miscellaneous Elements -->
    <!--      List Elements     -->
    <!--      Table Elements    -->
    <!--      Media Elements    -->
    <!--    Container Elements  -->
    <!--    Top-Level Elements  -->
  </Elements>
</XpressSchema>

Attribute Groups

XpressSchema.xsd identifies two attribute groups which can be associated with an element by reference, obviating the need to define each attribute separately. These groups are common attributes and field attributes. Attributes belonging to each of these groups are defined below.

Note that these are not the only attributes that may be used, and at times, an attribute from a group might be applied separately to an element. The particular attributes that may be applied to each element are identified in the Attribute Definition Elements section below.

Common Attributes

Common attributes serve to identify the elements in the schema. 

<b>Table: Schema Root Element Attributes and Values</b>

Attribute

Description

Example

name

Specifies the name of the attribute definition.

<AttributeDef name="section001">

 

namespace

Specifies the namespace to use for the element, and overrides the default namespace. This allows the use of multiple schemas in a single document.

<AttributeDef name="section01" namespace="sidebar">

 

prefix

If the namespace attribute is used, it must be accompanied by this attribute, which will append the specified prefix to the element name in the output XML, associating the element with the overriding namespace.

<AttributeDef name="MediaReference" namespace="urn:invision:msp-extensions" prefix="inv"

 

xmlname

Specifies the name that will be used as the element name in the XML file. Used to allow an attribute to have distinct enumerated values depending on which element it's associated with. Create a separate AttributeDef for each attribute instance and assign the same xmlname value to each one.

<AttributeDef name="section01" xmlname="section">

 

Field Attributes

<b>Table: Field Attributes</b>

Attribute

Description

Example

attrGroupName

Specifies the name of the tab in the attribute panel on which the attribute being defined will appear.

<AttributeDef name="pubdate" datatype="datetime" format="MMDDYYYY" friendly="Publication Date" attrGroupName="Publication Information"/>

 

datatype

Specifies the type of data to be supplied. Possible values are combobox, datetime, droplist, imageheight, imagewidth, imageheightdpi, imagewidthdpi, multiline, string, time, uniqueidentifier, columnBreak, pageBreak, and sectionBreak.

See Table 11‑4 for descriptions of these datatypes.

See Table 11‑5 for descriptions of table specific datatypes.

Default is string.

<AttributeDef name="id" datatype="uniqueidentifier"/>

 

default

Specifies a default value for the attribute being defined.

<AttributeDef name="securClassif" friendly="Security Classification" attrGroupName="Releasability" default="TS"/>

 

displayPattern

Used in the error message displayed to inform the user that the data entered does not match the pattern.

 

externalMethodId

Specifies an externalMethodId that provides a string that XML Author will used to populate an attribute's combo box list in the Attributes Panel.

<AttributeDef name="author" friendly="Author Name" externalMethodId="TechPubsStaff"/>

 

fixed

Assign the fixed attribute to a AttributeType for an element definition to uniquely identify the element among sibling elements that have identical xmlname values. The value of fixed is a string that is unique within the collection of sibling element definitions.

In this example, both ElementDefs define elements that are siblings. Both will be present in the XML document as <chapter> nodes, but the chapterType attribute for those nodes will be set according to the fixedattribute. This allows sibling elements with the same XML name to have entirely different structure definitions.

<ElementDef name="instruction" friendly="Instructional Chapter" xmlname="chapter">

  <Sequence>

    <!-- Sequence definition information -->

  </Sequence>

  <Attributes>

    <AttributeType name="chapterType" visible="true" fixed="instruct"/>

    <!-- Other AttributeTypes -->

  </Attributes>

 

</ElementDef>

<ElementDef name="concept" friendly="Conceptual Chapter" xmlname="chapter">

  <Sequence>

    <!-- Sequence definition information -->

  </Sequence>

  <Attributes>

    <AttributeType name="chapterType" visible="true" fixed="concept"/>

    <!-- Other AttributeTypes -->

  </Attributes>

</ElementDef>

 

Also see Field Attributes – fixed example.

format

Specifies a format for the data to be supplied. For example, MMDDYYYY represents a date field that is specified as Month, Day, and Year.

See "Valid date formats" more a list of valid date formats.

 

<AttributeDef name="pubdate" datatype="datetime" format="MMDDYYYY"/>

 

 

friendly

Specifies a user-friendly name for the attribute that will be displayed to the user in the attribute panel.

<AttributeDef name="pubdate" datatype="datetime" format="MMDDYYYY" friendly="Publication Date"/>

 

keepWithNext

Boolean. Defaults to false. When set to true, creates an attribute that, when present on an ElementDef, indicates that the element may be toggled so that it will break across a new page with the element that follows it. For example, consider this AttributeDef:

<AttributeDef name="keep-with-next" friendly="Keep with Next" keepWithNext="true" visible="false/>

Any ElementDef that includes the keep-with-next attribute defined above could be toggled to mimic Word’s “Keep with Next” paragraph behavior.

This feature does not support images. For tables, this feature supports table rows only.

 

pattern

When specified, selecting OK in the Attribute Panel validates the field against the pattern. If the attribute is required, the validation error will also be triggered if the field is null.

 

readonly

Specifies whether the value of the attribute will be read-only. Defaults to false.

<AttributeDef name="documentType" default="Memo" readonly="true"/>

 

required

Specifies whether the attribute value is mandatory. Defaults to false.

<AttributeDef name="author" required="true"/>

 

visible

Specifies whether the attribute will be visible in the Attribute Panel. Defaults to true.

<AttributeDef name="documentType" default="Memo" visible="false"/>

 

widowControl

Boolean. Defaults to false. When set to true, creates an attribute that, when present on an ElementDef, indicates that the element may be toggled so that it will allow widowed and orphaned text to be left at the bottom and tops of pages, respectively. For example, consider this AttributeDef:

<AttributeDef name="widow-control" friendly="Widow Orphan control" default="true" widowControl="true" readonly="true" visible="false"/>

Any ElementDef that includes the widow-control attribute defined above could be toggled to mimic Word’s “Widow/Orphan Control” paragraph behavior.

 

dir

Specifies the text direction in an element or document. Defaults to ltr(left to right).

 

Valid date formats

The following link provides a list of valid date formats

Field Attributes — fixed example

This is an additional example to accompany the definition of the fixed attribute. See Table: Field Attribute. 

If the schema has <p/> defined three different ways, one is text-only, one is children-only (no text), and one is mixed (allows text and children). Quark XML Author must be able to differentiate within the configuration between the elements in order to work with documents containing structures like the following.

   <p> I’m a text only para</p>
   <p>
      <child>
      <child>
      <child>
   </p>
   <p> I can have text and children
      <child>
   </p>

The following shows how those elements would be configured:

   <AttributeDef name="para_type" visible="false" readonly="true"/>
 
   <ElementDef xmlname="p" name="p_text_only" friendly="Text Paragraph" />
      <Attributes>
         <AttributeType name="para_type" fixed="textOnly"/>
      </Attributes>
   </ElementDef>
   <ElementDef xmlname="p" name="p_children_only" friendly="Paragraph Section" />
      <Attributes>
         <AttributeType name="para_type" fixed="childrenOnly"/>
      </Attributes>
   </ElementDef>
   <ElementDef xmlname="p" name="p_mixed" friendly="Paragraph" />
      <Attributes>
         <AttributeType name="para_type" fixed="mixed"/>
      </Attributes>
   </ElementDef>

The following content example shows the three para elements in use:

   <p para_type="textOnly"> I’m a text only para</p>
   <p para_type="childrenOnly">
      <child>
      <child>
      <child>
   </p>
   <p para_type="mixed"> I can have text and children
      <child>
   </p>
<b>Table: Field Attributes — Datatype Values</b>

datatype

Description

Example

columnBreak

Set an AttributeDef’s datatype to columnBreak to indicate a Column Break attribute.

See section 9.7 for information on DocConfig settings. See section 12.3 for information about creating and using break attributes.

 

datetime

This attribute stores the date and time.

 

droplist

droplist lets users select from a list of values populated from values specified in the schema.

 

imageheight, imagewidth, imageheightdpi, imagewidthdpi

In general, these attributes are set when an image is inserted, refreshed, or resized. When a document is opened, if these attributes don't exist then they're added and they're set using the values retrieved from the image file.

When an image is inserted, these attributes are added and they're set using the values retrieved from the image file. In those two scenarios, if the system determines that the image size is larger than the area available on the Word canvas, then the system will reduce the size of image to fit while maintaining the aspect ratio. These attributes are set when the user manually alters the size of the image on the Word canvas.

The user may set the size to be larger than the area available on the Word canvas. imageheight and imagewidth values are in pixels.

 

multiline

multiline indicates that the textbox for the attribute will have three lines, will support carriage returns, and display a tooltip showing the entire value of the attribute when the mouse hovers over it.

 

pageBreak

Set an AttributeDef’s datatype to pageBreak to indicate a Page Break attribute.

See section 9.7 for information on DocConfig settings. See section 12.3 for information about creating and using break attributes.

 

sectionBreak

Set an AttributeDef’s datatype to sectionBreak to indicate a Section Break attribute.

See section 9.7 for information on DocConfig settings. See section 12.3 for information about creating and using break attributes.

 

string

A simple string. This is the default datatype.

 

time

This attribute stores the time.

 

uniqueidentifier

If the value is uniqueidentifier, a GUID will be generated as the value of the attribute.

 

directionAttribute

Allows support for direction attributes for elements.

<AttributeDef name="dir" datatype="directionAttribute" visible="false"/>

 

The following datatypes can be applied to all table elements and be inherited in the order of Table > Group > Section > Row | Column > Cell (meaning that the cell inherits from the Column only if it's explicitly defined on the Column and not on the Row).

<b>Table: Field Attributes — datatype values for table elements</b>

Datatype

Description

Example

tableBorderBottomStyle

Set to 1 to style the bottom border using the style specified in the Table Style. Set to 0 to use no styling. Note that if rowBorderStyle is set to None, then setting tableBorderBottomStyleto 1 will have no effect. Styling is not applied. This applies to the bottom border of the table element, not including the table frame.

<AttributeDef name="rowsep"datatype="tableBorderBottomStyle"friendly="Border Style - bottom"visible="false"/>

tableBorderRightStyle

Specifies the right border of the table element, not including the table frame.

<AttributeDef name="colsep" datatype="tableBorderRightStyle" friendly="Border Style - right" visible="false"/>

tableAlignmentHorizontal

Specifies the horizontal alignment of the content.

<AttributeDef name="align" datatype="tableAlignmentHorizontal" friendly="" visible="false" default="left">

   <Restriction>

      <Enumeration value="left"/>

      <Enumeration value="right"/>

      <Enumeration value="center"/>

      <Enumeration value="just"/>

    </Restriction>

</AttributeDef>

tableAlignmentVertical

Specifies the vertical alignment of the content.

<AttributeDef name="valign" datatype="tableAlignmentVertical" friendly="" visible="false" default="top">

   <Restriction>

      <Enumeration value="top"/>

      <Enumeration value="middle"/>

      <Enumeration value="bottom"/>

   </Restriction>

</AttributeDef>

Table-level datatypes
<b>Table: Field Attributes — datatype values for tables</b>

Datatype

Description

Example

tableFrame

Specifies the border of the table, not including cells.

<AttributeDef name="frame" datatype="tableFrame" friendly="Table Frame Borders" visible="false" default="all">

   <Restriction>

      <Enumeration value="all"/>

      <Enumeration value="top"/>

      <Enumeration value="bottom"/>

      <Enumeration value="topbot"/>

      <Enumeration value="sides"/>

      <Enumeration value="none"/>

      </Restriction>

</AttributeDef>

<b>Table: Field Attributes — datatype values for table rows/columns</b>

Datatype

Description

Example

tableRowColumnIndex

Specifies the index of the row/column that contains the cell. Required for merged cells in CALS tables.

<AttributeDef name="colnum" datatype="tableRowColumnIndex" friendly="" visible="false"/>

tableRowColumnIdentifier

The name or identifier of the row/column that contains the cell. Required for merged cells in CALS tables.

<AttributeDef name="colname" datatype="tableRowColumnIdentifier" friendly="" visible="false"/>

<b>Table: Field Attributes — datatype values for table cells</b>

Datatype

Description

Example

tableCellColumnStart

For a merged cell, specifies the column in which the cell starts. Used to facilitate CALS namest.

<AttributeDef name="namest" datatype="tableCellColumnStart" friendly="" visible="false"/>

 

tableCellColumnEnd

For a merged cell, specifies the column in which the cell ends. Used to facilitate CALS nameend.

<AttributeDef name="nameend" datatype="tableCellColumnEnd" friendly="" visible="false"/>

 

tableCellColumnCount

For a merged cell, specifies the number of columns the cell spans. Used to facilitate HTML colspan and horizontal merge.

<AttributeDef name="namecount" datatype="tableCellColumnCount" friendly="" visible="false"/>

 

tableCellRowCount

Specifies the number of additional rows in the merge (equals total rows minus one). Required for vertically merged cells in CALS tables.

<AttributeDef name="cellrowcount" datatype="tableCellRowCount" friendly="" visible="false"/>

 

tableCellContentRotate

Specifies that the content of the cell should be rotated.

<AttributeDef name="rotate" datatype="tableCellContentRotate" friendly="" visible="false"/>

 

tableCellBackgroundColor

Specifies the background color (hex RGB) of the cell. To display a specific set of color choices to the user, use Restriction Enumerations. Otherwise, the user interface displays Word’s stock colors for cell shading.

<AttributeDef name="bkgndcolor" datatype="tableCellBackgroundColor" friendly="" visible="false"

  >

   <Restriction>

      <Enumeration value="F0F8FF "/>

      <Enumeration value="FAEBD7"/>

   </Restriction>

</AttributeDef>

 

tableCellRowSpan

Specifies the total number of rows in the merge. Required for vertically merged cells in HTML tables. Used to facilitate HTML rowspan.

<AttributeDef name="rowspan" datatype="tableCellRowSpan" visible="false"/>

 

tableCellMoreRows

Specifies the number of additional rows in the merge (equals total rows minus one). Required for vertically merged cells in CALS tables. Used to facilitate CALS morerows. Behaves identically to the deprecated tableCellRowCount. It's added for clarity for the engineer implementing CALS. The current value of tableCellRowCount is preserved for backward compatibility despite the misleading name.

<AttributeDef name="morerows" datatype="tableCellMoreRows" visible="false"/>

 

<b>Table: Field Attributes — datatype values for table, group, section</b>

Datatype

Description

Example

tableColumnCount

For a table or table group, specifies the number of columns it contains.

<AttributeDef name="cols" datatype="tableColumnCount" friendly="" visible="false"/>

 

tableColumnWidth

Specifies the width of the column. Required for merged cells in CALS tables. Required to allow the width of columns to be modified. See "Column Widths" for details.

<AttributeDef name="colwidth" datatype="tableColumnWidth" friendly="" visible="false"/>

 

tableRowCount

For a table, table group or table section, specifies the number of rows it contains. Specifies the height of the row. Required to allow the height of the rows to be modified.

<AttributeDef name="rows" datatype="tableRowCount" friendly="" visible="false"/>

 

tableRowHeight

Specifies the height of the row. Required to allow the height of rows to be modified.

<AttributeDef name="rowHeight" xmlname="height" datatype="tableRowHeight" visible="false"/>

 

tableStyle

Specifies the name of the style of the table. For tables or groups only.

<AttributeDef name="tgroupstyle" datatype="tableStyle" friendly="" visible="false"/>