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 Table 11‑1.
Table 11‑1: Schema Root Element Attributes and Values
|
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
Figure 11‑1 shows a simple element structure.

Figure 11‑1: 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 of 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 cannot 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.
Table 11‑2: Common Attributes
|
Attribute |
Description |
Example |
|
name |
Specifies the name of the attribute definition. |
|
|
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. |
|
|
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. |
|
|
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 is associated with. Create a separate AttributeDef for each attribute instance and assign the same xmlname value to each one. |
|
Field Attributes
Table 11‑3: Field Attributes
|
Attribute |
Description |
Example |
|
attrGroupName |
Specifies the name of the tab in the attribute panel on which the attribute being defined will appear. |
|
|
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. |
|
|
default |
Specifies a default value for the attribute being defined. |
|
|
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. |
|
|
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 fixed attribute. This allows sibling elements with the same XML name to have entirely different structure definitions.
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.
|
|
|
friendly |
Specifies a user-friendly name for the attribute that will be displayed to the user in the attribute panel. |
|
|
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. |
|
|
required |
Specifies whether the attribute value is mandatory. Defaults to false. |
|
|
visible |
Specifies whether the attribute will be visible in the Attribute Panel. Defaults to true. |
|
|
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 11‑3: 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>Table 11‑4: Field Attributes – datatype values
|
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 do not exist then they are added and they are set using the values retrieved from the image file. When an image is inserted, these attributes are added and they are 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. |
|
Table 11‑5: Field Attributes – datatype values for table elements
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 is explicitly defined on the Column and not on the Row).
|
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 tableBorderBottomStyle to 1 will have no effect. Styling is not applied. This applies to the bottom border of the table element, not including the table frame. |
|
|
tableBorderRightStyle |
Specifies the right border of the table element, not including the table frame. |
|
|
tableAlignmentHorizontal |
Specifies the horizontal alignment of the content. |
|
|
tableAlignmentVertical |
Specifies the vertical alignment of the content. |
|
Table 11‑6: Field Attributes – datatype values for tables
Table-level datatypes.
|
Datatype |
Description |
Example |
|
tableFrame |
Specifies the border of the table, not including cells. |
|
Table 11‑7: Field Attributes –datatype values for table rows/columns
|
tableRowColumnIndex |
Specifies the index of the row/column that contains the cell. Required for merged cells in CALS tables. |
|
|
tableRowColumnIdentifier |
The name or identifier of the row/column that contains the cell. Required for merged cells in CALS tables. |
|
Table 11‑8: Field Attributes – datatype values for table cells
|
Datatype |
Description |
Example |
|
tableCellColumnStart |
For a merged cell, specifies the column in which the cell starts. Used to facilitate CALS namest. |
|
|
tableCellColumnEnd |
For a merged cell, specifies the column in which the cell ends. Used to facilitate CALS nameend. |
|
|
tableCellColumnCount |
For a merged cell, specifies the number of columns the cell spans. Used to facilitate HTML colspan and horizontal merge. |
|
|
tableCellRowCount |
Specifies the number of additional rows in the merge (equals total rows minus one). Required for vertically merged cells in CALS tables. |
|
|
tableCellContentRotate |
Specifies that the content of the cell should be rotated. |
|
|
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. |
|
|
tableCellRowSpan |
Specifies the total number of rows in the merge. Required for vertically merged cells in HTML tables. Used to facilitate HTML rowspan. |
|
|
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 is added for clarity for the engineer implementing CALS. The current value of tableCellRowCount is preserved for backward compatibility despite the misleading name. |
|
Table 11‑9: Field Attributes – datatype values for table, group, section
|
Datatype |
Description |
Example |
|
tableColumnCount |
For a table or table group, specifies the number of columns it contains. |
|
|
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. |
|
|
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. |
|
|
tableRowHeight |
Specifies the height of the row. Required to allow the height of rows to be modified. |
|
|
tableStyle |
Specifies the name of the style of the table. For tables or groups only. |
|