How to configure Quark XML Author to use external methods for Extensibility Interface?

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: Method Attributes defines these attributes, all of which are mandatory.

Table: 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 : ExtensibilityMethod Attributes.

Table : 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”.

Awesome, share it: