Quark XML Author 10.0 — System Admin Guide

Implementing Cross References

A cross-reference is a navigable link within a document either to another location in the document or to an external document (another Quark XML Author document, a URL, or another type of document) stored in a content management system or other file storage system.

Implementing cross-references requires configuration in the AppConfig, DocConfig, Cross Reference EI Config and Schema.

AppConfig

A <Reference> node is necessary to resolve the cross-reference link. See this section for details on the <Reference> node. Implementing a cross-reference in a DITA environment can use the dita-cms assembly shown in the example below: 

<ResolveReferences>  
       <Reference pattern=".*" assembly="dita-cms" class="Invision.Xpress.CMS.DitaCMS">
              <Token>errorLogging=true</Token>
              <!-- The following specifies tooltip format: {0}=filename and {1}=title -->
              <Token>alternateTextFormat={1} - {0}</Token>
       </Reference>
</ResolveReferences>

DocConfig

There are two components to configure in the DocConfig file:

  1. EI Method

  2. ComponentCopy Node

EI Method

Create an Extensibility Method that points to the assembly, class, and method that returns the cross-reference string information. Implementing a cross-reference in a DITA environment can use the dita-cms assembly shown in the example below.

<Method id="GetComponentId" assembly="DITA-cms" class="Invision.Xpress.CMS.DitaCMS" method="GetComponentId">
  <Argument type="Filename"/>
  <Argument type="XomCurrentNode"/>
</Method>

ComponentCopy Node

Implement the <ComponentCopy> node (Section 9.5) with the getReferenceId attribute. The value of this attribute is the value of the id attribute of the Extensibility Interface <Method> defined above. If transform attribute is present in ComponentCopy node, then the cascading stylesheets within the ComponentCopy node won't be honored.<ComponentCopy getReferenceId="GetComponentId">

<Stylesheet xslt="..\CopyTransform.xslt" />
<Stylesheet xslt="..\CopyTransform1.xslt" />
</ComponentCopy>

ElementDef

You must specifically designate each element that you want to be able to target as a cross-reference by assigning a value to the referenceAttribute attribute. See "Table 14‑1" for information on referenceAttribute.

Only elements that have been assigned a referenceAttribute value will be available for cross-referencing. For example, if your schema has a section element that may contain paragraph elements, and you define a referenceAttribute value to the section element definition but not the paragraphs, only the section will be available as a cross-reference target, and not the paragraphs within it.

An example is provided below.

<ElementDef name="subuli2" xmlname="li" friendly="Sub-Sub List Item" style="List Bullet 3" referenceAttribute="conref">
       <Section>
              <Para defaultHyperlink="xrefemph@format='html'">
                     <Emphasis>
                           <!-- Omitted for clarity -->
                     </Emphasis>
              </Para>
              <Choice minOccurs="0" maxOccurs="unbounded">
                     <SectionType name="lp"/>
                     <ReferenceType name="image"/>
                     <SectionType name="childTextNode"/>
              </Choice>
       </Section>
       <Attributes>
              <!-- Omitted for clarity -->
       </Attributes>
</ElementDef>

EmphasisDef

Cross references in Quark XML Author are represented to the user using a specialized emphasis definition. See Section 13.1.1 for information on building the specialized emphasis. Note that the <Custom> link type must be specified, and its assembly and class attributes must point to the external application that will handle the link behavior. In a DITA environment, the Invision.Xpress.CustomLink.DITA assembly shown in the example below can be used.

The external application must implement the ICustomLink interface. Details of this interface are beyond the scope of this document; if you need to implement a custom external application, please contact Quark for technical support.
<EmphasisDef name="xref" friendly="Cross Reference" xmlname="xref" excludeFromEmphasisCombo="true">
      <Specialized>
        <Link>
          <Multiple>
            <Custom substyle="dita" assembly="Quark.XA.EI.ReferenceResolver" class="XA.EI.ReferenceResolver.FileBasedReferenceResolver"/>
            <External substyle="html"/>
          </Multiple>
        </Link>
      </Specialized>
      <Style/>
      <SubStyles key="format">
        <SubStyle value="dita" friendly="Cross-Reference">
          <Style foreColor="Blue" underline="true"/>
        </SubStyle>
        <SubStyle value="html" friendly="Hyperlink">
          <Style foreColor="Blue" underline="true"/>
        </SubStyle>
     </SubStyles>
      <Attributes>
        <AttributeType name="href"/>
        <AttributeType name="format"/>
      </Attributes>
      <ExtensibilityMethods>
        <ExtensibilityMethod id="EditCrossReference" friendly=" - Edit"  showInContextMenu="true" enableXPath="self::*[local-name()='xref' and @referencetype='Text' and @*[local-name()='read-only']]"/>
        <ExtensibilityMethod id="UpdateReferences" friendly=" - Update"  showInContextMenu="true" enableXPath="self::*[local-name()='xref' and @synctargettext='true']"/><ExtensibilityMethod id="MakeCrossReferenceReadOnly" friendly=" - Mark Read-Only"  showInContextMenu="true" enableXPath="self::*[local-name()='xref' and @synctargettext='false' and not(@*[local-name()='read-only'])]"/>
      </ExtensibilityMethods>
      <Emphasis/>
    </EmphasisDef>

Configuring the Cross-reference dialog

Cross-references is a highly configurable feature. The potential cross-reference target can be configured in Quark.XA.EI.CrossReferences.dll.config. Items in the new non-modal cross-reference dialog drop-down lists can be customized. The length of the cross-references listed in the dialog can be also be defined. Authoring is now possible while the dialog is open.

Configuring dialog listings based on target element names (XMLNames) or XPath

References can be configured in the Cross-reference EI configuration to get desired reference types listed in the cross-reference dialog.

<b>Table: Configuration attribute values</b>

Parameter

Definition

Name

Attribute Values will be used as names for grouping elements under their value. For example "Configured Numbered List" will be shown in the Reference Typecombo box.

TargetElements

XML names of Elements defined in the XAS that need to be listed as reference types are to be added as comma separated values.

xpath

For advanced users, the XPath can be configured to list elements with certain properties.

AllowedProperties

This attribute contains values that are a part of the Insert Reference To field. The following properties are available in the drop-down list:

  • Paragraph number

  • Page number

  • Text

From these, Text is mandatory and will be part of the selection irrespective of the configuration definition.

Example

Listing all list items that do not have child elements as placeholders:

Specific xpaths can be mentioned for these cases as follows:

<ReferenceType Name ="Configured Numbered List"  TargetElements= "" xpath="/descendant::*[local-name()='oli' and not(descendant::*[local-name()='placeholder'])]" AllowedProperties="Paragraph number,Page number"/>

Note:

  1. In Case both XPath and targetElements are present, the precedence of XPath will be higher and the list will be populated on the basis of the XPath.

  2. Rules defined in the No Configuration case section will be equally applicable to the configured reference types.

Configuring dialog listing based on the name of target elements (XML Names) or XPath

In the Cross-reference EI config file (Quark.XA.EI.CrossReferences.dll.config), the References configuration can be built to get the desired types of references listed in the dialog. The tag ReferenceType is used to configure the desired reference types.

<ReferenceSection>
  <References>
    <ReferenceType Name ="Configured Numbered List" TargetElements= "oli, oli2, oli3, oli-feature" xpath="" AllowedProperties="Paragraph number, Page number,"/>
  </References>
</ReferenceSection>

or

<ReferenceSection>
  <References>
    <ReferenceType Name ="Configured Numbered List" TargetElements= "" xpath="="/descendant::*[local-name()='oli' and not(descendant::*[local-name()='placeholder'])]" " AllowedProperties="Paragraph number, Page number,"/>
  </References>
</ReferenceSection>

If no configuration is provided, all elements present in the XML Author document with the following properties will get listed, grouped by their friendly Element Definition names as specified in the XAS:

  1. referenceAttribute defined with the value conref in element def.

  2. ID or the UniqueIdentifier attribute is configured for the element in elementDef.

  3. The element should be configured as visible(which is default property of elementdef).

Insert Reference To will contain properties such as paragraph number, Page Number and Text by default in the No configuration mode.

<b>Configuring MaxLengthOfTextExtractedFromReference and HrefAttributeOfCrossReferenceNodeName</b>

Parameter

Definition

MaxLengthOfTextExtractedFromReference

This Attribute value signifies the maximum length of a string in Text reference property as shown in a caption text box or a list box. The value is the maximum number of characters allowed.

HrefAttributeOfCrossReferenceNodeName

This is a required attribute value to enable the cross-references functionality. Its value contains the name of the href attribute name of the xref element as used in the environment under consideration. For example, BUSDOCS uses xlink:href.