Configuring MetaFormsBridge
In some instances, a Windows form is a better user interface for adding and editing XML data than the Word canvas. Metadata forms, called MetaForms, can be created using the MetaForms Designer tool. For more information about creating MetaForms, see the MetaForms Designer User Guide. This section explains how to create the Extensibility Interface method that calls a MetaForm.
Quark XML Author provides an external class assembly, MetaFormsBridge, which can be called to link a visual form with a Quark XML Author document for inputting non-narrative XML data. The class information is listed below:
Full class name: Invision.MetaForms.MetaFormsLaunch
Assembly: MetaFormsBridge
Method: XpressRun
Like all external methods, XpressRun is called via an Extensibility Interface(EI) method in the document configuration file. Because XpressRun would only be used in conjunction with a Quark XML Author document, its EI method would only exist in a DocConfig file, and not in the AppConfig file. In the example below, a method named DocumentAttributes calls XpressRun:
<Method id="DocumentAttributes" assembly="MetaFormsBridge" class="Invision.MetaForms.MetaFormsLaunch" method="XpressRun">
<!-- Method info -->
</Method>For more information about building EI methods, see Section 6.
XpressRun Method
XpressRun returns a Boolean value. As with all EI methods, a return value of false halts processing of any further EI methods that may be associated with the command that called XpressRun. There are six signatures, shown below:
public bool XpressRun(string accessMode, XmlNode[] sourceNodes, string[] tokens, Delegate[] delegates)
public bool XpressRun(string accessMode, XmlNode[] sourceNodes, string[] tokens)
public bool XpressRun(string accessMode, XmlNode sourceNode, string[] tokens)
public bool XpressRun(string accessMode, XmlNode sourceNode, string[] tokens, Delegate[] delegates)
public bool XpressRun(XmlNode sourceNode, string[] tokens)
public bool XpressRun(XmlNode sourceNode, string[] tokens, Delegate[] delegates)The parameters that XpressRun may accept are explained below.
Table 19‑1: XpressRun Parameters
|
Parameter |
Definition |
|
accessMode |
Passes the access mode of the document. If the document’s accessMode is set to Review, the document is set to read only. The MetaForm can still be displayed and viewed, but any changes made while the form is open will not propagate back to the document when the form is closed. |
|
Delegate(s) |
Provides a delegate or list of delegates that will be supplied to XpressRun. If Invision.Xpress.ExtensibilityDelegates.UpdateAttributes is one of the delegates supplied, then it is executed on completion of form modifications. For information on Quark XML Author delegates, see Section 6.4. |
|
sourceNode(s) |
Provides the node or an array of nodes to be processed. |
|
tokens |
Specifies an array of values that can be passed to XpressRun to define where the MetaForm files are located, among other things. Tokens are explained in detail in the XpressRun Tokens section, below. |
XpressRun Tokens
The following tokens may be supplied via the Tokens parameter:
Table 19‑2: XpressRun Tokens
|
Parameter |
Definition |
|
Config=path |
Replace path with the path to the MetaForms configuration file. This is the main file defining the form. The path is relative to the Quark XML Author application folder. |
|
Rules=path |
Replace path with the path to the rules file for the MetaForm. The path is relative to the Quark XML Author application folder. |
|
Validate=true/false |
If set to true, directs Quark XML Author to run a validation script if one is specified in the configuration file. Defaults to false. |
|
ValidateMessage=message |
Replace message with the text of the message to show on a validation error. |
|
xmlns=namespace |
Replace namespace with the namespace for the MetaForm. |
|
XPath=path |
Replace path with XPath into the source node to use as the start node for processing. |
MetaForms Files
The files that define a MetaForm can be placed in any location, but Quark recommends placing them in a subfolder of the folder containing the configuration files for the document class. For example, given a configuration for a document class called Book, the configuration files for Book might be located in:
C:\Program Files\Quark\XML Author\Book
The MetaForm files should be placed in a subdirectory of Book. Again, the name of the folder can be anything, but Quark recommends naming the folder MetaForms:
C:\Program Files\Quark\XML Author\Book\MetaForms
Example
The example below illustrates one possible use of MetaFormsBridge. In this example, the method is used to call a document attributes form.
<Method id="DocumentAttributes" assembly="MetaFormsBridge" class="Invision.MetaForms.MetaFormsLaunch" method="XpressRun">
<Argument type="AccessMode"/>
<Argument type="XomRoot"/>
<Argument type="Tokens">
<Token>Config=Book\Metaforms\DocumentAttributes.xml</Token>
<Token>XPath=./DocumentMetadata</Token>
</Argument>
<Argument type="Delegates">
<Delegate>UpdateAttributes</Delegate>
</Argument>
</Method>This example implements the fourth XpressRun interface shown above, and reproduced here:
public bool XpressRun(string accessMode, XmlNode sourceNode, string[] tokens, Delegate[] delegates)
When the EI method is invoked, it passes the document access mode and the entire document structure to XpressRun (XomRoot—see section 6.3.1 for general information on XOM and Section 6.3 for the XomRoot enumerated value) to XpressRun. The tokens point to the MetaForm's configuration file and the XPath location of the source node to begin processing in the document. The configuration file is located in the Metaforms subdirectory of the document configuration file's location, and is called DocumentAttributes.xml. The XPath points to the DocumentMetadata node.
Finally, the UpdateAttributes delegate is supplied. When the user finishes making changes to the form, UpdateAttributes is triggered.