Quark XML Author 2015 October 2018 Update for Microsoft Word — System Admin Guide

Application Configuration: Extensibility Interface

Quark XML Author was designed to be extensible, so that it can be easily integrated with custom and third party (external) applications. Quark XML Author communicates with external applications via the Extensibility Interface (EI) section of the application and document configuration files. Functions that are document type specific are specified in the DocConfig file. Functions that may be invoked for all document types are specified in the application-level configuration file (AppConfig).

External applications typically are in the form of a Dynamic Link Library (DLL) or an EXE. A DLL contains a set of functions, each of which has its own parameters. EI is the mechanism by which these functions are called. EI must be told the details of “when” and “how” a function is called.

This chapter covers the Extensibility Interface from two major viewpoints: programming external methods for use with Quark XML Author, and configuring Quark XML Author to make use of those external methods.

Section 17 of this manual, “Integration with Content Management Systems”, discusses integrating Quark XML Author with Content Management Systems, and contains several examples of creating Extensibility Interface methods. In addition, chapter 18, “Configuring Smart Paste”, contains an EI method example.

Programming for Quark XML Author

Quark XML Author can be configured to call any external application that exposes public methods. The person configuring Quark XML Author simply needs to know the assembly, class, and method name and what parameters the method expects. For example, the following method requires that an XML node and an array of Delegates be passed to it:

public bool IsEditableElement(XmlNode node, Delegate[] delegates)
{
  try
  {
   //read all the delegates here.
   //The namespaces for all delegates are Quark.XA.ExtensibilityDelegates.
   IsEditableElement isEditableElementDelegate = delegates[0] as IsEditableElement;           
   if(isEditableElementDelegate != null && node != null && node is XmlElement)
   {
     // This delegate indicates whether a node is editable or not.
     // This is based on values associated to a proprietary
     // Invision attribute called inv:access where
     // xmlns:inv="urn:xpressauthor:xpressdocument".This attribute is usually
     // applied in another EI method. A typical example would be a document coming
     // from a CMS system with certain nodes
     // tagged as non-editable, On an open, this EI method would read the non-editable
     // tag from this document and add a Quark XML Author
     //tag (inv:access="read-only") identifying it as a readOnly chunk.
     return isEditableElementDelegate(node);
   }
  }
  catch(Exception e)
  {
   System.Diagnostics.Debug.WriteLine("IsEditableElement Exception :" + e.Message + "\nStackTrace:" + e.StackTrace);
  }
  return false;
}

As long as the assembly and class to which this method belongs are known, Quark XML Author can be configured to supply the XML node and any delegates that the method requires. The method would do its work and return a Boolean value to Quark XML Author to be acted upon.

Calling Quark XML Author from an External Method with Delegates

In addition to being able to call external methods, Quark XML Author exposes its own methods that can be called by external methods via delegates. Delegates are function pointers to Quark XML Author methods that can be passed on to external DLLs. The External DLLs may then call the methods to perform operations within the application. Custom methods can accept delegates by implementing the Delegate[] argument type.

Configuring the Extensibility Interface

Configuring Quark XML Author to use external methods is a matter of telling Quark XML Author how and when to call them. “How” is covered in Section 6.2.1, “Building the EI Method”. “When” is covered in Section 6.2.2, “Calling the EI Method”.

Building the EI Method

The ExtensibilityInterface node of both the AppConfig and DocConfig files contains the Method definitions that are used to call external applications. (It also can contain instructions about when to call them, which is covered in Section 6.2.2.1, “Calling the EI Method from a Document Event”). The ExtensibilityInterface node contains a MethodInfo child element. MethodInfo in turn contains one or more Method nodes. The attributes of Method identify the external application to be called. The child nodes of Method provide the parameter values to be passed to the external application, as shown below:

 
<ExtensibilityInterface>
 
  <MethodInfo>
 
    <Method
 
    <Method id="name for the EI method" assembly=" external application assembly name" class="external application class name" method=" external application method name">
 
      <!-- Any number of <Argument> nodes -->
 
    </Method>
 
  </MethodInfo>
 
</ExtensibilityInterface>
 

In the following subsections, we will explain the attributes and arguments and build an example EI method that calls the external method provided as an example in section 6.1.

Method Node Attributes

The attributes for the Method node define the .NET class library of the external process and how it is executed. Table 6‑1 defines these attributes, all of which are mandatory.

Table 6‑1: Method Attributes

Attribute

Definition

assembly

Specifies the file name of the .NET class library of the external process, without the .dll extension. For example, About.dll would be identified simply as About. A relative path to the assembly may be supplied if the assembly is placed in the root or a subdirectory of the Quark XML Author application folder.

class

Specifies the fully namespace-qualified class name within the .dll file (for example, Invision.Xpress.Extensible.MultiSelectPopup) being called for the external process.

id

Defines the name by which the method will be referenced.

method

Specifies the method executed when the class is called.

 

In the example below, we are calling a method named InvokeMethodIdTest. This is a method of MiscellaneousDelegates.Misc, which isprovided in the sample Visual Studio .NET project file.

 
<Method id="IsEditableEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="IsEditableElement">
 
<!-- Arguments to be added -->
 
</Method>
 

We have assigned the id value IsEditableEI to this EI method; whenever we invoke this method, the id value is used to reference it. The id value can be anything you want it to be provided that it is unique.

Method Node Arguments

Now that we’ve identified the external method to be called, we have to supply it with the parameter values it expects. Here is the signature for the method again:

public bool IsEditableElement(XmlNode node, Delegate[] delegates)

IsEditableElement expects to receive an XML node and at least one delegate. We will supply this data with a collection of Argument elements.

Enumerated Values

At its simplest, Argument is an empty element with one attribute: type. The value of type is an enumerated value that supplies information about the Quark XML Author document. For the example we’re working with, we need to supply an XML node to the external class. Quark XML Author has several enumerated values that supply XML fragments. The one we need to use here is XomCurrentNode, which provides the document node corresponding to the user’s current selection. We would add an Argument element to our method definition that names XomCurrentNode as the argument type, as shown in the example below:

 
<Method id="IsEditableEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="IsEditableElement">
 
  <Argument type="XomCurrentNode"/>
 
</Method>
 

A complete list of the Enumerated Value names that Quark XML Author makes available is provided in section 6.3, “List of Available Enumerated Values”.

Delegates

As mentioned previously, delegates are function pointers to Quark XML Author methods that can be passed on to external DLLs. The external method sample we are using expects to be passed a delegate that it can use to determine if the node it has been passed may be edited. We’ll supply this delegate with another Argument node.

In this case, the type attribute for the Argument node is set to Delegates, and Argument contains a collection of one or more Delegate nodes:

 
<Method id="IsEditableEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="IsEditableElement">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <!-- One or more <Delegate> nodes go here -->
 
  </Argument>
 
</Method>
 
The content of the Delegate node is the name of the delegate to be supplied. For this example, we will supply the IsEditableElement delegate, shown below:
 
<Method id="IsEditableEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="IsEditableElement">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>IsEditableElement</Delegate>
 
  </Argument>
 
</Method>
 

 

The method is complete.

A complete list of the delegates that Quark XML Author makes available, along with the signatures that must be used when calling them, is provided in section 6.4, “List of Available Delegates”.

Tokens

In some cases, neither enumerated values nor delegates will be adequate to supply the correct information to the external class. In these cases, you set the Argument type value to Tokens. With type set to Tokens, the Argument node must then contain one or more Token child nodes. The content of the Token node can be any data that needs to be supplied to the external application.

For example, consider the following external method, which belongs to the same assembly and class as the previous example:

 
public void AssignSingleAttributeTest(XmlNode xomNode, string[] tokens)
 
   {
 
     if(xomNode is XmlElement && tokens != null && tokens.Length > 0 && xomNode.Attributes.Count > 0)
 
     {
 
       XmlAttribute attr = xomNode.Attributes[tokens[0]];
 
       if(attr != null)
 
       {
 
              //Simply display the attribute value in the Console. This could be more complex like displaying
 
              //a custom form for choosing/changing an attribute value.
 
              Console.WriteLine("Attribute Name:" + attr.Name + " Value:" + attr.Value);
 
       }
 
     }
 
   }
 

This method requires an XML node and tokens to be supplied to it. The EI method would be constructed similarly to the one we constructed previously, but the second Argument node type would be set to Tokens:

 
<Method id="AssignSingleAttributeEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="AssignSingleAttributeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Tokens">
 
    <!-- Token elements go here -->
 
  </Argument>
 
</Method>
 

In this case, the external method is being used to get an attribute value from a custom Quark XML Author control, so we need to assign the attribute name as the content of a Token node:

 
<Method id="AssignSingleAttributeEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="AssignSingleAttributeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Tokens">
 
    <Token>inv:attr1</Token>
 
  </Argument>
 
</Method>
 

The content of Token can be any string value or an xml fragment required by the external application.

Tag

Tag is a special Argument type that supplies the label of an item selected in the user interface. It is typically used with EI methods that intercept an attempt to insert an element by the user. For example, if the following method was invoked when the user clicked an element with the label Section, the string Section would be passed to the external method:

 
<Method id="getImage" assembly="ImageHandler" class=" ImageHandler.InsertElementManager" method="GetImage">
 
  <Argument type="Tag"/>
 
</Method> 
 

Tag is used in the case study presented in Chapter 21.

Calling the EI Method

Once you have defined a method in the Extensibility Interface, it still won’t do anything unless it is invoked. EI methods may be invoked through a document event, through a Quark XML Author command (menu item, commandbar button, or shortcut key) defined in the application or document configuration files, or by an element, emphasis, or attribute definition in the Quark XML Author Structure

Calling the EI Method from a Document Event

Previously, we have discussed the MethodInfo node of the ExtensibilityInterface element in the configuration files. However, ExtensibilityInterface can also contain any number of nodes named for document events. These nodes allow you to specify EI methods to be called when document events are triggered.

To invoke an EI method from a document event, include an ExtensibilityMethod element as a child of the document event element. The ExtensibilityMethod element has one required attribute: id. The value of the id attribute is the name of an EI Method defined in the MethodInfo node.

For example, suppose we had defined a method that looks for document variables called header and footer in the Word document and sets them to a specified value:

 
<Method id="AssignDocVariableEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="AssignDocVariableTest">
 
  <Argument type="Tokens">
 
    <!-- the header and footer are doc variables defined in the dot file of the document. -->
 
    <-- In this simple example, the docVariables are set to a hardcoded value. -->
 
    <Token>header=This is the Header</Token>
 
    <Token>footer=This is the footer</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>AssignDocVariable</Delegate>
 
    <Delegate>RefreshDocVariables</Delegate>
 
  </Argument>
 
</Method>
 

Now suppose that we wanted to call this method whenever the document was saved. We would add the following node as a child of the ExtensibilityInterface element:

 
<Save>
 
  <ExtensibilityMethod id="AssignDocVariableEI"/>
 
</Save>
 

When the document is saved, the AssignDocVariableEI method would be invoked before the Save completes. A document event can contain an unlimited number of ExtensibilityMethod child elements, each of which would call a different EI method.

A complete list of available document events is provided in section 6.5,"List of available Document events".

Calling the EI Method from a Quark XML Author User Command

Menu items, commandbar buttons, and shortcut keys can all be configured to invoke EI methods. Section 4 of this manual discusses the use of the ExtensibilityMethod child element for each type of user interface component, but for ease of reference, those instructions are summarized here.

To invoke an EI method from a menu item, commandbar button, or a shortcut key combination, include an ExtensibilityMethod element as a child of the appropriate element in the configuration file. The ExtensibilityMethod element has one required attribute: id. The value of the id attribute is the name of an EI Method defined in the MethodInfo node. In each example below, an EI Method name SampleTableImport is invoked:

From a menu item:
 
<MenuItem resourceId="Table Import">
 
  <ExtensibilityMethod id="SampleTableImport"/>
 
</MenuItem>
 
From a commandbar button:
 
<CommandBarButton resourceId="Table Import">
 
  <ExtensibilityMethod id="SampleTableImport"/>
 
</CommandBarButton>
 
From a shortcut key:
 
<ShortcutKey Key="T" Shift="true" Ctrl="true">
 
  <ExtensibilityMethod id="SampleTableImport"/>
 
</ShortcutKey>
 

For more information on configuring menu items, commandbar buttons, and shortcut keys, see Chapter 4 of this manual.

Multiple EI Methods from a Single Command

You may call multiple EI methods from a single command by adding a separate ExtensibilityMethod node for each method you wish to call. Keep in mind, however, that if an EI method returns a value of false or throws an exception, any subsequent EI method calls will be cancelled.

Calling the EI Method from an Element or Emphasis Definition

With some elements or emphasis styles (which are simply in-line elements), 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. Element and Emphasis definitions may use Extensibility methods to provide this functionality.

To use EI methods with either an element definition or emphasis definition, add an ExtensibilityMethods child element to the definition. This node will contain one or more ExtensibilityMethod elements, one for each EI method to be called.

The syntax for using Extensibility Methods in these contexts is shown below:

 
<ExtensibilityMethods>
 
  <ExtensibilityMethod id="method name" friendly="friendly name" showInComponentContextMenu="true or false" showInContextMenu="true or false" faceID="#"/>
 
</ExtensibilityMethods>
 

Note that for element and emphasis definition, the ExtensibilityMethod element has more attributes available to it. They are defined in Table 6‑2.

Table 6‑2: ExtensibilityMethod Attributes

Attribute Name

Required

Definition

toggleXPath

no

Toggle the state of the ‘toggle button’ based on the xpath mentioned in the attribute.

enableXpath

no

Value is an XPath expression which evalutes to a node-set in which false is returned for an empty node-set and true otherwise. Used to toggle availability of menu items, commandbar buttons, and shortcut keys. If the value evaluates to false, the item is disabled, or enabled if the value evaluates to true.

Namespaces are not supported in the xpath syntax.

For the Ribbon, enableXpath 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. 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.

 

prependElementFriendly

No

Boolean. Defaults to true. When set to false, the element friendly name will not be appended before the extensibility method name.

 

See section 13 for information on how to define Emphasis and section 14 for information about how to define Elements.

Calling the EI Method from an Attribute Definition

With some document element attributes, you may want to provide a way for users to access a tool such as a metadata wizard. Attribute definitions may invoke an EI method to provide this functionality. Simply add the externalMethodId attribute to the AttributeDef element in the XAS file. The value of the attribute is the id of the EI method. An example is shown below:

 
<AttributeDef namespace="www.invisionresearch.com" prefix="inv" name="attr1" externalMethodId="AssignSingleAttributeEI" visible="true"/>
 
Calling the EI Method from an Element Definition

The ElementDef element has an externalMethodId attribute which can define an EI for inserting new elements. For such definitions, the insertable context menu displays a special icon to indicate that this is an EI insert. See “Table 14‑1” for information on this attribute

Using One EI Method to Call Another

You can also call EI methods from the external application. In the example below, the InvokeAnotherEI method passes the name of another EI method (JustAnotherEI) to the external method it calls:

 
<Method id="InvokeAnotherEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="InvokeMethodIdTest">
 
  <Argument type="Tokens">
 
    <Token>JustAnotherEI</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>InvokeMethodId</Delegate>
 
  </Argument>
 
</Method>
 
Here’s the second EI method:
 
<Method id="JustAnotherEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="InvokeeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>SelectNode</Delegate>
 
  </Argument>
 
</Method>
 

The first EI method invokes this external method:

 
   public void InvokeMethodIdTest(string[] tokens, Delegate[] delegates)
 
   {
 
     InvokeMethodId invokeMethodIdDelegate = delegates[0] as InvokeMethodId;
 
     if(invokeMethodIdDelegate != null && tokens.Length > 0 && tokens[0] != String.Empty)
 
     {
 
       //This delegate simply calls another EI method defined in the config files.
 
       //The name for the method comes from a token. In this case we are invoking the InvokeeTest EI method.
 
       invokeMethodIdDelegate(tokens[0]);
 
     }
 
   }
 

This method receives the token value JustAnotherEI and the InvokeMethodId delegate. It then uses InvokeMethodId to call the EI method named in the token, which is the second EI Method. That EI method invokes an entirely different external method:

 
   public void InvokeeTest(XmlNode currentNode, Delegate[] delegates)
 
   {
 
     SelectNode selectNodeDelegate = delegates[0] as SelectNode;
 
     if(selectNodeDelegate != null && currentNode != null)
 
     {
 
       selectNodeDelegate(currentNode);
 
     }
 
   }
 

And this method selects the node passed to it by the XomCurrentNode enumerated value.

You can daisy-chain any number of EI methods and external methods in this manner should you need to.

Use Cases

For additional use cases and examples see "Extensibility Interface Use Case Study".

List of Available Enumerated Values

The enumerated values defined in Table 6‑3 may be used as Extensibility Interface argument types. Several enumerated values refer to the XOM, which is explained following the table.

Table 6‑3: Enumerated Values

Enumerated Value

Type

Definition

AccessMode

string

The access mode for the current document. AccessMode is available in an (embedded) OLE Word Document. When an OLE Word Document is the active document, this is the access mode of the parent XML Author document that owns the OLE Word Document.

DeleteNodes

2-d array of DeleteNode-ParentNode pairs:

XmlNode[element,parent]

Special argument type that is only valid for an EI method specified under the BeforeComponentDelete and ComponentDelete events. It holds a list of elements that either will be deleted (when used with BeforeComponentDelete) or have been deleted (when used with ComponentDelete) and their parent nodes. For example, suppose you were to delete <Title/> and <Para/> from:

<Section>

  <Title/>

  <Para/>

</Section>

DeleteNodes would supply an array containing the following:

  • Title-Section

  • Para-Section

Note that when DeleteNodes is used as an argument for an EI method under BeforeComponentDelete, the first element in each pair is still part of the XOM.

When DeleteNodes is used with ComponentDelete, the first element in each pair is no longer part of the XOM.

DocNumber

Int

The repository document number for a checked out document. A new document will have a DocNumber of 0. Used by Xpress Server[1].

DocumentType

string

This argument may be assigned a value by the Xpress Server based on taxonomy (document classification) or catalog information. For example, this would allow a process to differentiate between ‘Document’ and ‘Template’ document types.

ExportedCurrentNode

XML Node

With this argument type, only the currently selected element is serialized. In other words, a new XmlNode is created that will contain element content, but will not have references to parent or child nodes.

ExportedCurrentNodeTree

XML Node

This argument has the same characteristics as ExportedCurrentNode, but also includes all descendent elements.

ExportedRoot

XML Node

Indicates a schema-valid XML document. This document contains element content and is fully de-referenced including CALS-standard tables. Because this argument type requires normalizing the Quark XML Author and Word object models, it may require processing time for larger documents.

Filename

string

Provides an EI method with the currently active document's full name, including paths.

PasteNode

XML Node

Special argument type used exclusively by any BeforePaste and InsertComponent EI methods. Contains the node being pasted (for any EI methods in BeforePaste event) or the node after it has been pasted (for any EI methods inside InsertComponent event).

Revision

int

The repository revision number for a checked out document. When a document is checked in, it will be assigned a Revision 1 greater than this value. A new document will have a Revision of 0. Used by Xpress Server.

StyleList

ArrayList of strings

Special argument type used exclusively by the BuildStyleList EI methods. Contains a list of currently insertable elements. Used to facilitate business rules that cannot be supported by configuration. For example, a business rule states that only one instance of a certain content element can exist in a given document.

ToggleState

boolean

Special argument type used exclusively for external method wired to a toggle menu item. Indicates the current state of the toggle button.

Pressed=true

Depressed=false)

UserName

string

The username of the individual authoring or revising the document as specified in the document header. As is the case with all Quark XML Author header information, it is populated by the Xpress Server (servlet).

WordUserName

string

The UserName property of the Word application.

XomCurrentNode

XML Node

The XOM node corresponding to the user’s current selection. If the current selection is on an empty style or it spans multiple paragraphs, XomCurrentNode will be null. See section 6.3.1, “XOM Defined” for a definition of XOM.

XOMCurrentNode is available in an (embedded) OLE Word Document. When an OLE Word Document is the active document, the XOM node corresponds to a node within the Psuedo XOM of the OLE Word Document.

XomRoot

XML Node

The XOM node corresponding to the current document root. See section 6.3.1, “XOM Defined” for a definition of XOM. XOMRoot is available in an (embedded) OLE Word Document. When an OLE Word Document is the active document, the XOM node corresponds to the root of the parent XML Author document that owns the OLE Word Document.

XomSelectedNodes

XML Node

The XOM nodes corresponding to the user's current selection when the selection spans multiple elements. Note that only nodes with a defined relationship to the external method are included. To define a relationship with the external method, the method must be referenced in the ElementDef's ExtensibilityMethods section. See Section 14.10 for more information about the ExtensiblityMethods section of ElementDef. See section 6.3.1, “XOM Defined” for a definition of XOM.

XomPreviousNode

XML Node

The XOM node corresponding to the previous visible node if selection is on an empty. Otherwise null. See section 6.3.1, “XOM Defined” for a definition of XOM.

StyleListParents

Arraylist of XML Node

A special argument type to be used exclusively by the BuildStyleList EI methods. This contains a list of parents of currently insertable elements provided by the styleList argument with a one–on–one linkage with stylelist items. This argument can help the EI developer to distinguish between insertables under different parents with the same name.

 

XOM Defined

XOM means Quark XML Author Object Model. It is the Quark XML Author XML DOM that is used to manage the structure of a document and its attributes. The XOM includes reference nodes and their de-referenced descendants. XOM contains only the document structure. It does not contain any element content. All element content is managed in the Microsoft Word Object Model. A custom process provided with an <Argument type="XomRoot"/> may traverse the current document’s structure, as well as browse and/or manipulate attribute values.

XOM and OLE Word Documents

XOMCurrentNode is available in an (embedded) OLE Word Document. XOMRoot is available in an (embedded) OLE Word Document.

See “Table 6‑3: Enumerated Values”.

List of Available Delegates

The available delegates and their signatures are defined below.

AssignDocVariable

public delegate void AssignDocVariable(string docVariableName, string docVarValue)

For the given document variable, supplies the string variable specified.

Configuration Example

 
<!-- This method looks for doc variables called "header" and "footer" in the Word document and sets them to a specific value-->
 
<Method id="AssignDocVariableEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="AssignDocVariableTest">
 
  <Argument type="Tokens">
 
    <!-- the header and footer are doc variables defined in the dot file of the document. -->
 
    <!-- In this simple example, the docVariables are set to a hardcoded value. -->
 
    <Token>header=This is the Header</Token>
 
    <Token>footer=This is the footer</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>AssignDocVariable</Delegate>
 
    <Delegate>RefreshDocVariables</Delegate>
 
  </Argument>
 
</Method>
 

AssignPostText

public delegate void AssignPostText(XmlNode visibleNode, string postTextString)

Assigns PostText portionmark values for a given visible node.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

 

AssignPreText

public delegate void AssignPreText(XmlNode visibleNode, string preTextString)

Assigns PreText portionmark values for a given visible node.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

 

AssignTextNode

public delegate void AssignTextNode(XmlNode visibleParaNode, string fragment, TriValue enableTrackChanges)

Replaces the content of the visibleParaNode with the contents of the fragment. Only the text portion of the node (and any emphasis applied to that text) is replaced. Any other child elements of the visibleParaNode are left intact. The value of enableTrackChanges indicates whether to record TrackChanges for the change. The possible values are Quark.XA.ExtensibilityDelegates.TriValue.False (do not record TrackChanges), Quark.XA.ExtensibilityDelegates.TriValue.True (record TrackChanges), and Quark.XA.ExtensibilityDelegates.TriValue.NoValue (the current value of TrackChanges for the document is used).

Configuration Example

 
<!-- AssignTextNode delegate test method definition -->
 
<!-- This method replaces the text in the XomCurrentNode with text from the location specified in the token-->
 
<Method id="AssignTextEI" assembly="XomManipulation" class="XomManipulation.XomDelegates" method="AssignTextNodeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Tokens">
 
    <!-- location of the text chunk which is being inserted -->
 
    <Token>c:\temp\AssignTextNodeTest.txt</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>AssignTextNode</Delegate>
 
  </Argument>
 
</Method>
 

 

 

Configuration Example

 
<Method id="UndoRecordingTest" assembly="UndoRecording" class="ExtensibilityInterface.Delegates.UndoRecording" method="UndoRecordingTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>AssignTextNode</Delegate>
 
    <Delegate>BeginUndoRecording</Delegate>
 
    <Delegate>EndUndoRecording</Delegate>
 
  </Argument>
 
</Method>
 

BeginUndoRecording

public delegate void BeginUndoRecording()

Begins recording undo objects.

Configuration Example

 
<Method id="UndoRecordingTest" assembly="UndoRecording" class="ExtensibilityInterface.Delegates.UndoRecording" method="UndoRecordingTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>AssignTextNode</Delegate>
 
    <Delegate>BeginUndoRecording</Delegate>
 
    <Delegate>EndUndoRecording</Delegate>
 
  </Argument>
 
</Method>
 

CreateContextMenu

public delegate void CreateContextMenu(XmlNode node, ContextMenuItem[] items);

Supplies the list of items to be placed in a context menu. Used typically for custom context menus in post-text and pre-text portionmark areas.

Configuration Example

 
<!-- EI Method tests CreateContextMenu - the EI will use the current xom node and build the context menu.  For this to work - assign a shortcut key to the ribbon button-->
 
<Method id="CreateContextMenuTest" assembly="CreateContextMenu" class="ExtensibilityInterface.Delegates.CreateContextMenuTest" method="TestCreateContextMenu">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Tokens">
 
    <Token>Corporate Governance</Token>
 
    <Token>Environment, Safety &amp; Health</Token>
 
    <Token>Facilities</Token>
 
    <Token>Finance</Token>
 
    <Token>Human Resources</Token>
 
    <Token>Information Management</Token>
 
    <Token>Integrated Safeguards &amp; Security</Token>
 
    <Token>Mission Execution</Token>
 
    <Token>Supply Chain Management</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>CreateContextMenu</Delegate>
 
  </Argument>
 
</Method>
 

DeleteNode

public delegate void DeleteNode(XmlNode nodeToBeDeleted, bool displayWarning = false);

Delete the node specified. This operation will also delete any schema-dependent nodes. For instance, if the node to be deleted is a required child of a parent as defined in the schema, the parent and all its other siblings will be deleted. Thus, the operation will fail if the final delete root happens to be the root of the document.

DeleteNode Parameters

Parameter

Required

Definition

nodeToBeDeleted

yes

XmlNode. The XOM Node to be Deleted.

displayWarning

no

Boolean. Displays a warning before the node is deleted. Defaults to false.

Configuration Example

 
<!-- DeleteNode delegate test method definition -->
 
<!-- This method tries to delete the incoming node -->
 
<Method id="DeleteEI" assembly="XomManipulation" class="XomManipulation.XomDelegates" method="DeleteNodeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>DeleteNode</Delegate>
 
  </Argument>
 
</Method>
 

 

EmphasisAction

public delegate void EmphasisAction(XmlNode node, string emphasisName, string subStyleKey, string subStyleValue)

Used to apply emphasis.

For more information, see InternalClass”EmphasisAction”.

The delegate is available for use in XML Author documents and embedded Word documents.

Configuration Example

 
<Method id="TestEmphasisAction" assembly="XOMCurrentTest" class="XOMCurrentTest.XOMTest" method="TestEmphasisAction">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>EmphasisAction</Delegate>
 
  </Argument>
 
  <Argument type="Tokens">
 
    <Token>emphasisName=example</Token>
 
    <!-- provide the name of an EmphasisDef that exists as child to the OLEWordDocument/ParaType/Emphasis -->
 
  </Argument>
 
</Method>
 

 

 

EndUndoRecording

public delegate void EndUndoRecording()

Ends registering undo objects and also registers a compound Undo for all operations that took place so that they can be undone with one Undo call.

Configuration Example

 
<Method id="UndoRecordingTest" assembly="UndoRecording" class="ExtensibilityInterface.Delegates.UndoRecording" method="UndoRecordingTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>AssignTextNode</Delegate>
 
    <Delegate>BeginUndoRecording</Delegate>
 
    <Delegate>EndUndoRecording</Delegate>
 
  </Argument>
 
</Method>
 

FormattingAction

public delegate bool FormattingAction(string formattingName, string colorValue)

Used to apply/remove character formatting, font color and highlight color on current selection.

For more information, see InternalClass”FormattingAction”.

The delegate is available for use in XML Author documents.

GetExportedNode

public delegate XmlNode GetExportedNode(XmlNode xomNode)

Returns the exported node for the specified XOM node.

Configuration Example

 
<!-- EI Method tests GetExportedNode, and GetExtensibldUserInterface - should display xml of current xom node in Word taskpane -->
 
<Method id="GetExtensibleUserInterfaceTest" assembly="ExtensibleUserInterface" class="ExtensibilityInterface.Delegates.ExtensibleUserInterface" method="GetExtensibleUserInterfaceTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>GetExportedNode</Delegate>
 
    <Delegate>GetExtensibleUserInterface</Delegate>
 
  </Argument>
 
</Method>
 

GetExtensibleUserInterface

public delegate IExtensibleUserInterface GetExtensibleUserInterface(ExtensibleUserInterfaceType type, UserControl control, string title, Guid guid = null, DockPosition dockPosition = DockPosition.dockPositionRight, bool createIfNotFound = true);

For a given custom UserControl, returns an object implementing the ITaskpane interface which provides the incoming control with a parent form. Available parameters provide support to show multiple custom task panes simultaneously, set default dock position and to get an Extensible User Interface (EUI) object that has already been created.

GetExtensibleUserInterface Parameters

Parameter

Required

Definition

type

yes

ExtensibleUserInterfaceType. Permissible values are Taskpane and Dialog.

control

yes

UserControl. The control to be added to the task pane.

title

yes

String. The title of ExtensibleUserInterfaceType.

guid

no

GUID. An EI can now specify a GUID to create a separate task pane. If no GUID is specified, the task pane will be created as a legacy task pane. Defaults to Null.

DockPosition

no

String. the default dock position can be specified when creating the task pane. Defaults to DockPosition.dockPositionRight.

createIfNotFound

no

Boolean. If true, it will create a new EUI if not already created. If false, it will get the already created EUI. Defaults to true.

 

Example :

GetExtensibleUserInterface(ExtensibleUserInterfaceType.Taskpane, taskPane, "Navigation Pane", guid, DockPosition.dockPositionLeft, true);

 

GetNextNode

public delegate XmlNode GetNextNode(XmlNode node)

Returns the next visible node in the document as an XML node. If provided node is null, returns the first visible node in the document.

Configuration Example

 
<!-- GetNextNode delegate test method definition -->
 
<Method id="GetNextNodeEI" assembly="Doc_Navigation_Selection" class="Doc_Navigation_Selection.Selection_Navigation" method="GetNextNodeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNextNode</Delegate>
 
    <Delegate>SelectNode</Delegate>
 
  </Argument>
 
</Method>
 

GetNodeProperties

public delegate void GetNodeProperties(XmlNode node, Hashtable ht)

Gets all properties defined for an attribute, element, or emphasis in the schema. Currently the following properties are supported: NodeType (NodeType identifies the type of incoming element-Element, Attribute or Emphasis), namespace, prefix, xmlname, friendly, style, defaultHyperlink, displayAttribute, displayElement, insertAfter, increaseIndent, decreaseIndent, excludeFromContextMenu, keyCode (only for NodeType=Element, contains keyCode - the actual value if it is visible or -1 if it is not),submenu, contextId, Unmanaged, UniqueIdentifier, externalMethodId, default, numbering, visible, readonly , datatype, format, attrGroupName, required, fixed, and contextFriendly. The contextFriendly property is the friendly name that is displayed in the context menu/style list.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

GetPageNumber

public delegate string GetPageNumber(XmlNode node)

Returns the page number for the start of the given XML node.

Configuration Example

 
<!-- EI Method tests GetPageNumber - should display pagenumber of current xom node in a MessageBox -->
 
<Method id="GetPageNumberTest" assembly="GetPageNumber" class="ExtensibilityInterface.Delegates.PageNumberTest" method="GetPageNumberTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>GetPageNumber</Delegate>
 
  </Argument>
 
</Method>
 

GetPostText

public delegate void GetPostText(XmlNode node, ref string prevPostTextValue)

Retrieves the value of a PostText portionmark for a given node and stores it in the incoming prevPostTextValue parameter.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

GetPreText

public delegate void GetPreText(XmlNode node, ref string prevPreTextValue)

Retrieves the value of a PreText portionmark for a given node and stores it in the incoming prevPreTextValue parameter.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

GetPreviousNode

public delegate XmlNode GetPreviousNode(XmlNode node)

Returns the previous visible node in the document as an XML node. If provided node is null, the last visible node is returned.

Configuration Example

 
<!-- GetPreviousNode delegate test method definition -->
 
<Method id="GetPreviousNodeEI" assembly="Doc_Navigation_Selection" class="Doc_Navigation_Selection.Selection_Navigation" method="GetPreviousNodeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetPreviousNode</Delegate>
 
    <Delegate>SelectNode</Delegate>
 
  </Argument>
 
</Method>
 

GetSectionMetadata

public delegate XmlElement GetSectionMetadata(XmlNode visibleNode, bool getWordML)

 

Returns the metadata for the Word Section to which the provided visible node belongs.

The visibleNode has to be a visible XOM node. The getWordML boolean flag indicates whether WordML for the header/footer node must also be returned.

The format of the node that is returned is shown below:

 

 
<WordSection orientation="portrait" breakType="sectionBreakNextPage">
 
  <!-- orientation = portrait|landscape breakType=sectionBreakNextPage| sectionBreakContinuous -->
 
  <Headers>
 
    <!-- max of 3 Header nodes one each of type primaryPageHeader, firstPageHeader and evenPageHeader are possible-->
 
    <Header type="primaryPageHeader">
 
      <Fields>
 
        <!-- Each field corresponds to Word's field - type is the field type, name is the field name, value is the value held by this feild -->
 
        <Field type="wdFieldPage" name="PAGE  \* MERGEFORMAT" value="2"/>
 
        <Field type="wdFieldNumPages" name="NUMPAGES  \* MERGEFORMAT" value="1"/>
 
        <Field type="wdFieldDocVariable" name="DOCVARIABLE  pf  \* MERGEFORMAT" value="pf Number"/>
 
      </Fields>
 
      <!-- This is the text in the header/footer range-->
 
      <Text>Range text content</Text>
 
      <!-- This is a WordML representation of header/footer content-->
 
      <WordML>WordML content</WordML>
 
    </Header>
 
  </Headers>
 
  <Footers>
 
    <!-- max of 3 Footer nodes one each of type primaryPageFooter, firstPageFooter and evenPageFooter are possible-->
 
    <Footer type="primaryPageFooter">
 
      <Fields>
 
        <Field type="wdFieldDocVariable" name="xxx" value="yyy"/>
 
      </Fields>
 
      <Text> Range text content</Text>
 
      <WordML>WordML Content</WordML>
 
    </Footer>
 
  </Footers>
 
</WordSection>
 

If the getWordML flag is false, the WordML nodes in bold above are absent. This is done because retrieving WordML from headers and footers is a potentially expensive operation and should only be done when it is required to parse any header/footer content that is not in the <Text> node or the <Fields> node.

GetToggleButtonState

public delegate bool GetToggleButtonState(string externalMethodId)

Returns the state (true or false) of the toggle button specified by the given external method ID.

Configuration Example

 
<Method id="GetToggleButtonState" assembly="GetToggleButtonState" class="ExtensibilityInterface.Delegates.ToggleButtonStateTest" method="GetToggleButtonStateTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>SelectNode</Delegate>
 
    <Delegate>GetToggleButtonState</Delegate>
 
  </Argument>
 
</Method>
 

GetXmlResolver

public delegate IXmlResolverProvider GetXmlResolver();

GetXmlResolver is used to return the current instance of the IXmlResolverProvider class used by Quark XML Author – it could be the default one used by Quark XML Author or an external one provided by the SetXmlResolver delegate.

Information about creating and using custom resolvers can be found in Section 0.

Configuration Example

 
<!-- EI Method tests GetXmlResolver - if provider is successfully obtained message box will indicate that -->
 
<Method id="GetXmlResolverTest" assembly="GetXmlResolver" class="ExtensibilityInterface.Delegates.TestXmlResolver" method="GetXmlResolverTest">
 
  <Argument type="Delegates">
 
    <Delegate>GetXmlResolver</Delegate>
 
  </Argument>
 
</Method>
 

GetXomNode

public delegate XmlNode GetXomNode(XmlNode exportedNode)

Returns the XOM node for the specified exported node.

An external process manipulates a document by modifying the XOM. This delegate is used to create the XOM that represents the exportedNode.

Do not use the document’s CurrentExportedNode as the input parameter. Instead, you must use a node within the document’s ExportedRoot.

A use case of GetXOMNode is to calculate the CRC for the exportedNode , GetXOMNode of the exportedNode and then store that CRC in the XOM.

Configuration Example

 
<!-- EI Method tests GetXomNode - should display xml of xom node that corresponds to the first 'p' element of the exported root node in a MessageBox -->
 
<Method id="GetXomNodeTest" assembly="GetXomNode" class="ExtensibilityInterface.Delegates.XomNodeTest" method="GetXomNodeTest">
 
  <Argument type="ExportedRoot" />
 
  <Argument type="Delegates">
 
    <Delegate>GetXomNode</Delegate>
 
  </Argument>
 
</Method>
 

InsertEmphasis

public delegate void InsertEmphasis(XmlNode emphasisFragmentNode, bool overwriteSelectedContent = false);

Inserts an emphasized text node into the specified XML node at the cursor position. The selected content may or may not be replaced based on the value of overwriteSelectedContent. An optional parameter with the default value false has been introduced in the InsertEmphasis delegate. If the value of this parameter is set to true,  it will replace the selected content on canvas.

For more information, see InternalClass”Insert Emphasis”.

The delegate is available for use in XML Author documents and embedded Word documents.

InsertEmphasis Parameters

Parameter

Required

Definition

emphasisFragmentNode

yes

XmlNode. The fragment node of emphasis that needs to inserted at current selection.

overwriteSelectedContent

no

Boolean. If true, it will insert an emphasis over the selection and will overwrite the selected content. Defaults to false.

Configuration Example

 
<!-- InsertEmphasis delegate test method definition -->
 
<!-- This method tries to insert the emphasis XML fragment at the current selection -->
 
<Method id="InsertEmphasisEI" assembly="XomManipulation" class="XomManipulation.XomDelegates" method="InsertEmphasisTest">
 
  <Argument type="Tokens">
 
    <!--location of the XML emphasis chunk which is being inserted-->
 
    <Token>c:\temp\AssignTextNodeTest.txt</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>InsertEmphasis</Delegate>
 
  </Argument>
 
</Method>
 
Configuration Example
 
<Method id="TestInsertEmphasis" assembly="XOMCurrentTest" class="XOMCurrentTest.XOMTest" method="TestInsertEmphasis">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>InsertEmphasis</Delegate>
 
  </Argument>
 
  <Argument type="Tokens">
 
    <Token>emphasisName=cite</Token>
 
    <!-- provide the name of an EmphasisDef that exists as child to the OLEWordDocument/ParaType/Emphasis -->
 
  </Argument>
 
</Method>
 

 

InsertNode

public delegate bool InsertNode(XmlNode visibleXomNode, XmlNode fragmentNode, string elementDisplayName, bool preserveID = false, bool showErrorMsg = true);

Insert a new node immediately underneath the visibleXomNode specified. The new node and the entire subtree underneath must be schema compliant and insertable immediately under the visibleXomNode.

The third parameter, the element display name, needs to be populated only when there are multiple contexts for the node being inserted. The elementDisplayName helps to identify the element which the EI method intends to insert from a list of possible insertables. In all other cases it can be null. If this property is null and there are multiple insertables possible at the insertable point, the first one in the list will be inserted.

InsertNode Parameters

Parameter

Required

Definition

visibleXomNode

yes

XmlNode. The node under which the fragmentNode will be inserted.

fragmentNode

Yes

XmlNode. The fragment node to be inserted.

elementDisplayName

Yes

String. The friendly name of the element to be inserted.

preserveID

Yes

Boolean. Preserves the ID of the inserted fragment node. Defaults to false.

showErrorMsg

no

Boolean. Executes InsertNode in silent mode so that no message or warning is displayed in case insertion fails. Defaults to true.

 

Configuration Example

 
<!-- InsertNode delegate test method definition -->
 
<!-- This method tries to insert an XML fragment pointed to by the Token argument just below the location specified by the XomCurrentNode-->
 
<Method id="InsertEI" assembly="XomManipulation" class="XomManipulation.XomDelegates" method="InsertNodeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Tokens">
 
    <!-- location of the xml chunk which is being inserted -->
 
    <Token>c:\temp\InsertNodeTest.txt</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>InsertNode</Delegate>
 
  </Argument>
 
</Method>
 

InvokeInternalClass

public delegate void InvokeInternalClass(string internalClassName, Hashtable parameters)

Invokes an InternalClass from an extensibility method. This delegate is similar to the InvokeMethodId delegate except that an InternalClass method is being invoked instead of an extensibility method. Parameters required by the InternalClass must be specified in the parameters argument as a Hash table of name-value pairs.

Configuration Example

 
<!-- EI Method tests InvokeInternalClass - the EI will use the delegate to invoke "DocumentClose"-->
 
<Method id="InvokeInternalClassTest" assembly="InvokeInternalClass" class="ExtensibilityInterface.Delegates.TestInvokeInternalClass" method="InvokeInternalClassTest">
 
  <Argument type="Delegates">
 
    <Delegate>InvokeInternalClass</Delegate>
 
  </Argument>
 
</Method>
 

InvokeMethodId

public delegate object InvokeMethodId(string eiMethodName, XmlNode node = null);

Invokes an Extensibility Interfaces method in the DocConfig file that matches the Extensibility Interface method name passed on specified XOM Node else if unspecified, on XomCurrentNode. Hence by default this passes the same XomCurrentNode and ExportedCurrentNode values that were passed to its parent method (the one calling InvokeMethodId) and if not, then the corresponding values of specified XOM node. This passes the return value of the invoked method (if any) back to the caller.

ToggleVisibleElement Parameters

Parameter

Required

Definition

node

no

Node. This is an optional Xom Node parameter that can be specified by calling the EI, if the eiMethodName needs to be invoked on a specific XOM node (other than current xom node). If unspecified, it will be invoked on CurrentXomNode.

eiMethodName

yes

String.

Configuration Example

 
<!-- InvokeMethodId delegate test definition -->
 
<!-- This method invokes another EI method called JustAnotherEI -->
 
<Method id="InvokeAnotherEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="InvokeMethodIdTest">
 
  <Argument type="Tokens">
 
    <Token>JustAnotherEI</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>InvokeMethodId</Delegate>
 
  </Argument>
 
</Method>
 

IsEditableElement

public delegate bool IsEditableElement(XmlNode node)

Returns true if the specified node is editable, otherwise it returns false. The node is not editable and IsEditableElement returns false if:

  • inv:access is not present

  • or inv:access = read-only

  • or inv:access = external

  • or qxa:read-only = true

Determination is based on values associated to a proprietary attribute called inv:access where xmlns:inv="urn:xpressauthor:xpressdocument". The inv:access attribute has two possible values: “read-only” and “external”. The external is set (by Quark XML Author) for externally referenced elements such as referenced images or DITA conrefs. The read-only is not set by Quark XML Author but Quark XML Author will look at any read-only value set (say by an external method) to disable any UI changes to it.

Similar to inv:access, is the proprietary attribute qxa:read-only where xmlns:qxa="urn:schemas-quark-com:xmlauthor". The difference between the two is that qxa:read-only is persisted with the document when it is saved. The qxa:read-only attribute has two possible values: “true” and “false”.

At the element-level, these read-only attributes are used to prevent the editing of an element.

Referenced or embedded images are still resizable, regardless of the reference implementation being used unless qxa:read-only is set to true.

 

Configuration Example

 
<!-- IsEditableElement delegate test method definition -->
 
<!-- This method returns whether the incoming node is editable or not. In this example the EI method is returning an boolean back to Xpress.
 
A boolean false returned by any EI method implies a failure which is interpreted by Xpress to signify halting of any further activities scheduled to
 
be executed under the same command(menu item/toolbar click or a document event trigger). For ex: for the DocumentSave event we might have a
 
Ei method which checks for certain problems with the document. If this EI method returns a false, the save operation is halted and the user is notified of the failure.-->
 
<Method id="IsEditableEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="IsEditableElement">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>IsEditableElement</Delegate>
 
  </Argument>
 
</Method>
 

RefreshDocVariable

public delegate void RefreshDocVariable(XmlNode nodeToBeUpdated);

Method which will update the portion mark for a given node.

Configuration Example

 
<!-- PreText delegates test method definition -->
 
<!-- This method assigns a randomly generated string to the PreText area of a visible node-->
 
<Method id="PreTextEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="PreTextPostTextTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>GetNodeProperties</Delegate>
 
    <Delegate>GetPreText</Delegate>
 
    <Delegate>AssignPreText</Delegate>
 
    <Delegate>GetPostText</Delegate>
 
    <Delegate>AssignPostText</Delegate>
 
    <Delegate>RefreshDocVariable</Delegate>
 
  </Argument>
 
</Method>
 

RefreshDocVariables

public delegate void RefreshDocVariables();

Method which will update the portion marks on screen.

Configuration Example

 
<!-- This method looks for doc variables called "header" and "footer" in the Word document and sets them to a specific value-->
 
<Method id="AssignDocVariableEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="AssignDocVariableTest">
 
  <Argument type="Tokens">
 
    <!-- the header and footer are doc variables defined in the dot file of the document. -->
 
    <!-- In this simple example, the docVariables are set to a hardcoded value. -->
 
    <Token>header=This is the Header</Token>
 
    <Token>footer=This is the footer</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>AssignDocVariable</Delegate>
 
    <Delegate>RefreshDocVariables</Delegate>
 
  </Argument>
 
</Method>
 

RemoveContentItem

public delegate void RemoveContentItem(XmlNode node)

This delegate applies to embedded Word documents only. Used to delete the specified XML node in the Pseudo XOM and its associated Word Content Control in an embedded Word document

Configuration Example

 
<Method id="TestRemoveContentItem" assembly="XOMCurrentTest"    class="XOMCurrentTest.XOMTest" method="TestRemoveContentItem">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>RemoveContentItem</Delegate>
 
  </Argument>
 
</Method>
 

AllowToggleTrackChange

public delegate void AllowToggleTrackChange(bool allowToggleTrackChange)

This delegate sets whether the Track Changes Toggle is enabled or disabled.

Configuration Example

 
<Method id="SetReviewOptionsEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="SetReviewOptions">
 
  <Argument type="Delegates">
 
    <Delegate> AllowToggleTrackChange </Delegate>
 
  </Argument>
 
</Method>
 

AllowAcceptRejectChange

public delegate void AllowAcceptRejectChange (XmlNode node)

This delegate sets Sets whether the Accept/Reject Changes option is enabled or disabled according to configuration.

Configuration Example

 
<Method id="SetReviewOptionsEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="SetReviewOptions">
 
  <Argument type="Delegates">
 
    <Delegate> AllowAcceptRejectChange </Delegate>
 
  </Argument>
 
</Method>
 

SetWordUserName

public delegate void SetWordUserName (string userName, string userInitials)

This delegate is used to set the Username and Initials for the current Word session.

LockActiveDocument

 
public delegate LockOperationResult LockActiveDocument()
 
This delegate specifies locking the current XML Author document as the Active document of Word. The locked document will be considered as the active document for XA processing even if other documents are in focus.This delegate returns the LockOperationResult back to caller
 
Configuration Example
 
<Method id="LockingTest" assembly="LockUnlock" class="ExtensibilityInterface.Delegates.LockUnlock " method="LockingTest">
 
  <Argument type="Delegates">
 
    <Delegate>LockActiveDocument </Delegate>
 
  </Argument>
 
</Method>
 

UnlockActiveDocument

public delegate UnlockOperationResult UnlockActiveDocument()

This delegate specifies the unlocking of the locked XML Author document as the active word document and this unlocked document will no longer be considered as an active document when not in focus.This delegate returns the UnlockOperationResult back to caller .

Configuration Example

 
<Method id="Unlocking rest" assembly="LockUnlock" class="ExtensibilityInterface.Delegates.LockUnlock " method="UnlockingTest">
 
  <Argument type="Delegates">
 
    <Delegate>UnlockActiveDocument </Delegate>
 
  </Argument>
 
</Method>
 

GetComponentReferenceLink

public delegate XmlNode GetComponentReferenceLink (XmlNode xmlNode, bool AllowComponentTargets = false)

This delegate returns the link emphasis node for a component.

 

ResolveReference

public delegate ITarget ResolveReference (XmlNode xmlNode)

This delegate returns the component being referred to by the link emphasis node

 

GetCurrentNode

public delegate XmlNode GetCurrentNode()

This delegate returns the current visible node in the document as an XML node.

Configuration Example

 
<Method id="TestEI" assembly="XOMManipulation" class="ExtensibilityInterface.Delegates.XOM" method="CurrentNode">
 
  <Argument type="Delegates">
 
    <Delegate>GetCurrentNode</Delegate>
 
  </Argument>
 
</Method>
 

ReplaceNode

public delegate bool ReplaceNode(ReplaceMap[] replacePairs)

Used to replace one document node with another. (Does not support replacing emphasis nodes.) ReplaceMap is a class in the Invision.XpressExtensibilityDelegates namespace containing three properties. These properties indicate the nodes to be replaced, the node to use as the replacement, and the replacement strategy to use. Each property is explained below.

public System.Xml.XmlNode OriginalXomNode;

The XomNode to be replaced.

public System.Xml.XmlNode ReplaceNode;

The new node to replace OriginalXomNode with.

public ReplaceStrategy StrategyToUse = ReplaceStrategy.Dynamic|ReplaceStrategy.Redraw;

Specifies the replace strategy to use. ReplaceStrategy.Dynamic allows Quark XML Author to make the decision whether to restyle or use delete-insert. ReplaceStrategy.Redraw specifically uses the delete and insert strategy.

This delegate was created to support changing list styles. Each list type/style has a different XAS element definition, therefore, changing the list style requires altering the document’s element structure. In this scenario, there is no change in the number of visible elements. When the number of visible elements being replaced is the same as those replacing them AND the corresponding textnodes and emphasis are unchanged, the ReplaceStrategy flag allows the XOM fragment to be replaced while on the Word canvas, the narrative content is merely re-styled. This avoids the unpleasant, and unnecessary deleting and re-inserting of content on-screen.

Configuration Example

 
<!-- EI Method tests ReplaceNode - the EI will use the current xom node to replace the previous xom node-->
 
<Method id="ReplaceNodeTest" assembly="ReplaceNode" class="ExtensibilityInterface.Delegates.ReplaceNodeTest" method="TestReplaceNode">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>ReplaceNode</Delegate>
 
    <Delegate>GetPreviousNode</Delegate>
 
  </Argument>
 
</Method>
 

SelectNode

public delegate void SelectNode(XmlNode visibleNode)

Passing null value as argument to  SelectNode will collapse selection to end of currently selected node.

Configuration Example

 
<!-- This EI method is called by the InvokeAnotherEI EI method through the InvokeMethodId delegate-->
 
<Method id="JustAnotherEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="InvokeeTest">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>SelectNode</Delegate>
 
  </Argument>
 

</Method>

SelectNodes

public delegate void SelectNodes(XmlNode startVisibleNode, XmlNode endVisibleNode);

Selects all content between and including the two endpoint nodes.

Configuration Example

 
<!-- EI Method tests SelectNode should select current XML Author node and previous XML Author node -->
 
<Method id="SelectNodesTest" assembly="SelectNodes" class="ExtensibilityInterface.Delegates.TestSelectNodes" method="SelectNodesTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Delegates">
 
    <Delegate>GetPreviousNode</Delegate>
 
    <Delegate>SelectNodes</Delegate>
 
  </Argument>
 
</Method>
 

SetSavedState

public delegate void SetSavedState(bool bSaved);

Called by an EI method to set the saved state of the document. Quark adapters use EI methods to manage document persistence. This delegate is used to ensure that the state of the document is accurate. This state is evaluated at various times such as when the user attempts to close the document. In this case, if the document state is “not saved” then the user should be prompted to save.

Configuration Example

 
<Method id="SetDocumentSaved" assembly=" assemblyName" class="Class" method="SetDocumentSaved">
 
  <Argument type="Delegates">
 
    <Delegate>SetSavedState</Delegate>
 
  </Argument>
 
</Method>
 

SetXmlResolver

public delegate void SetXmlResolver(IXmlResolverProvider provider);

Called by an EI method to set a custom XmlResolver instance. Typically, this EI method is called from within the Connect event in AppConfig.xml.

By default, if SetXmlResolver is not used and the document contains a URL declaration (DTD or Schema), Quark XML Author attempts to connect to the resource. If the resource is reachable, the XmlResolver property is set to XmlUrlResolver, the native XmlResolver for Quark XML Author. If the resource cannot be reached, the XmlResolver property is set to null.

SetXmlResolver is used when a custom resolver is needed. The custom resolver must implement the IXmlResolverProvider interface. Information about creating and using custom resolvers can be found in Section 0.

Configuration Example

 
<!-- EI Method tests SetXmlResolver - if resolver is successfully set message box will indicate that, and you can open DITA files that contain doctype definitions -->
 
<Method id="SetXmlResolverTest" assembly="SetXmlResolver" class="ExtensibilityInterface.Delegates.TestXmlResolver" method="SetXmlResolverTest">
 
  <Argument type="Delegates">
 
    <Delegate>SetXmlResolver</Delegate>
 
  </Argument>
 
</Method>
 

ShadeRegion

public delegate void ShadeRegion(XmlNode[] nodes, System.Drawing.Color backColor, bool recurse)

Shades an array of nodes with the supplied background shading. The shading will be performed for all visible nodes in the collection. This includes block elements, inline images and equations, but does not include emphasis. The recurse parameter specifies whether the procedure should recursively perform this operation on all descendants of the node collection.

Configuration Example

 
<!-- EI Method tests ShadeRegion - should select current XML Author node and children depending on token -->
 
<Method id="ShadeRegionTest" assembly="ShadeRegion" class="ExtensibilityInterface.Delegates.TestShadeRegion" method="ShadeRegionTest">
 
  <Argument type="XomCurrentNode" />
 
  <Argument type="Tokens">
 
    <Token>true</Token>
 
  </Argument>
 
  <Argument type="Delegates">
 
    <Delegate>ShadeRegion</Delegate>
 
  </Argument>
 
</Method>
 

ToggleEditableRegion

public delegate void ToggleEditableRegion(XmlNode[] nodes, bool booleanValueToBeSet, bool recurse)

Toggles the editable status of the specified XML node or nodes.

Configuration Example

 
<!-- ToggleEditableRegion test delegate definition -->
 
<!-- This particular method will take the current selection and make it non-editable. -->
 
<Method id="NonEditableRegionEI" assembly="UIManipulation" class="UIManipulation.UIDelegates" method="ToggleRegionEditablePropertyTest">
 
  <!-- The XomSelectedNodes provides an array of VISIBLE nodes selected by user -->
 
  <Argument type="XomSelectedNodes"/>
 
  <Argument type="Delegates">
 
    <Delegate>ToggleEditableRegion</Delegate>
 
  </Argument>
 
</Method>
 

UpdateAttributes

public delegate void UpdateAttributes()

Calls the Update Attributes event handler for an external attribute panel.

Configuration Example

 
<!-- UpdateAttributes delegate test method definition -->
 
<Method id="AttributePanelEI" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="ShowElementAttributes">
 
  <Argument type="XomCurrentNode"/>
 
  <Argument type="Delegates">
 
    <Delegate>UpdateAttributes</Delegate>
 
  </Argument>
 
</Method>
 

 

AssignRefVariable

public delegate void AssignRefVariable(string docVariableName, string docVariableValue, string fileName = null);

Assigns the named Reference Variable. Reference Variables can help resolve indirect references. See Variable Reference Support.

AssignRefVariable Parameters

Parameter

Required

Definition

docVariableName

yes

String. Name of the document variable.

docVariableValue

yes

String. Value of the document variable. This value should be direct reference value.

fileName

no

String. The document's full name, including path. Defaults to null for the current document.

 

GetRefVariable

public delegate string GetRefVariable(string docVariableName, string fileName = null);

Returns the named Reference Variable for the Quark XML Author document. See Variable Reference Support.

GetRefVariable Parameters

Parameter

Required

Definition

docVariableName

yes

String. Name of the document variable.

fileName

no

String. The document's full name, including path. Defaults to null for the current document.

 

GetAllRefVariables

public delegate int GetAllRefVariables(string[,] refVars, string fileName = null);

Gets all the References Variables or their count for the Quark XML Author document. See Variable Reference Support.

GetAllRefVariables Parameters

Parameter

Required

Definition

refVars

yes

Array. An array to get all the reference variables and their values. Can be null to determine the number of variables.

fileName

no

String. The document's full name, including path. Defaults to null for the current document.

 

GetExportedXMLForRefVariables

public delegate string GetExportedXMLForRefVariables(string fileName = null);

 

Returns  the serialized xml for the reference variables. The serialized xml can bepersisted by a custom component in BeforeSave Event.

 

Reference Variables can help resolve indirect references. See Variable Reference Support.

GetExportedXMLForRefVariables Parameters

Parameter

Required

Definition

filename

No

String. The document's full name, including path. Defaults to null for the current document.

 

ResolveReference

public delegate ITarget ResolveReference(XmlNode xmlNode);

Resolves references for the LinkEmphasis node. Returns the resolved target.

ResolveReference Parameters

Parameter

Required

Definition

xmlNode

yes

String. Returns the XmlNode of type LinkEmphasis for example "Xref".

Configuration Example

 
<!-- ResolveReference delegate test method definition -->
 
<Method id="ResolveReferenceTest" assembly=" ResolveReferenceTest " class=" ResolveReferenceTest.Example"
 
method="TestResolveNode">
 
<Argument type="Delegates">
 
<Argument type="XomCurrentNode"/>
 
 <Delegate> ResolveReference </Delegate>
 
</Argument>
 
</Method>
 

 

EI method Example

This method will resolve link emphasis and the messageBox will display both the URL path and the element xpath if the current selected node is of type link emphasis.

 
Public void TestResolveNode(XmlNode currentXomNode, Delegates[] delegates)
 
{
 
   ResolveReference resolveRefdelegate = delegates[0] as ResolveReference;
 
   ITarget target = resolveRefdelegate(currentXomNode);
 
   MessageBox.Show( target.TargetLocation  +"  "+  target. TargetElementXPath );
 
}
 

 

GetInsertableElements

ArrayList GetInsertableElements(XmlNode visibleXomNode);

A Delegate that returns a list of Insertables (captionName) for the provided visibleXomNode.

GetInsertableElements Parameters

Parameter

Required

Definition

visibleXomNode

yes

XmlNode. Returns the visible XomNode whose Insertables are required.

Configuration Example

 
<!-- GetInsertableElements delegate test method definition -->
 
<Method id=" GetInsertableElementsTest" assembly=" GetInsertableElementsTest " class=" GetInsertableElementsTest.Example"
 
method="TestGetInsertableElements">
 
<Argument type="XomCurrentNode"/>
 
<Argument type="Delegates">
 
 <Delegate> GetInsertableElements</Delegate>
 
</Argument>
 
</Method>
 

 

EI method Example

This method will return a list of insertables and the messageBox will display all insertables allowed at the current selection location.

 

 
Public void TestGetInsertableElements (XmlNode currentXomNode, Delegates[] delegates)
 
{
 
   GetInsertableElements getInsertableElementsDelegate = delegates[0] as GetInsertableElements;
 
   ArrayList insertables = getInsertableElementsDelegate (currentXomNode);
 
   stringBuilder sb = new StringBuilder();
 
    foreach(string insertable in insertables)
 
   {
 
     Sb.Append(insertables + " ");
 
   }
 
   MessageBox.Show( sb.ToString() );
 
}
 

 

GetNodeDefProperties

public delegate void GetNodeDefProperties(string XomName, string parentXomName, Hashtable ht);

This method is used to get all the properties defined for an element in the schema. Currently the following properties are supported:

  • Xmlname

  • Friendly

  • Style

  • defaultHyperlink

  • displayAttribute

  • insertAfter

  • increaseIndent

  • decreaseIndent

  • externalMethodId

  • default

  • numbering

  • visible

  • readonly

For getting the properties of the EmphasisNode, the parentXomName is not required.

GetNodeDefProperties Parameters

Parameter

Required

Definition

XomName

yes

String. The XomName whose properties are required.

parentXomName

Yes

String. The possible parent Xom Name for which the node properties are required.

ht

Yes

Hashtable. A hashtable to fill the required properties.

 

Configuration Example

 
<!-- GetNodeDefProperties delegate test method definition -->
 
<Method id=" GetNodeDefPropertiesTest" assembly=" GetNodeDefPropertiesTest " class=" GetNodeDefPropertiesTest.Example"
 
method="TestGetNodeDefProperties">
 
<Argument type="XomCurrentNode"/>
 
<Argument type="Delegates">
 
 <Delegate>GetNodeDefProperties </Delegate>
 
</Argument>
 
</Method>
 

 

EI method Example

This method will populate hashtable with node def properties of current selected Node, the message box will show the total number of properties retrieved.

 
Public void TestGetNodeDefProperties (XmlNode currentXomNode, Delegates[] delegates)
 
{
 
   GetNodeDefProperties getNodeDefPropertiesDelegate = delegates[0] as GetNodeDefProperties;
 
   Hashtable ht = new Hashtable();
 
   getNodeDefPropertiesDelegate (currentXomNode.LocalName ,                   currentXomNode.ParentNode.LocalName,ht);
 
MessageBox.Show("Total Number of properties retrieve is : " ht.Count);
 
  
 
}
 

GetNodeDirtyType

Public delegate DirtyType GetNodeDirtyType (xmlNode xomNode, List<string> xmlAttribList)

This delegate returns the dirty type of xomNode. This delegate can be used to identify which of the nodes in the document are actually dirty and the level of dirtiness. If a node is dirty due to kAttribute, then xmlAttribList will contain the list of xml attribute names due to which nodes becomes dirty.

Level of dirtiness (highest to lowest):

  1. kNew, kRemove

  2. kModified

  3. kAttribute

Public enum DirtyType
{
   kNone,
  kModified,
  kNew,
  kRemoved,
  kAttribute
}

Configuration example:

 
<!-- GetNodeDirtyType delegate test method definition -->
 
  <Method id="GetNodeDirtyTypeEI" assembly="XXXXX " class="XXXXX"
 
    method="GetNodeDirtyTypeTest">
 
      <Argument type="XomCurrentNode"/>
 
      <Argument type="Delegates">
 
        <Delegate> GetNodeDirtyType </Delegate>
 
      </Argument>
 
  </Method>
 

SetReferenceAttributes

Public delegate bool SetReferenceAttributes (xmlNode xomNode, Hashtable referenceAttributes);

This delegate is used to add passed direct and indirect reference attribute value in XOMNode, where allowed. It also handles shading for the same.

Returns true if added, false otherwise.

SetReferenceAttributes Parameters

Parameter

Required

Definition

xomNode

yes

XmlNode. The XOMNode to set the reference attribute to.

referenceAttributes

yes

Hashtable. A Hashtable with reference keys and corresponding values. The only valid keys are “DirectReference” and “IndirectReference”.

 

Configuration example:

 
<Method id=”setReferenceAttributesTest”
 
  assembly=”MiscellaneousDelegates”
 
  class=”MiscellaneousDelegates.Misc” method=”SetReferenceAttributesTest”>
 
    <Argument type=”XomCurrentNode”/>
 
    Argument type=”Delegates”>
 
      <Delegate>SetReferenceAttributes</Delegate>
 
    </Argument>
 
</Method>
 

 

El method example:

 
public bool SetReferenceAttributesTest(XmlNode node, Delegate[] delegates)
 
        {
 
            try
 
            {
 
                SetReferenceAttributes setReferenceAttributesDelegate = delegates[0] as SetReferenceAttributes;
 
                if (setReferenceAttributesDelegate != null && node != null && node is XmlElement)
 
                {
 
                    // Using SetReferenceAttributes Delegate to set the conkeyref and conref attr
 
                    Hashtable ht = new Hashtable();
 
                    ht.Add("DirectReference", "c:/Dummy.xml");
 
                    ht.Add("IndirectReference", "c:/Dummy1.xml");
 
                    return setReferenceAttributesDelegate(node, ht);
 
                }
 
            }
 
            catch (Exception e)
 
            {
 
                System.Diagnostics.Debug.WriteLine("SetReferenceAttributes Exception :" + e.Message + "\nStackTrace:" + e.StackTrace);
 
            }
 
            return false;
 
        }
 

RemoveReferenceAttributes

Public delegate bool RemoveReferenceAttributes (xmlNode xomNode)

This delegate is used to remove all the direct and indirect reference attribute values from the passed XOMNode. It also handles shading for the same.

Returns true if removed, false otherwise.

RemoveReferenceAttributes Parameters

Parameter

Required

Definition

xomNode

yes

XmlNode. The XOMNode to set the reference attribute to.

Configuration example:

 
<Method id="RemoveReferenceAttributesTest" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="RemoveReferenceAttributesTest">
 
                <Argument type="XomCurrentNode"/>
 
                <Argument type="Delegates">
 
                                <Delegate>RemoveReferenceAttributes</Delegate>
 
                </Argument>
 
</Method>
 

 

El method example:

 
       public bool RemoveReferenceAttributesTest(XmlNode node, Delegate[] delegates)
 
        {
 
            try
 
            {
 
                RemoveReferenceAttributes removeReferenceAttributesDelegate = delegates[0] as RemoveReferenceAttributes;
 
                if (removeReferenceAttributesDelegate != null && node != null && node is XmlElement)
 
                  {
 
                     return removeReferenceAttributesDelegate(node);
 
                  }
 
            }
 
            catch (Exception e)
 
            {
 
        System.Diagnostics.Debug.WriteLine(RemoveReferenceAttributesException : "+ e.Message + "\nStackTrace:" + e.StackTrace);
 
            }
 
            return false;
 
        }
 

SetListRestartContinueNumbering

Public delegate void SetListartRestartContinueNumbering (xmlNode xomNode, bool restart)

This delegate is used to restart/continue the list item.returns the dirty type of xomNode.

SetListRestartContinueNumbering Parameters

Parameter

Required

Definition

xomNode

yes

XmlNode. The XOMNode to set the reference attribute to.

restart

yes

If set to true, restart the list item, else continue.

Configuration example:

 
  <Method id="SetListRestartNumberingTest" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="SetListRestartContinueNumberingTest">
 
                <Argument type="XomCurrentNode"/>
 
                <Argument type="Tokens">
 
                                <Token>True</Token>
 
                </Argument>
 
                <Argument type="Delegates">
 
                                <Delegate>SetListRestartContinueNumbering</Delegate>
 
                </Argument>
 
</Method>
 
 
<Method id="SetListContinueNumberingTest" assembly="MiscellaneousDelegates" class="MiscellaneousDelegates.Misc" method="SetListRestartContinueNumberingTest">
 
                <Argument type="XomCurrentNode"/>
 
                <Argument type="Tokens">
 
                                <Token>False</Token>
 
                </Argument>
 
                <Argument type="Delegates">
 
                                <Delegate>SetListRestartContinueNumbering</Delegate>
 
                </Argument>
 
</Method>
 

 

EI method example:

 
public void SetListRestartContinueNumberingTest(XmlNode curXomNode, string []restart, Delegate[] delegates)
 
        {
 
            try
 
            {
 
                SetListRestartContinueNumbering setListRestartContinueNumbering = delegates[0] as SetListRestartContinueNumbering;
 
 
 
                if (setListRestartContinueNumbering != null && curXomNode != null && curXomNode is XmlElement)
 
                {
 
                    // Set restart numbereing for New Numbered list inserted and not new List item added
 
                    XmlNode listItemNode = curXomNode.SelectSingleNode("self::*[starts-with(local-name(),'oli')]");
 
                    if (listItemNode != null)
 
                    {
 
                     
 
                      setListRestartContinueNumbering(listItemNode, restart[0] == "True");
 
 
 
                    }
 
                }
 
            }
 
            catch (Exception e)
 
            {
 
                System.Diagnostics.Debug.WriteLine("SetListRestartContinueNumbering Exception :" + e.Message + "\nStackTrace:" + e.StackTrace);
 
            }
 
        }
 

 RemoveRefVariable

Public delegate void RemoveRefVariable (string docVariableName, string filename = null)

This delegate is used to remove the named reference variable from the Quark XML Author document. See Variable Reference Support.

RemoveRefVariable Parameters

Parameter

Required

Definition

docVariableName

yes

String. Name of the document variable to be removed.

filename

yes

The document;s full name, including the path. Defaults to null for the current document.

List of Available Document Events

The available document events are defined below.

For information on using events, see section 6.2.2.1, “Calling the EI Method from a Document Event”.

Activated

The Activated event fires when a document is created, opened or when the document window receives focus.

AfterSave

The AfterSave event fires after a document is saved.

BeforeComponentDelete

The BeforeComponentDelete is fired by a user action or the DeleteNode EI delegate when the action will result in one or more element being deleted. Specifically, the event is fired before all specified elements have been deleted. BeforeComponentDelete supports the DeleteNodes argument type. A return value of false will cancel the delete operation.

BeforeOpen

The BeforeOpen event fires just prior to the opening of a document. Typically used in conjunction with conversions, or any other preprocessing that cannot be accomplished with a transform. For example, can be used to in conjunction with the conversion of XML entities (HTML and other) to Unicode characters.

Definition:

BeforeOpen is a child of Namespace.

Any ExtensibilityMethod registering for this event has access to all content in the document, two document arguments and one token argument type. The three document arguments are ExportedRoot which is the document content that can be manipulated and returned, the Filename argument which is the full name of the file being opened and the standard Tokens argument.

 

The following AppConfig fragment sample shows this event being used to invoke an EI method.

 
<BeforeOpen assembly="EIHarness" method="ExecuteBeforeOpenStuff" class="EIHarness.EITester" >
 
  <Argument type="ExportedRoot"></Argument>
 
  <Argument type="Filename"></Argument>"
 
  <Argument type="Tokens">
 
    <Token>xform1= dita/transform1.xsl</Token>
 
    <Token>xform2= dita/transform2.xsl </Token>
 
  </Argument>
 
</BeforeOpen>
 

Responsibilities:

If the BeforeOpen EI throws an exception or returns false the Open process is cancelled.

 

Dependencies / Constraints:

A Namespace node may contain both the BeforeOpen node and the transform attribute. See section 8.7.1, Namespace. The Namespace reevaluate attribute is associated with the BeforeOpen event and the transform attribute.

 

BeforePaste

Whenever the user attempts to insert an XML component, the BeforePaste event fires, the component is attached to the XOM, the content is inserted into the document, and then the InsertComponent event fires. An EI method associated with this event can receive the argument type PasteNode. This is the XML node fragment about to be inserted. A method associated with BeforePaste can modify the PasteNode XML—it can modify attributes, modify element structure, and so forth, to conform to schema or business requirements.

BuildStyleList

Whenever the selection within a document changes, the BuildStyleList event fires in order to rebuild the list of elements that may be added to the document in the new cursor location.

ComponentDelete

The ComponentDelete event fires after one or more elements have been deleted as a result of a user action or is raised by the DeleteNode EI delegate. Specifically, the event is fired after all specified elements have been deleted.

Similar to BeforeComponentDelete, ComponentDelete supports the DeleteNodes argument type. However, in the case of ComponentDelete, the nodes have been detached from the tree. To provide the EI developer context, we also supply references to the deleted component's former parent node. The DeletedNodes argument is now a 2-dimensional array that associates each deleted node with its parent. The deleted node and its parent are essentially stored as a pair.

(0,0) accesses deleted node 1(0,1) accesses deleted node’s parent 1

(1,0) accesses deleted node 2(1,1) accesses deleted node’s parent 2

Return values from any of the invoked EI methods will not affect the delete operation.

The ComponentDelete event is not fired for the following:

  • deletion of emphasis nodes

  • DeleteRow(), DeleteColumn() and cell merges

Connect

The Connect event, used only in AppConfig.xml, fires immediately after Quark XML Author is loaded. It is used to connect Quark XML Author to other applications. Connect is the only event that is “global”.

To use Connect, define an EI Method for it in the standard manner. Connect can only take delegates or tokens as arguments.

In the ExtensibilityInterface node, you must also define a <Connect> child node that calls the EI Method. In the example below, the EI Method has been defined with the id value DSConnection.

 
<Connect>
 
<ExtensibilityMethod id="DSConnection"/>
 
</Connect>
 

DocClosed

The DocClosed event fires just prior to the closing of a Quark XML Author document. A separate DocClosed event is raised for each Quark XML Author document. All EI methods associated with this event are invoked sequentially. If an associated EI method returns false, the Close operation is cancelled. If the EI method raises an exception, a confirmation dialog prompts the user whether to continue or cancel the closing of the document.

DocOpened

The DocOpened event fires when a document is opened. Called before the Initialize event.

DoubleClickHeaderFooter

The DoubleClickHeaderFooter event fires when the user double clicks the header or footer region of the document if AllowHeaderFooterEdit (Section 9.8) is set to true.

Initialize

The Initialize event fires after DocOpened when a document is opened, but only for documents with no Binary data.

InsertElementXom

The InsertElementXom event fires for each element that is added to the XOM, regardless of whether that element is visible in the user interface. Not called for components attached via import, paste or InsertNode delegate.

InsertElementUI

The InsertElementUI event is similar to InsertElementXom, but fires only when adding elements that are visible in the user interface. For example, if a Note element was added, and it was itself invisible to the UI, but contained visible Title and Paragraph child elements, InsertElementXom would fire three times, but InsertElementUI would fire only twice.

InsertComponent

The InsertComponent event fires for drag and drop import, component paste, user-inserted elements, and the InsertNode delegate. The event is raised once for every top-level element that is inserted. For example, if the user inserts an element named Section that contains required Title and Para child elements, the firing order of events is as follows:

Section - InsertElementXom, InsertElementUI (if visible)

Title - InsertElementXom, InsertElementUI (if visible)

Para - InsertElementXom, InsertElementUI (if visible)

Section - InsertComponent

An EI method associated with this event can receive the argument type PasteNode. This is the XML node fragment about to be inserted.

InsertComponent will fire when splitting an element if the ElementDef in the XAS file uses the insertAfter attribute.

Drag and Drop

There is not an OnDrop event. Use the linkDropHandler attribute to specify the ID of the EI method to be called when the user drops a hyperlink onto the element. See “Table 14‑1: ElementDef Attributes”.

This feature overrides any internal XML Author behavior. For example, in the sample below, if "tocnumtitle" supports inline media elements, and the hyperlink dropped on this element happens to be a hyperlink to a media that the user wants to insert, the inline media behavior will never be invoked. Instead the EI method specified in the linkDropHandler attribute is invoked.

 

Example configuration

 
<ElementDef name="tocnumtitle" xmlname="title" friendly="Numbered Title" style="Heading 8" linkDropHandler="TestLinkDropHandler">
 
  <Section>
 
    <Para>
 
      <Emphasis>
 
        &emphasis-ref;
 
      </Emphasis>
 
    </Para>
 
  </Section>
 
  ...
 
</ElementDef>
 

 

Example method

 
<Method id="TestLinkDropHandler" assembly="TestEIs\DragDropTester" class="DragDropTester.Test" method="TestLinkHandlerEI">
 
  <Argument type="Tag"/>
 
</Method>
 

 

Tag: A special argument that contains the hyperlink that was dropped.

 

RightClickPreText

The RightClickPreText event fires when the user clicks on the portionmark pre-text area of a visible node. Used only in the DocConfig file.

RightClickPostText

The RightClickPostText event fires when the user clicks on the portionmark post-text area of a visible node. Used only in the DocConfig file.

Save

The Save event is fired just before the document is saved locally. Any EI methods specified in the Save node are executed and if any of them throws an exception or returns false, the save is cancelled.

UpdateAttributes

The UpdateAttributes event fires when an attribute is updated via the internal attribute panel. Any external methods defined under the <UpdateAttributes> tag in the EI are executed. If an external attribute panel is used to change attributes, there is a corresponding UpdateAttributes delegate which fires the UpdateAttributes event separately

 

StyleListParents

This is a special argument type used exclusively by the BuildStyleList EI methods. It contains a list of parents of currently insertable elements provided by the styleList argument with a one – on – one linkage with stylelist items. This argument can help the EI developer to distinguish between insertables under different parents with same name.