Integration with Content Management Systems
Communication with a Content Management System (CMS) for content upload and download is handled externally from Quark XML Author. Quark XML Author passes the content and information for handling that content to an external DLL that performs the upload and download tasks. This chapter explains:
-
How to configure the Quark XML Author Internal Class SaveToRepository that is used to integrate with the external DLL.
-
The upload interface that the external DLL must implement in order for SaveToRepository to communicate with it.
-
The download interface that the external DLL must expose in order for Quark XML Author to be able receive content from the repository.
SaveToRepository
Quark XML Author uses the SaveToRepository Internal Class to call the external DLL that performs the upload operation. The SaveToRepository internal class is structured as shown below. Table 17‑1 defines the attributes used for the InternalClass element.
<InternalClass name="SaveToRepository" nativeFormat="true" assembly="assemblyName" class="className">
<Argument type="Tokens">
<Token>Token Data as needed, one datum per token.</Token>
</Argument>
<Argument type="Delegates">
<Delegate>Delegates as needed.</Delegate>
</Argument>
</InternalClass>
Table 17‑1: SaveToRepository Attributes
|
Attribute |
Required |
Definition |
|
assembly |
yes |
Specifies the file name of the .NET class library that implements the upload process (without the .dll extension). |
|
class |
yes |
Specifies the fully namespace-qualified class name within the .dll file being called for the external process |
|
name |
yes |
Name of the class to be invoked. In this case, SaveToRepository. |
|
nativeFormat |
no |
Boolean. Defaults to false. When set to true, Word binary is included with the document. |
The InternalClass element is used in the configuration file, usually for the document class.
Example
Here is an example of how SaveToRepository might be used in a DocConfig file. Like the other examples in this chapter, it assumes that we are communicating with a CMS called Tritus.
<MenuItem resourceId="SaveToTritus">
<InternalClass name="SaveToRepository" assembly="Tritus" class="fullNamespaceOftheClass.Tritus" nativeFormat="false">
<Token>enableLogging=true</Token>
<Token>credentials=windows</Token>
</InternalClass>
</MenuItem>
The example above maps the SaveToRepository internal class to a menu item. When the menu item is selected, SaveToRepository will dynamically load the Tritus.dll assembly and look for the upload() implementation in the specified class. (The upload() interface is described below). If the assembly or any of its dependencies do not load or the specified class does not exist or does not implement the upload() signature, an error message will be displayed and Quark XML Author will not perform any upload.
Upload() Interface
In order to allow Quark XML Author to check documents into a repository, the external DLL must implement one of the following interfaces:
bool upload(System.String fileContents, string filename, string[] tokens)
bool upload(System.String fileContents, string filename, string[] tokens, Delegate[] delegates)
fileContents
The complete XML document that currently has focus. The XML will contain any changes occurring after the document was opened or last saved locally.
filename
The name of the XML document that currently has focus.
tokens
A list of tokens that are specified in the InternalClass that calls the upload interface. (See SaveToRepository on page 92. The string array is made up of the contents of each of the <Token> nodes specified as a child of the InternalClass node. If no tokens are provided in the Internal Class, the token array will be null. The tokens are completely arbitrary and can be any text string that an upload() function needs in order to execute successfully.
delegates
An optional list of predefined delegates supported by Quark XML Author. Supported delegates are discussed in section 6.4.
The upload() interface returns a Boolean value which indicates whether an upload succeeded or failed. For example:
<MenuItem resourceId="SaveToTritus">
<InternalClass name="SaveToRepository" assembly="Tritus" class="fullNamespaceOftheClass.Tritus" nativeFormat="false">
<Tokens>
<Token>enableLogging=true</Token>
<Token>credentials=windows</Token>
<Token>webservice=http://soap.tritus.com/schemas/TritusWebServices.wsdl</Token>
<Token>iniFileLocation =C:\Program Files\XML Author\TritusCMS.ini</Token>
<Tokens>
</InternalClass>
<InternalClass name="DocumentClose"/>
</MenuItem>
The menu item shown above has two actions associated with it. Normally, both of them will execute in sequence when the menu item is clicked, but a return of false from the upload() method causes any subsequent actions to be ignored. Thus, a return value of false will cancel the execution of the DocClose event which simply cancels the closing of the document and keeps it open in Quark XML Author if upload failed.
Example 1: Upload without delegates
Below is a very simple upload() function that implements the simpler signature:
bool upload(System.String fileContents, string filename, string[] tokens)
It uses a published web service used by the Tritus CMS to perform the upload function. If there are any other details embedded in the document, we can use that in the upload function as well. In the example below, the document root has an embedded id attribute (this id is being assigned by Tritus CMS when it provided the document), which is extracted and used for the upload.
namespace fullNamespaceOftheClass
{
public class Tritus
{
bool upload(string fileContents, string fileName, string[] tokens)
{
try{
//These are completely arbitrary and not required.
//read the tokens - Order of tokens are preserved.
bool log = tokens[0].Split('=')[1]].Equals("true"); //to turn logging on.
string cred = tokens[1].Split('=')[1]]; //use windows credentials
string url = tokens[2].Split('=')[1]]; //web service URL.
string iniFile = tokens[3].Split('=')[1]]; //This location will point to any CMS specific information required for the upload() function.
//get credentials for access to the CMS
ICredentials credentials = CredentialCache.DefaultCredentials; //since the token[1] says gets windows Credentials
//read the document to get some details from it.
XmlDocument doc = new XmlDocument();
doc.LoadXml(fileContents);
string id = doc.DocumentElement.GetAttribute("id");
//if there is no ID we consider this to be a brand new document, or if there is one if we consider this to be an existing document.
Tritus.CMS.WebServices service = new Tritus.CMS.WebServices();
sservice.Credentials = credentials;
int newID = 0;
if(id ==String.Empty){
//New document
newID = service.ImportDocument(fileContents, fileName, credentials);
}
else{
//Existing document - attempt to invoke the Checkin webservice.
newID = service.CheckinDocument(id, fileContents, fileName, credentials);
}
return success;
}catch(Exception e)
{
//Good idea to log any specific log errors.
//Can be either thrown back to Quark XML Author or a false return to signify failure
return false;
}
}
}
}
Example 2: Upload with delegates
The other upload() signature that can be used is:
bool upload(System.String fileContents, string fileName, string[] tokens, Delegate[] delegates);
Here is an example of how this signature can be called by a menu item:
<MenuItem resourceId="SaveToTritus">
<InternalClass name="SaveToRepository" assembly="Tritus" class="fullNamespaceOftheClass.Tritus" nativeFormat="false">
<Tokens>
<Token>enableLogging=true</Token>
<Token>credentials=windows</Token>
<Token>webservice=http://soap.tritus.com/schemas/TritusWebServices.wsdl</Token>
<Token>iniFileLocation =C:\Program Files\XML Author\TritusCMS.ini</Token>
<Tokens>
<Delegates>
<Delegate>InvokeInternalClass</Delegate>
</Delegates>
</InternalClass>
</MenuItem>
An InvokeInternalClass delegate is used inside the InternalClass definition; this delegate will be passed to the upload() method defined below. (Supported delegates are discussed in section 6.4.)
bool upload(string fileContents, string fileName, string[] tokens)
{
try{
//Remember these are completely arbitrary and not required. If there are no tokens in the config file, tokens will be null.
//read the tokens - Order of tokens are preserved.
bool log = tokens[0].Split('=')[1]].Equals("true"); //to turn logging on.
string cred = tokens[1].Split('=')[1]]; //use windows credentials
string webserviceURL = tokens[2].Split('=')[1]]; //web service URL.
string iniFile = tokens[3].Split('=')[1]]; //This location will point to any CMS specific information required for the upload() function.
Invision.Xpress.ExtensibilityDelegates.InvokeInternalClass invokeInternalClassDelegate = delegate[0] as Invision.Xpress.ExtensibilityDelegates.InvokeInternalClass;
//get credentials for access to the CMS
ICredentials credentials = CredentialCache.DefaultCredentials; //since the token[1] says gets windows Credentials
//read the document to get some details from it.
XmlDocument doc = new XmlDocument();
doc.LoadXml(fileContents);
string id = doc.DocumentElement.GetAttribute("id");
//if there is no ID we consider this to be a brand new document, or if there is one if we consider this to be an existing document.
Tritus.CMS.WebServices service = new Tritus.CMS.WebServices();
service.Url = webserviceURL;
service.Credentials = credentials;
int newId = 0;
if(id ==String.Empty){
//New document
newId = service.ImportDocument(fileContents, fileName, credentials);
}
else{
//Existing document - attempt to invoke the Checkin webservice.
newId = service.CheckinDocument(id, fileContents, fileName, credentials);
}
//Before returning, check with user whether to close Document.
if(success && invokeInternalClassDelegate != null && MessageBox.Show("Close Document?", "Tritus", MessageBoxButtons.YesNo, MessageBoxIcon.Warning) == DialogResult.Yes){
//The second parameter are for any other parameters for DocumentClose.Please refer to DocumentClose documentation for all possible parameters
invokeInternalClassDelegate("DocumentClose", new Hashtable()); //This will initiate the closing of the document.
}
else
//Do nothing. The document will remain open in the UI.
//As seen above, the upload() method can initiate closure of a document as well through the above delegate call. This makes it a little more flexible in terms of closing document for
//various scenarios. In the above case, I close the document only if user chooses Yes in the dialog.
return success; //since there is no event following the upload() in the MenuItem, the return value here does not hold any relevance.
}catch(Exception e)
{
//Good idea to log any specific errors.
//Can be either thrown back to Quark XML Author or a false return to signify failure
return false;
}
}
Example 3: Upload a document fragment
In the previous examples, the upload was for a complete document. There are multiple ways to upload/import partial fragments into a CMS by making use of the Extensibility Interface. (A complete discussion of the Extensibility Interface can be found in section 6.) For example, let’s say the user wants to make a List in the document reusable by importing it into the CMS as a brand new fragment. Here is a sample configuration that will do it:
<!-- Method definition (in the doc-config) file-->
<Method id="UploadAnyFragment" assembly="Tritus" class="fullNamespaceOftheClass.Tritus" method="UploadFragment">
<Argument type="XomCurrentNode"/>
<Argument type="Tokens">
<Token>enableLogging=true</Token>
<Token>credentials=windows</Token>
<Token>webservice=http://soap.tritus.com/schemas/TritusWebServices.wsdl</Token>
</Argument>
<Argument type="Delegates">
<Delegate>ToggleEditableRegion</Delegate>
</Argument>
</Method>
<!-- Method reference (in the xas file)-->
<ElementDef name="List" friendly="List" visible="false">
<Section>
<Sequence maxOccurs="unbounded">
<SectionType name="ListItem"/>
</Sequence>
</Section>
<Attributes>
<AttributeType name="id"/>
</Attributes>
<ExtensibilityMethods>
<!-- HERE IS THE ACTUAL REFERENCE-->
<ExtensibilityMethod id="UploadAnyFragment" friendly="Reuse Component"/>
</ExtensibilityMethods>
</ElementDef>
There are two parts to any Extensibility Interface implementation—definition and reference. The definition in this case is in the document configuration file. The reference is in the Quark XML Author Structure (xas). The reference is allowing us to access the UploadFragment from the UI through the Component->List Context Menu. So if we want to make an existing list in a document a reusable component in the CMS , we will right-click on the List (or any of its children), access the Component->List menu and we should see the Reuse Component menu item. Clicking that will invoke the UploadFragment()method. As shown in the definition, it takes the XomCurrentNode, which in this case will be the List instance. The ToggleEditableRegion delegate is passed in to mark the region non-editable (indicated by color shading the background of the region) after the upload is successful. This reference must be repeated for each element that can be marked as a reusable fragment. For example, if tables in the document can be marked as reusable, the reference would need to appear in the table element definition as well.
The upload method that would be used in conjunction with the example above is shown below:
namespace fullNamespaceOftheClass
{
public class Tritus
{
public void UploadFragment(XmlNode nodeToBeUploaded, string[] tokens, Delegate[] delegates)
{
//Remember these are completely arbitrary and not required.If there are no tokens in the config file, tokens will be null.
//read the tokens - Order of tokens are preserved.
bool log = tokens[0].Split('=')[1]].Equals("true"); //to turn logging on.
string cred = tokens[1].Split('=')[1]]; //use windows credentials
string webserviceURL = tokens[2].Split('=')[1]]; //web service URL.
Invision.Xpress.ExtensibilityDelegates.ToggleEditableRegion toggleEditableRegionDelegate = delegates[0] as Invision.Xpress.ExtensibilityDelegates.ToggleEditableRegion;
//get credentials for access to the CMS
ICredentials credentials = CredentialCache.DefaultCredentials; //since the token[1] says gets windows Credentials
Tritus.CMS.WebServices service = new Tritus.CMS.WebServices();
service.Url = webserviceURL;
service.Credentials = credentials;
bool success = false;
int newId = 0;
string id = nodeToBeUploaded.GetAttribute("id");
if(id ==String.Empty){
//New fragment
newId = service.ImportFragment(fileContents, credentials);
}
else{
//Existing fragment - attempt to invoke the Checkin webservice.
newId = service.CheckinFragment(id, fileContents, credentials);
}
//Make the uploaded node non-editable and also toggle the region in the UI to make it read-only.
if(newId > 0 && toggleEditableRegionDelegate != null)
{
XmlNode[] nodesToBeMadeReadonly = new XmlNode[1];
nodesToBeMadeReadonly.Add(nodeToBeUploaded);
//For all nodes append an inv:access=readonly attribute to make sure the nodes cannot be modified.
XmlAttribute accessAttr = nodeToBeUploaded.OwnerDocument.CreateAttribute("inv", "access", "urn:xpressauthor:xpressdocument");
accessAttr.Value = "read-only";
nodeToBeUploaded.Attributes.Prepend(accessAttr);
//Assign the new id to the id attribute.
nodeToBeUploaded.SetAttribute("id", newID);
toggleEditableRegionDelegate(nodesToBeMadeReadonly, true, true); //This will notify the UI to make the List and all its region non-editable
}
}
}
Download and Content Reuse
Two types of operations for retrieving content from a CMS need to be considered: opening an entire document and importing content fragments into an already open document.
Open a CMS Document in Quark XML Author
Quark XML Author has built-in classes to open a document from a local or network drive, or from a network WEBDAV folder. If the location is on a proprietary CMS, there are two possible ways to support opening a file:
-
Leveraging an existing hook in the external CMS. For example, the Documentum CMS, through its Webtop interface, exposes a way to launch an external editor to edit XML files. Quark XML Author can be configured as such an external editor through the File types association in Windows Explorer.
-
From within Quark XML Author.
The simplest way to do the latter would be to write an extensibility method to download the entire document into a temp location on disk and launch Quark XML Author to open the downloaded file. Here is a simple example that does just that:
<Method id="OpenFromTritus" assembly="Tritus" class="fullNamespaceOftheClass.Tritus" method="OpenFromTritus">
<Argument type="Tokens">
<Token>credentials=TritusLogin.xml</Token>
<Token>webservice=http://soap.tritus.com/schemas/TritusWebServices.wsdl</Token>
<Token>openLocation=c:\Tritus\Export</Token>
</Argument>
</Method>
This method definition invokes the OpenFromTritus method exposed in the class shown below:
namespace fullNamespaceOftheClass
{
public class Tritus
{
public void DocumentOpen(string[] tokens)
{
//read tokens
string openLocation = tokens[3].Split('=')[1]];
string webserviceURL = tokens[1].Split('=')[1]]; //WSDL location
//Connect to the Tritus web service
Tritus.CMS.WebServices service = new Tritus.CMS.WebServices();
service.Url = webserviceURL;
service.Credentials = credentials;
//Launch some sort of File Explorer UI to get the file path and download it. Remember this is just an example
//and the implementation can differ. The ultimate objective is to download the file to a local temp location and have Quark XML Author launch
//this temporary file.
stream content = service.OpenFromRepository(ref returnContentType, ref filename); //get the content type, and the opened object's name
if(content != null && returnContentType.IndexOf("text/xml") > -1) //Only interested in XML content
{
//Save it to a local location with the returned filename
string tempFileName = openLocation +"\\" + DateTime.Now.Ticks +"\\" + filename + ".xml";
FileInfo tempF = new FileInfo(tempFileName);
if (!tempF.Directory.Exists)
tempF.Directory.Create();
StreamWriter writer = new StreamWriter(tempF.FullName, false, "UTF-8");
System.IO.StreamReader sr = new System.IO.StreamReader(content, Encoding.GetEncoding("UTF-8")); //Assuming encoding as UTF-8
string fileContents = sr.ReadToEnd();
sr.Close();
//If the file or part of it needs to be launched in readonly mode, the nodes to be launched in read-only mode can be assigned an Invision defined
//attribute called inv:access like below.
XmlDocument doc = new XmlDocument();
doc.LoadXml(fileContents);
XmlAttribute accessAttr = doc.CreateAttribute("inv", "access", "urn:xpressauthor:xpressdocument");
accessAttr.Value = "read-only";
doc.DocumentElement.Attributes.Prepend(accessAttr);
writer.Write(doc.OuterXml);
writer.Close();
if(File.Exists(tempFileName)
Process.Start(tempFileName); //This assumes that the text/xml mimetype in the file type associations is mapped to Quark XML Author.
}
}
}
}
Importing content into existing documents
External content can be imported into Quark XML Author by dragging and dropping hyperlinks to the external content into the document. Content links can be dropped in “Empty” locations in the document or onto a Reference element that has previously been inserted.
“Empty” locations are nothing but an empty paragraph that Quark XML Author uses to delineate separate content elements. These paragraphs are assigned the “Empty” style and cannot hold any content. When the user drops a link onto an Empty location, Quark XML Author inserts the dropped content and surrounds the new element(s) with Empty paragraphs. The dropped content becomes a part of the document and can be edited in-line without affecting the source. This content is therefore a ‘copy’ and does not retain any relationship with the original content.
Reference elements can be defined so that content can be imported that is not editable within Quark XML Author. A reference container is simply an XML container element with an hfref attribute; the attribute points to the resource being referenced. See section 14.7 for information on defining reference elements in the Quark XML Author Structure.[1]
For either method of importing content, the ResolveReferences node in the AppConfig file must be present and configured to accept data from the CMS. A typical configuration from the AppConfig.xml looks like this:
<ResolveReferences>
<Reference pattern="?objId=x-en-tritus:" assembly="Tritus" class="IfullNamespaceOftheClass.Tritus">
<Token>webservice=http://soap.tritus.com/schemas/TritusWebServices.wsdl</Token>
<Token>credentials=TritusLogin.xml</Token>
</Reference>
<!-- This is the default fallback pattern (.*) that matches every url. -->
<Reference pattern=".*" assembly="SomeOtherDll" class="SomeOtherNamespace.SomeOtherClass"/>
</ResolveReferences>
ResolveReferences can hold multiple Reference nodes, each of which can invoke a different download() interface to get content from one or more content management systems. The download() interface itself is explained in the next section.
Table 17‑2 defines the attributes used for the Reference node.
Table 17‑2: Reference Attributes
|
Attribute |
Required |
Definition |
|
assembly |
yes |
Name of the assembly which contains the download() interface implementation. |
|
class |
yes |
Name of the class which contains the download() interface implementation. |
|
pattern |
yes |
The pattern attribute’s value must be a regular expression that contains a matching pattern for the URI that refers to the CMS. When an object is dragged into Quark XML Author, Quark XML Author searches for a pattern that can be matched against the URI for the object being dragged into it. In the example above, if the URL being processed contains ?objId=x-en-tritus: then the IfullNamespaceOftheClass.Tritus.download() method is invoked. For all other URLs, SomeOtherNamespace.SomeOtherClass.download() is invoked. To allow all URIs to match a single Reference node, the wildcard character phrase (.*) can be used as the value of the pattern attribute. |
[1] It is possible to import content in non-editable form without using reference elements, but this requires additional external resources. For example, the DocumentOpen event could be used to call an external DLL that scans the document, searches for content that should not be edited, and marks it accordingly. However, the content still “lives” within the document, whereas with a reference element, the content “lives” in the CMS and is merely referenced by the document.
Download Interface
The external DLL that calls the CMS must implement one of the following interfaces:
Stream download(string uri, string[] tokens, out string returnContentType)
Stream download(string uri, string[] tokens, out string returnContentType, out string alternateText)
Table 17‑3: Download Interface Parameters
|
Parameter |
Definition |
|
uri |
The actual URI used for the download. |
|
tokens |
A string array of tokens used in the AppConfig file (see the example in the previous section). The token array may allow a zero-length string array to be passed in the event that no tokens are provided. The current document's filename is always passed to the download method as a separate token, so that if the ResolveReference node has three tokens, the actual number of tokens provided to the download method will be four. |
|
returnContentType |
The content type of the downloaded stream that the method is returning to Quark XML Author. |
|
alternateText |
An optional parameter which can be used exclusively for image references; allows Quark XML Author to assign and display an alternate text value for the image. |
The method must return a stream of the downloaded content.
Here is a very simple download() example:
namespace fullNamespaceOftheClass
{
public class Tritus
{
public Stream download(string url, string[] tokens, out string returnContentType)
{
//Using the first Reference node as an example..
string webserviceURL = tokens[0].Split('=')[1]]; //WSDL location
string cred = tokens[1].Split('=')[1]]; //use windows credentials
//get credentials for access to the CMS
ICredentials credentials = CredentialCache.DefaultCredentials; //since the token[1] says gets windows Credentials
Tritus.CMS.WebServices service = new Tritus.CMS.WebServices();
service.Url = webserviceURL;
service.Credentials = credentials;
//The url that comes in is the actual URL being resolved by Quark XML Author. Let’s say it’s of the following form:
//http://hyperbole.hyperactive.net/Documents?objId=x-en-tritus:TT0000000000509154:0000:2.
//We want to pull the objId from the URL and use it in the GetObject() web service call.
string objId = "x-en-tritus:TT0000000000509154:0000:2";
//Have some sort of UI to see if user wants it checked out, referenced OR a copy. ALternately this information can come directly from the URL itself.
//For example, there can be 3 seperate URLS - Edit(..?objId=x-en-tritus:TT0000000000509154:0000:2&type=edit). , Copy(..?objId=x-en-tritus:TT0000000000509154:0000:2&type=copy), Reference(..?objId=x-en-tritus:TT0000000000509154:0000:2&type=reference)
bool checkout= false;
bool readonly = true;
stream content = service.GetObject(objId, checkout, readonly, out contentType);
returnContentType = contentType; //Before returning, make sure the returnContent mimetype is set, for ex:- text/xml, image/jpg etc.
if(returnContentType == "text/xml" && readonly)
{
System.IO.StreamReader sr = new System.IO.StreamReader(content, Encoding.UTF8); //Assuming encoding as UTF-8
string fileContents = sr.ReadToEnd();
sr.Close();
XmlDocument doc = new XmlDocument();
doc.LoadXml(fileContents);
//if the url is dropped on reference links instead of on "empty", there is no need to perform the next step of tagging elements as read-only.
//Any content within the reference is automatically tagged as read-only within the Quark XML Author UI and stripped off when the document is serialized
//leaving behind a reference container.
XmlAttribute accessAttr = doc.CreateAttribute("inv", "access", "urn:xpressauthor:xpressdocument");
accessAttr.Value = "read-only";
doc.DocumentElement.Attributes.Prepend(accessAttr);
//Assign this attribute to every node recursively.
//The fragment should have some CMS attributes (at the very least it should have the id which will help Quark XML Author identify it as a CMS fragment and NOT a local fragment)
writer.Write(doc.OuterXml);
writer.Close();
return new MemoryStream(Encoding.UTF8.GetBytes(doc.DocumentElement.OuterXml));
}
else
return content; //For all other content, return as is. Quark XML Author has to support the incoming content type at the current location.
}
Example 1: Drag and Drop External Content
Consider a simple use case situation: an existing Quark XML Author document is open and we want to drag an object from the Tritus CMS into the document. The URL for the object has the following format:
http://hyperbole.hyperactive.net/Documents?objId=x-en-tritus:TT0000000000509154:0000:2.
The URL being dropped is matched against all possible Reference patterns defined in the AppConfig. The first matching Reference node is selected (in our example above, the first Reference node) and its corresponding download() method is invoked with the dropped URL and any other tokens specified in the Reference node. The download needs to communicate with the CMS and get the requested object. Once the object is downloaded, the contentType of the downloaded content has to be assigned and the downloaded object has to be passed back to Quark XML Author as a stream.
Once Quark XML Author receives the stream, depending on the returned content's contentType, it determines whether this is an XML fragment or image content. If this is an XML fragment, Quark XML Author checks to see if that fragment is insertable at the given location. If there are multiple contexts of insertion (for example, if a table is dragged on an insertable, and there are two possible tables that can be inserted—one as a child of the Section and the other as a child of the Section's parent, Chapter), the user is shown a context menu that allows the user to choose the correct context of information. If the downloaded XML fragment cannot be inserted at the dragged location or is not XML, an error dialog is shown to the user and the fragment is discarded. Once the fragment is inserted and attached to the document, any CMS attributes present in the fragment are preserved within the document.
If Quark XML Author receives any other content (other than contentType=text/xml), at least one of the insertable elements defined for the location of the drop must support the same mimetype. For example, if the returning stream's content type is image/jpeg, there has to be at least one insertable at the drop position that supports the image/jpeg format. See section 14.7.1.1 for more information on mimetypes that can be associated with Element definitions.
Example 2: Using Paste to Insert External Content
A paste operation can be performed as well. The user can copy the actual URL of the object onto the clipboard by some means (for example, browsing to the object in Internet Explorer, right-clicking, and selecting Copy Shortcut) and right click on the appropriate Empty location in a Quark XML Author document. If the downloaded fragment is insertable at that position, the context menu will contain a Paste element name menu item (where element name is the friendly name of the object as defined in the Quark XML Author Structure) along with other insertables for that location. If the downloaded fragment cannot be pasted into that location, no Paste menu option appears. Alternately, the user may right-click on a Reference element that matches the downloaded fragment type (not the Empty location) and click Assign reference on the context menu. The Reference element’s href attribute will be assigned the URL of the downloaded fragment.
This paste is an alternative implementation to the drag-drop scenario above but the implementation is nearly the same. The only difference in case of Copy and Paste is that once a valid URL is copied to the clipboard, the fragment is also downloaded and copied to the clipboard along with the original URL, so the user can actually click around the document to determine the right insertion spot in the document. The fragment remains on the clipboard until another copy operation is performed.
Example 3: Opening a Document Referencing External Content
When Quark XML Author opens a document that references external content, it recognizes any element that is a reference container from its definition in the Quark XML Author Structure and uses the element’s href attribute to invoke the appropriate download() method and display the content.
For example, suppose a document being opened has the following structure:
<Document>
<Section>
<Title> Section name </Title>
<ComponentReference href="http://hyperbole.hyperactive.net/Documents?objId=x-en-tritus:TT0000000000509154:0000:2.">
</Section>
</Document>
In this example, ComponenteReference is a reference element; its href attribute points to an external object. Quark XML Author displays that content in-line. If the object cannot be downloaded, the rest of the document continues to open and the reference container is flagged with an error label in the Quark XML Author document.
