Configuring Smart Paste
Smart Paste is a Quark XML Author feature that allows you to copy content from a standard Word document and convert that content to structured XML to be pasted into a Quark XML Author document. This chapter explains how to configure Smart Paste.
Smart Paste Overview
Smart Paste is accomplished through the use of three stylesheets, an Extensibility Interface (EI) method, and an EI call from a document event. Here is an overview of what happens when an author uses smart paste:
-
In an external document, the author selects content and copies it to the clipboard. If the external document is Microsoft Word, then Word pastes XHTML onto the clipboard.
-
The author switches to a Quark XML Author document. Quark XML Author is now involved in the process. The Activated event fires and calls the EI method defined to handle Smart Paste.
-
The EI method determines that there is content on the clipboard that needs to be processed. It calls the external Smart Paste.
-
SP_Filter.xslt filters the XHTML content on the clipboard. This performs a level of normalization.
-
SP_Clipboard.xslt converts the XHTML content into intermediate format that conforms to the Smart Paste schema. See “The Intermediate Schema”. This performs an additional level of normalization. The normalized content is ready for configuration-specific processing.
-
A configuration-specific transform transforms the content into the XML structure that matches the target document schema. See “Configuration-specific transforms”.
-
An additional configuration-specific transform can be used to further transform tabular content. See “Configuration-specific table transforms”.
When the user subsequently right-clicks in a document location, if the content on the clipboard matches a legal document element as defined in the configuration, the context menu will contain a Paste {element} entry corresponding to the copied content.
Smart Paste Extensibility Method
SmartPaste.dll, which facilitates the Smart Paste feature, is a standard component of Quark XML Author and is located in the Quark XML Author application folder. In order to use Smart Paste, you must define an EI method in the DocConfig file. The EI method will call the Start method in the Invision.Xpress.Extensibile.SmartPaste class. Detailed information on configuring EI methods can be found in section 6, but an example of the Method element and its attributes is shown below:
<MethodInfo>
<Method id="SmartPaste" assembly="Quark.XA.SmartPaste" class="Invision.Xpress.Extensible.SmartPaste" method="Start">
<!-- Arguments are discussed below -->
</Method>
</MethodInfo>
Of course, you may name the EI Method anything you wish; typically SmartPaste is used as the Method’s id value for ease of reference.
The Start method requires one argument that contains three tokens. All three tokens must be provided in name=value format, where name identifies the name of the parameter being passed and value is the parameter value.
The first token identifies the location of the stylesheet that maps intermediate content to the Quark XML Author Structure. It takes the following format:
ImportXslt=quark\Renditions\smart-paste.xsl
The left side of the name=value pair must be ImportXslt. The right side of the pair is a path relative to the Quark XML Author application folder and must include the full name of the stylesheet file.
The second token defines how images are to be handled if any are present in the source content. Use Image=embed if the XAS specifies that images are embedded in the document and Image=reference if the XAS defines images as referenced content.
The third token is the debug setting. For production systems, this will always be set to Debug=false. If set to Debug=true, the system will display a window containing four tabs, each of which contains the results of one stage of the transformation process.
Configuration-specific transforms
A typical, fully-defined EI Method for Smart Paste is shown below:
<MethodInfo>
<Method id="SmartPaste" assembly="Quark.XA.SmartPaste" class="Invision.Xpress.Extensible.SmartPaste" method="Start">
<Argument type="Tokens">
<Token>ImportXslt=quark\Renditions\smart-paste.xsl</Token>
<Token>Image=embed</Token>
<Token>Debug=false</Token>
</Argument>
</Method>
</MethodInfo>
The following is an example of a DITA XML specific transform call:
<!-- this snippet is found in doc config: DITA/sme-config.xml -->
<ExtensibilityInterface>
<MethodInfo>
<Method id="SmartPaste" assembly="Quark.XA.SmartPaste" class="Invision.Xpress.Extensible.SmartPaste" method="Start">
<Argument type="Tokens">
<Token>ImportXslt=DITA/xml_smartPaste_dita.xsl</Token>
...
...
</Argument>
</Method>
Configuration-specific table transforms
An additional configuration-specific transform can be used to transform tabular content.
The following is an example of a DITA XML specific table transform call:
<!-- this optional snippet would be found in doc config: DITA/sme-config.xml -->
<ExtensibilityInterface>
<MethodInfo>
<Method id="SmartPaste" assembly="Quark.XA.SmartPaste" class="Invision.Xpress.Extensible.SmartPaste" method="Start">
<Argument type="Tokens">
...
<Token>CustomTableXslt=[PATH]/[FILENAME].xsl</Token>
...
</Argument>
</Method>
Enabling Smart Paste
As with any EI method, you must also define some means to call it. The Smart Paste method is called by Quark XML Author’s Activated event, which is fired whenever a Quark XML Author document receives focus. The Smart Paste method must be defined in the DocConfig file, similar to the EI method. Add the following element to the ExtensibilityInterface node of the DocConfig file:
<Activated>
<ExtensibilityMethod id="SmartPaste"/>
</Activated>
The value of the id attribute must equal the value of the id value for the Smart Paste method.
The Intermediate Schema
The intermediate table schema for 4.0 is XHTML. When table content is pasted from Word, the format is XHTML and does not have to be converted.
Earlier versions of Quark XML Author used CALS as the intermediate schema which required the table content from Word to have to be converted from XHTML to CALS.
Smart Paste uses three stylesheets. Two standard stylesheets ship with Quark XML Author and are typically not modified[1]. These stylesheets are SP_Clipboard.xslt and SP_Filter.xslt, and are located in the Quark XML Author application folder. These files perform the first stages of the transformation process. The result is an XML document that conforms to the Smart Paste schema. It consists of an Import element that contains the copied content elements. An overview of the schema is provided here.
Import can contain one or more of any of the following elements: Heading, Para, ListItem, Table, and Image.
The third stylesheet is configuration-specific and resides in the application \ configuration folder. For example, {application folder} \DITA\xml_smartPaste_dita.xsl.
[1] Although these stylesheets are typically not modified, they can be changed to support other types of source documents such as HTML, Microsoft Excel, or even other types of XML Author documents.
TextType Elements
The first three elements (Heading, Para, and ListItem) are all TextType elements and, as such, have the same substructure (described in section 18.4.1.1, “TextType Structure”).
Table 18‑1: TextType Elements
|
Element |
Definition |
|
Heading |
Heading elements are created from any Word paragraph that has a style of Heading #, where # is any number (Heading 1, Heading 2, etc.) Heading has no special attributes. |
|
ListItem |
ListItem elements are created from any Word paragraph that is a list style (bullets or numbered). The style attribute specifies whether the list item type is bullet (style="ul") or numbered (style="ol"). For example: <ListItem style="ul">List item text</ListItem> Note that ListItem elements are not wrapped in any sort of parent List element; this must be accomplished in the final transform stylesheet. |
|
Para |
Any text paragraph in the source content that does not meet the criteria for a Heading or a ListItem element is transformed into a Para element. Para has no special attributes. |
TextType Structure
TextType elements comprise either text or a Hyperlink child element.
Text can be mixed with any combination of Bold, Italic, and Underline elements. Superscript and Subscript are also available, but may not contain any further markup.
Hyperlink contains text that also may be mixed with the markup elements listed above. It also has the attribute xlink:href, which contains the URL to which the hyperlink points.
Table
Smart Paste may only configured for one table definition per configuration. The final table definition is determined by the final transformation of the intermediate table format (illustrated below) into the desired format (CALS, HTML, etc.).
The output from sp_clipboard.xslt converts the filtered Word XHTML into a table with an HTML-like structure. This is an example of a 2x2 Word table after transformation:
<Import xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:sp="http://www.w3.org/TR/REC-html40" xmlns:spext="urn:xpressauthor:smartpaste:extensions"
xmlns:inlinext="urn:convert"
xmlns:xlink=http://www.w3.org/1999/xlink
xmlns:xt="urn:xpressauthor:trackchanges>
<Table>
<tbody>
<tr>
<td tempid="EDDDBA" colspan="" rowspan="" tableRowColumnSize="239.4pt" tableBorderBottomStyle="" tableBorderTopStyle="" tableBorderRightStyle="" tableBorderLeftStyle="">
<Para>Table cell one</Para>
</td>
<td tempid="EBDDBA" colspan="" rowspan="" tableRowColumnSize="239.4pt" tableBorderBottomStyle="" tableBorderTopStyle="" tableBorderRightStyle="" tableBorderLeftStyle="">
<Para>Table cell two</Para>
</td>
</tr>
<tr>
<td tempid="EDBDBA" colspan="" rowspan="" tableRowColumnSize="239.4pt" tableBorderBottomStyle="" tableBorderTopStyle="" tableBorderRightStyle="" tableBorderLeftStyle="">
<Para>Table cell three</Para>
</td>
<td tempid="EBBDBA" colspan="" rowspan="" tableRowColumnSize="239.4pt" tableBorderBottomStyle="single" tableBorderTopStyle="" tableBorderRightStyle="single" tableBorderLeftStyle="
 none">
<Para>Table cell four</Para>
</td>
</tr>
</tbody>
</Table>
</Import>
Image
The attributes and content of the Image element depend on the value of the Image token in the EI Method.If the token content is Image=reference, then the Image element is empty and the href attribute specifies the location of the referenced image.If the token content is Image=embed, then the Image element contains the Base 64 encoding for the image content and the href attribute is not used.
Table 18‑2: Image Attributes
|
Attribute |
Required |
Definition |
|
href |
no |
Value is the URL of a referenced image. If the file no longer exists at its original location when the copy operation is performed, the value will be a temporary location. |
|
filename |
yes |
Value is the file name of the image. |
|
coordinates |
yes |
Value is four comma-separated integers specifying, in this order: X position, Y position, width, and height of the image. |
Final Transformation Stylesheet
The final transformation stage is performed by the stylesheet identified in the first Token described above. Although this stylesheet can have any file name, we will refer to it here as the “Smart Paste stylesheet”.
The Smart Paste stylesheet maps the intermediate document to the Quark XML Author Structure so that the content can be pasted into the Quark XML Author document.
Multipart Wrapper
If the user selects more than one paragraph[1] in the source document, the XML that is added to the clipboard must be contained in a Multipart wrapper element. Consider the very simple example of an Import document with two sibling paragraphs, as shown below:
<Import>
<Para>Test1</Para>
<Para>Test2</Para>
</Import>
These sibling elements must be placed within the Multipart wrapper. In the example below, the Para element from the intermediate stylesheet has been mapped to the <p> element:
<Multipart>
<p>Test1</p>
<p>Test2</p>
</Multipart>
The Smart Paste stylesheet must implement logic to determine whether or not the Multipart wrapper is necessary. The XSLT template below returns a value of true or false to specify whether or not the Multipart wrapper should be used. The template checks the intermediate XML content to see if the selection includes multiple sibling elements, including Heading and child elements:
<!--*************************************************************************
** Import Template ++ Decide whether to use the Multipart parent container
**************************************************************************-->
<xsl:template name="IsMultipart">
<xsl:choose>
<xsl:when test="count(//Heading) > 1">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 1 and count(/Import/*[position() = 1 and local-name() != 'Heading']) > 0">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para) > 1">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para | //InvisionTable) > 1">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para) = 1 and count(//Import/*[position() = 1 and local-name() != 'para']) > 0">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para) = 1 and count(//Import/*[position() = 1 and local-name() = 'para']) = 1 and count(//Import/*[local-name() != 'para' and local-name() != 'listitem']) > 0">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para) = 0 and count(/Import/*) > 1 and count(/Import/*[local-name() != 'listitem']) = 0">
<xsl:value-of select="false()"/>
</xsl:when>
<xsl:when test="count(//Heading) = 0 and count(//para) = 0 and count(/Import/*) > 1">
<xsl:value-of select="true()"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="false()"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
The rest of the stylesheet must be defined to map the intermediate elements, as described previously, to the appropriate elements in the Quark XML Author Structure.
[1] In this context, “paragraph” refers to any object in the Word document: paragraphs, tables, images, etc., and any combination of these.
Example: Intermediate Heading > Quark XML Author Section
In the following template, the stylesheet transforms any Heading element it finds into a Section element. It examines the Heading’s subsequent sibling elements and places them within the section element until it finds another Heading element or reaches the end of the document.
<xsl:template match="Heading">
<xsl:element name="section">
<xsl:if test="(count(.//*) > 0) or (string-length(text()) > 0)">
<title>
<xsl:apply-templates select="text() | Bold | Italic | Underline | Superscript | Subscript | Hyperlink"/>
</title>
</xsl:if>
<xsl:variable name="thisPos" select="count(preceding-sibling::*) + 1"/>
<xsl:variable name="lastPos">
<xsl:choose>
<xsl:when test="not(following-sibling::Heading)">
<xsl:value-of select="count(//Import/*)+1"/>
</xsl:when>
<xsl:otherwise>
<xsl:for-each select="following-sibling::Heading[1]">
<xsl:value-of select="count(preceding-sibling::*) + 1"/>
</xsl:for-each>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:for-each select="//Import/*">
<xsl:if test="position() > $thisPos and position() < $lastPos">
<xsl:choose>
<xsl:when test="local-name() = 'listitem' and count(preceding-sibling::*[position() = 1][local-name() = 'para']) = 1"/>
<xsl:when test="local-name() = 'listitem' and count(preceding-sibling::*[position() = 1][local-name() = 'listitem']) = 0">
<xsl:apply-templates select="."/>
</xsl:when>
<xsl:when test="local-name() = 'listitem' and count(preceding-sibling::*[position() = 1][local-name() = 'listitem']) > 0"/>
<xsl:otherwise>
<xsl:apply-templates select="."/>
</xsl:otherwise>
</xsl:choose>
</xsl:if>
</xsl:for-each>
</xsl:element>
</xsl:template>
Example: Handling List Items
The following template contains logic to handle list item elements.
<xsl:template match="listitem">
<xsl:choose>
<xsl:when test="count(preceding-sibling::*[position()=1][contains(',listitem,', local-name())]) = 0">
<itemizedlist>
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
<xsl:apply-templates select="following-sibling::*[position() = 1][local-name() = 'listitem']"/>
</itemizedlist>
</xsl:when>
<xsl:when test="count(following-sibling::*[position()=1][local-name() = 'listitem']) > 0">
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
<xsl:apply-templates select="following-sibling::*[position() = 1][local-name() = 'listitem']"/>
</xsl:when>
<xsl:otherwise>
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
Example: Handling Table Rows
The following template validates that a row should only be transformed if it contains table data (i.e. cell).
<xsl:template match="tr">
<xsl:if test="descendant::td">
<row>
<xsl:apply-templates select="@*[name()!='xmlns']"/>
<xsl:apply-templates select="td"/>
</row>
</xsl:if>
</xsl:template>
