Quark XML Author Structure Emphasis Definition
Each element that makes up the emphasis definition section of the schema is defined below.
The Emphasis element contains the collection of emphasis definition elements for the schema, and is a direct child of the XpressSchema root element. It uses no attributes.
EmphasisDef
EmphasisDef defines a single emphasis style that may be associated with text elements in the schema. Its Style child element defines the actual appearance of the emphasis within the document. EmphasisDef may use any of the attributes defined in the commonAttributes group. It may also use the attributes defined below.
Table 13‑1: EmphasisDef Attributes
|
Attribute Name |
Required |
Definition |
|
contextId |
no |
A dash-delimited list of rule IDs in a validation configuration file. |
|
excludeFromEmphasisCombo |
no |
Defaults to false. When set to true, the emphasis is not visible in the drop-down box. |
|
friendly |
no |
Specifies a name for the emphasis style to be presented to the user within the interface, instead of the emphasis element name |
|
preserveSpace |
no |
Defaults to false. When set to true, the emphasis will include any trailing space/non-breaking-spaces that are part of the selection. For example, the trailing space/non-breaking-space that is selected when a user double-clicks on a word. |
|
readonly |
no |
Defaults to false. If set to true, the textnode of a readonly emphasis may not be changed. The emphasis can be deleted if its parent container is editable. Emphasis may not be nested within a readonly emphasis. |
|
selectOnFocus |
no |
Defaults to false. When set to true, Quark XML Author will auto-select the entire emphasis when the user clicks or selects within the emphasis region. If the user selects a range that includes but extends outside the emphasis, Quark XML Author does not perform the auto-selection. This allows the user to select and over-type the emphasized text (assuming that inv:required is not true). |
|
tooltipTransform |
no |
Defines the path to an XSLT file used to define the text displayed when the user hovers over the emphasized text. |
Specialized
Many features of Quark XML Author, such as footnotes, end notes, and cross reference links, are implemented as emphasis. The <Specialized> node is used to define enhanced emphasis functionality.
The specialized node’s child elements define the emphasis behavior. These are <Footnote>, <Endnote>, <Link>, <Entity>, and <ProcessingInstruction>.
Footnote
Use the <Footnote> element to establish presentation options for document footnotes.
Table 13‑2: Footnote Attributes
|
Attribute Name |
Required |
Definition |
|
allowedNumberingSchemes |
|
Used for footnote emphasis. Specifies the allowed numbering formats that can be used for note items. If more than one is allowed, they are separated by spaces. Possible values are:
|
|
captionAttribute |
no |
Specifies the name of the EmphasisDef attribute that will contain the value of a custom mark assigned by the author at runtime. |
|
disableCustomMarkTextbox |
no |
Boolean. Set to true if the Custom Mark option should be disabled in the Footnote Options dialog. Defaults to false. |
|
footnoteLocation |
yes |
Determines where footnotes will be placed in the rendered document. Valid values are document, page, section, and text. |
The sample below shows one possible Footnote configuration.
<EmphasisDef name="fn" friendly="Footnote">
<Specialized>
<Footnote footnoteLocation="page" allowedNumberingSchemes="smallRoman" captionAttribute="callout"/>
</Specialized>
<Style superscript="true"/>
<Attributes>
<AttributeType name="callout"/>
</Attributes>
<Emphasis/>
</EmphasisDef>Endnote
Use the <Endnote> element to establish presentation options for document endnotes and tablenotes. Endnotes are generalized to facilitate notes that are placed at the end of a content element. Therefore, endnote is used to facilitate tablenote.
Table 13‑3: Endnote Attributes
|
Attribute Name |
Required |
Definition |
|
allowedNumberingSchemes |
|
Used for endnote and tablenote emphasis. Specifies the allowed numbering formats that can be used for note items. If more than one is allowed, they are separated by spaces. Possible values are:
|
|
captionAttribute |
no |
Specifies the name of the EmphasisDef attribute that will contain the value of a custom mark assigned by the author at runtime. |
|
disableCustomMarkTextbox |
no |
Boolean. Set to true if the Custom Mark option should be disabled in the End note Options dialog. Defaults to false. |
|
endnoteElementDef |
|
Specifies the name of the endnote element definition. |
The implementation of a endnote is different from footnote in that endnote requires an additional element for storage and placement of the note.
The following sample configuration fragments show one possible tablenote configuration. Critical components are highlighted.
<!- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<ElementDef name="Tablenote" visible="false">
<Endnote/>
</ElementDef>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - for storage and placement of the tablenote - - - - - - - - - - - - - - - - - - - - - - - -->
<ElementDef name="entry" friendly="Cell" allowCut="false" allowRemove="false">
<Section>
<Para defaultHyperlink="xref@format='html'">
<Emphasis>
<EmphasisType name="b"/>
<EmphasisType name="i"/>
<EmphasisType name="u"/>
<EmphasisType name="sup"/>
<EmphasisType name="sub"/>
<EmphasisType name="term"/>
<EmphasisType name="xref"/>
<EmphasisType name="q"/>
<EmphasisType name="keyword"/>
<EmphasisType name="tm"/>
<EmphasisType name="tn"/>
<EmphasisType name="fontColor"/>
<EmphasisType name="fontSize"/>
</Emphasis>
</Para>
</Section>
</ElementDef>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<ElementDef name="table" friendly="Table" visible="false">
<Section>
<Sequence minOccurs="0">
<SectionType name="title" friendly="Table Title"/>
</Sequence>
<Sequence>
<SectionType name="tgroup"/>
</Sequence>
<Sequence>
<!-- minOccurs = 0 and maxOccurs=1 always for a EndnoteType element -->
<!-- Furthermore there can only be one reference of a particular EndNoteType element in the entire schema-->
<EndnoteType name="Tablenote"/>
</Sequence>
<Sequence minOccurs="0">
<SectionType name="desc" friendly="Table Caption"/>
</Sequence>
</Section>
<Attributes>
<AttributeType name="id"/>
<AttributeType name="conref"/>
<AttributeType name="frame"/>
<!--
<AttributeType name="rowsep"/>
<AttributeType name="colsep"/>
-->
</Attributes>
</ElementDef>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<EmphasisDef name="tn" friendly="Tablenote" >
<Specialized>
<Endnote endnoteElementDef="Tablenote" allowedNumberingSchemes="arabic" captionAttribute="callout" disableCustomMarkTextbox="true"/>
</Specialized>
<Style superscript="true"/>
<Attributes>
<AttributeType name="callout"/>
<AttributeType name="class"/>
<AttributeType name="outputclass"/>
</Attributes>
<!— The Formatting attributes gives the ability to apply formatting attributes to a Tablenote
<Formatting>
<FormattingType name="b"/>
<FormattingType name="i"/>
<FormattingType name="u"/>
<FormattingType name="strikethrough"/>
<FormattingType name="sub"/>
<FormattingType name="sup"/>
<FormattingType name="color"/>
<FormattingType name="highlight"/>
</Formatting>
</EmphasisDef>Link
Use the <Link> node to define the behavior of hyperlink emphasis. Hyperlinks can be defined as <Internal> (target is within the document), <External> (target is another document or a URL), or both, via <Multiple>. The <Link> node may also use the <Custom> node to indicate that the link creation and navigation behavior will be handled by an external application.
External
Use the <External> node to indicate a hyperlink to an external target, such as a different document, a component within a different document, or a URL. The <External> node can be used as a direct child of <Link> or it can be used as a child of <Multiple> when a combination of internal and external links is desired.
When used as a child of <Multiple>, the substyle attribute is required. The value of the substyle attribute specifies the name of a substyle, defined in the <SubStyles> node of the <EmphasisDef>, that defines the appearance of the external link.
When used as a child of <Link>, the appearance of the link is specified by the <Style> node.
Table 13‑4: External Attributes
|
Attribute Name |
Definition |
|
substyle |
Required when used as a child of <Multiple>. Specifies the name of the substyle that defines the appearance of the external link. |
Internal
Use the <Internal> node to indicate a hyperlink to an internal target, such as a component within the document. One or more child <Target> nodes define the elements that may be link targets.
The configuration attribute specifies the file which contains the Link Management configuration. Typically, this is the DocConfig file for the document class.
When used as a child of <Multiple>, the substyle attribute is required. The value of the substyle attribute specifies the name of a substyle, defined in the <SubStyles> node of the <EmphasisDef>, that defines the appearance of the external link.
When used as a child of <Link>, the appearance of the link is specified by the <Style> node.
Table 13‑5: Internal Attributes
|
Attribute Name |
Definition |
|
configuration |
Points to the file that contains the Link Management configuration. Typically, this is the DocConfig file for the document class. |
|
substyle |
Required when used as a child of <Multiple>. Specifies the name of the substyle that defines the appearance of the external link. |
The <Internal> node can be used as a direct child of <Link> or it can be used as a child of <Multiple> when a combination of internal and external links is desired.
Target
The <Target> element is used to define an element that may be the target of an Internal hyperlink. Each target type is defined by a separate <Target> element; the <Internal> node contains one or more of them.
Table 13‑6: Target Attributes
|
Attribute Name |
Definition |
|
definition |
The name of the <ElementDef> of the target element. This value is the value of the name attribute, not the xmlname of the element. |
|
link |
The name of the <ElementDef> attribute that supplies the target ID. |
|
xpath |
Deprecated. Formerly specified the XPath pointer to a document location. |
Custom
Use the <Custom> node to indicate that the link creation and behavior will be handled by an external application.
When used as a child of <Multiple>, the substyle attribute is required. The value of the substyle attribute specifies the name of a substyle, defined in the <SubStyles> node of the <EmphasisDef>, that defines the appearance of the external link.
When used as a child of <Link>, the appearance of the link is specified by the <Style> node.
Table 13‑7: Custom Attributes
|
Attribute Name |
Definition |
|
assembly |
The name of the external assembly that handles the link. |
|
class |
The name of the external class that handles the link. The assembly and class must implement the Invision.Xpress.Interfaces.EmphasisInterfaces.ICustomLink interface. |
|
substyle |
Required when used as a child of <Multiple>. Specifies the name of the substyle that defines the appearance of the custom link. |
Multiple
Use the <Multiple> node to wrap a combination of External, Internal, or Custom nodes.
Entity
This emphasis type is used to tag a content entity in the document. Any content entity that is tagged by this emphasis will maintain a synchronous mapping with the entity node in the document.
Adding this definition to the schema implies that every text XML entity encountered in the parent para type element under which this emphasis is defined will be wrapped by this emphasis element. Without defining this emphasis, any encountered text entities will be converted to their literal values and rendered on the canvas. They will be serialized as literal text. Use the <Entity> element to establish presentation options for content entities. Its child elements define its behavior.
Internal content entities defined within the document may be added, modified or deleted. External content entities (public and private) defined outside of the document may not be added, modified or deleted.
1. Wrapper
This is used for backward compatibility to allow for metadata-based (attributes) entity support. With this approach, an entity can be associated with metadata which will persist in the serialized document. This metadata among other things can be used to control whether an entity can be edited/deleted (using attributeName/attributeValue pairs) from the Modify/Delete children.
Add
Specifies whether an entity can be added through the UI. Set its allow attribute to true to allow the entity to be added, false to prevent.
Modify
If allow attribute is set to true, or an entity reference wrapper element has attributeName equal attributeValue, the instance value may be modified through the UI.
Table 13‑8: Modify Attributes
|
Attribute Name |
Required |
Definition |
|
allow |
no |
Boolean. Set to true if the content entity can be modified. Set to false if the content entity may not be modified. Defaults to true. |
|
attributeName |
no |
Name of the attribute which specifies whether the entity can be modified. |
|
attributeValue |
no |
Value of the attribute which specifies whether the entity can be modified. |
Delete
If an entity reference wrapper element has attributeName equal attributeValue, the instance value may be deleted through the UI. If allow attribute is set to true, the entity definition may be deleted, provided there are no entity references.
Table 13‑9: Delete Attributes
|
Attribute Name |
Required |
Definition |
|
Allow |
no |
Boolean. Set to true if the content entity can be deleted. Set to false if the content entity may not be deleted. Defaults to true. |
|
attributeName |
no |
Name of the attribute which specifies whether the entity can be deleted. |
|
attributeValue |
no |
Value of the attribute which specifies whether the entity can be deleted |
1. UserDefined
This is used to support a more generic entity scenario where metadata and wrapper emphasis are not preserved. During serialization, the emphasis element wrapper will be dropped and only the original entity will be written.
Table 13‑10: UserDefined Attributes
|
Attribute Name |
Required |
Definition |
|
allowAdd |
no |
Boolean. Specifies whether a new Internal entity definition can be added to the current document. Defaults to true. |
|
allowDelete |
no |
Boolean. Specifies whether an entity definition can be deleted. An entity definition can be deleted only if there are no entity references within the document. This attribute is irrelevant for external entities. Quark XML Author will not delete external entity definitions. Defaults to true. |
|
allowModify |
no |
Boolean. Specifies whether an entity definition’s value can be modified. This attribute is not relevant for external entities. Quark XML Author will not modify external entity definitions. Defaults to true. |
ProcessingInstruction
This emphasis type is used to tag a processing instruction in the document. This emphasis is required to be defined to preserve any existing processing instructions in the document otherwise they will be dropped from document.
If Quark XML Author encounters an XML processing instruction in a document, it will temporarily apply a special emphasis to that processing instruction. This emphasis is read-only to prevent any changes to the processing instruction. The emphasis provides a visual indicator to differentiate a processing instruction from surrounding narrative text. When the document is saved, the special emphasis is removed. This returns the processing instruction to its original state.
In the following sample, a Specialized emphasis definition has been added to wrap processing instructions in as emphasis to display in the UI. The emphasis will be read-only and will not show up in the emphasis combo box.
<EmphasisDef name="PI" friendly="Processing Instruction">
<Specialized>
<ProcessingInstruction/>
</Specialized>
<Style backColor="blue"/>
</EmphasisDef>
With the above structure, any existing PIs in the document will be wrapped in the above emphasis . Given an element that looks like the following:
<p> Testing para with PIs in it <?show [AQ]?> - more text here</p>
The XOM structure will look like the following:
<p> Testing para with PIs in it <PI><?show [AQ]?> </PI>- more text here</p>
On Save/Normalize, the special emphasis is removed.
Style
Style defines how the Emphasis will appear in the Word document, through its attributes, which are described below. All are optional.
Style Attributes
Table 13‑11: Style Attributes
|
Attribute Name |
Definition |
|
backColor |
Name of the color to be used as background highlighting for the emphasized text in the Word document. A list of valid color names is provided in Appendix A. Alternately, you may specify the RGB components of the color using numbers from 0 to 255, separated by commas. |
|
bold |
Set to true if the emphasized text is to be bolded. Defaults to false. |
|
fontName |
Name of a font that will be used to render the emphasized text in the Word document. The font named must be installed on the user’s computer. |
|
fontSize |
Font size, in points, to be used to render the emphasized text in the Word document. The value must be an integer no less than 8 nor greater than 72. |
|
foreColor |
Name of the color to be used to render the emphasized text in the Word document. A list of valid color names is provided in Appendix A. Alternately, you may specify the RGB components of the color using numbers from 0 to 255, separated by commas. |
|
italic |
Set to true if the emphasized text is to be italicized. Defaults to false. |
|
strikethrough |
Set to true if the emphasized text is to be rendered with strikethrough formatting. Defaults to false. |
|
subscript |
Set to true if the emphasized text is to be rendered in subscript. Defaults to false. |
|
superscript |
Set to true if the emphasized text is to be rendered in superscript. Defaults to false. |
|
underline |
Set to true if the emphasized text is to be underlined. Defaults to false. |
Substyles
An option for emphasis is to use Substyles instead of a single Style. Substyles allow you to assign multiple appearances to a single emphasis style. The user will see each appearance as a separate emphasis, but in the document XML, the same emphasis element will appear, regardless of what the user chooses, and an attribute of the emphasis element will define its appearance. For example, in the example below, the user may choose to assign Bold, Underline, or Italics as an emphasis.
<EmphasisDef name="EmphasizedText" friendly="Emphasized Text">
<Style/>
<SubStyles key="emphasisType">
<SubStyle value="b" friendly="Bold">
<Style bold="true"/>
</SubStyle>
<SubStyle value="u" friendly="Underline">
<Style underline="true"/>
</SubStyle>
<SubStyle value="i" friendly="Italics">
<Style italic="true"/>
</SubStyle>
</SubStyles>
<Attributes>
<AttributeType name="emphasisType"/>
</Attributes>
</EmphasisDef>
Applied to the Strikethrough definition above, the emphasized text would look like this in the document XML:
<Paragraph>
Optional. Set to <EmphasizedText emphasisType="b">true</EmphasizedText> if the emphasized text is to be rendered with strikethrough formatting. Defaults to <EmphasizedText emphasisType="b">false</EmphasizedText>.
</Paragraph>
The <Substyles> element has one required attribute: key. The key value is the name of the attribute that defines the emphasis substyle. Thus, in the example above, emphasisType becomes the attribute for the EmphasizedText element.
Each <Substyle> child element will have a value attribute. The value of this attribute is the value that will be used to identify the type of emphasis to be applied to the selected text. The <Substyle> element in turn has a child <Style> element which defines its appearance, in exactly the same manner as the regular <Style> element does.
If the Substyles node is used, the sibling Style node must be an empty node with no
data as shown in the example above.
Attributes and Attributes Type
Emphasis elements can have attributes associated with them, just as regular elements can. They are referenced in the Attributes section of the EmphasisDef element. Each attribute to be associated with the emphasis definition is identified with the AttributeType element. The AttributeType element’s name attribute contains the name of an AttributeDef defined earlier in the schema. AttributeType can use any of the Field Attributes defined in Section 11.6.2.
<EmphasisDef name="Org" friendly="Organization">
<Style foreColor="Lavender"/>
<Attributes>
<AttributeType name="href.jwics"/>
<AttributeType name="href.siprnet"/>
<AttributeType name="href.stoneghost"/>
<AttributeType name="href.niprnet"/>
<AttributeType name="href.domain5"/>
</Attributes>
</EmphasisDef>Associating Emphasis with Elements
Emphasis definitions can be associated with the Para element definition. The Para element has an optional child element named Emphasis. This element contains an EmphasisType child node for each emphasis style that can be applied to the text in a Para element. An example is shown below.
<ElementDef name="para" friendly="Paragraph" style="Body Text">
<Section>
<Para>
<Emphasis>
<EmphasisType name="color"/>
<EmphasisType name="bold"/>
<EmphasisType name="italic"/>
<EmphasisType name="underline"/>
<EmphasisType name="link"/>
<EmphasisType name="replaceable"/>
<EmphasisType name="xref"/>
<EmphasisType name="systemitem"/>
<EmphasisType name="userinput"/>
<EmphasisType name="anchor"/>
<EmphasisType name="glossterm"/>
<EmphasisType name="index"/>
</Emphasis>
</Para>
</Section>
</ElementDef>Extensibility Methods
With some emphasis styles, you may want to provide a way for users to access a tool such as a metadata wizard via a command in the context menu. An emphasis style may use an extensibility method to provide this functionality.
The syntax for using Extensibility Methods is shown below:
<ExtensibilityMethods>
<ExtensibilityMethod id="method number" friendly="friendly name" showInComponentContextMenu="true or false" showInContextMenu="true or false" faceID="#"/>
</ExtensibilityMethods>Table 13‑12: ExtensibilityMethod Attributes
|
Attribute Name |
Required |
Definition |
|
enableXPath |
no |
Value is a boolean XPath expression which evalutes to a node-set in which false is returned for an empty node-set and true otherwise. When applied to the runtime element, indicates whether to enable the method on the Context Menu. The XPath expression will be evaluated against the current runtime element and thus must be relative to it. Namespaces are not supported in the xpath syntax. For the Ribbon, enableXpath on evaluates against root notes. Against current node is not supported. |
|
faceID |
no |
Allows you to specify an icon that will be displayed next to the context menu item. The value of faceId is an integer corresponding to the ID number of an icon in the Word template FaceID.dot. |
|
friendly |
no |
Specifies a name for the context menu command. |
|
id |
yes |
Specifies the ID of the EI method to be called. |
|
showInComponentContextMenu |
no |
Defaults to true. When set to false, the command will not appear in the Component context menu. |
|
showInContextMenu |
no |
Defaults to true. When set to false, the command will not appear in the main context menu, but may still appear in the Component context menu if showInComponentContextMenu is set to true. |
|
showXPath |
no |
Value is an XPath expression which evaluates to a node-set, and when applied to the current element, indicates whether to include the method on the context menu: if a node-set is returned, the method is included; if an empty node-set is returned, the method is omitted. When applied to the runtime element, indicates whether to include the method on the Context Menu. The XPath expression is applied to the XOM therefore the names are XOM element names. The XPath expression will be evaluated against the current runtime element and thus must be relative to it. Namespaces are not supported in the xpath syntax. For example, showXPath="self::node()[local-name()='Section']". XML Author does not support dynamic show/hide of Ribbon items, therefore showXPath is not applicable for Ribbon items. |
See Section 6 for more information on how to configure Extensibility Interface methods.
Restricting Emphasis Nesting
By default, emphasis defined for a text element cannot be nested. For example, if an element named Paragraph can have Bold, Italic, and Underline emphasis applied, those three emphases cannot be nested unless the schema designer explicitly allows it.
To allow emphasis nesting, add an Emphasis child to the EmphasisDef element. Within the Emphasis element, add an EmphasisType node for each emphasis that you want to allow to be nested. EmphasisType is a leaf node with one attribute: name. The value of name refers to the Emphasis name.
In the example below, the bold emphasis allows italic and underline emphasis to be nested within it.
<EmphasisDef name="bold" friendly="Bold">
<Style bold="true"/>
<Emphasis>
<EmphasisType name="italic"/>
<EmphasisType name="underline"/>
</Emphasis>
</EmphasisDef>
In the next example, the italic emphasis allows only underline emphasis to be nested within it.
<EmphasisDef name="italic" friendly="Italic">
<Style italic="true"/>
<Emphasis>
<EmphasisType name="underline"/>
</Emphasis>
</EmphasisDef>Thus, an author could apply bold emphasis to a range of text and then apply either italic or underline to it. However, if the author first applied italic emphasis to text, only the underline emphasis could subsequently be applied to that range, because italic does not permit bold to be nested within it. Likewise, the author could apply bold and then italic, but not bold, then italic, and then underline. To allow all three emphasis styles to be applied in any combination, all three would need to be defined to allow the others. The italic EmphasisDef would receive a second EmphasisType element, as shown below:
<EmphasisDef name="italic" friendly="Italic">
<Style italic="true"/>
<Emphasis>
<EmphasisType name="underline"/>
<EmphasisType name="bold"/>
</Emphasis>
</EmphasisDef>
The underline emphasis would be defined as shown below:
<EmphasisDef name="underline" friendly="Underline">
<Style underline="true"/>
<Emphasis>
<EmphasisType name="italic"/>
<EmphasisType name="bold"/>
</Emphasis>
</EmphasisDef>Inline Media
The EmphasisDef element has an optional child element named Media. This element contains a MediaType child node for each media type (both reference and embedded) that can be inserted inline to the text in a EmphasisDef element.
Table 13‑13: MediaType Attributes
|
Attribute |
Required |
Definition |
|
name |
yes |
Identifies an ElementDef node in the schema for the media element |
See section 14.6.2, ''Images
In order for images to be rendered properly on the Word canvas, every image element
definition in the solution must be configured with following image data-types: imagewidth,
imageheight, imagewidthdpi, imageheightdpi. See “Table 11‑4: Field Attributes – datatype
values”.
Supported Image Formats", See "Table 11-4:Field Attributes – datatype values:, Supported Image Formats”, for a list of supported image formats.
An ElementDef cannot have an media element as both a child element and an inline element
in the same ElementDef.
Inline OLE
The EmphasisDef element has an optional child element named OLE. This element contains a OLEType child node for each OLE type that can be inserted inline to the text in a EmphasisDef element.
Supported element types include:
-
MathTypeEquation
-
OLEWordDocument
Table 13‑14: OLEType Attributes
|
Attribute |
Required |
Definition |
|
name |
yes |
name of the elementDef node containing the OLE definition. |