IPublishPostProcessPlugin - DitaDeliveryConvertRefs
Parses XML files and replaces the file references with the corresponding ish:xxx-yyy-zzz identifier value found in the __packages.xml. Optionally, it renames the XML element having one of the attributes configured in ConvertElementsHavingAttributes to tcdl:Link or tcdl:Image.
Plugin Input
| Parameter | Required | Default value | Allowed values | Description |
|---|---|---|---|---|
| ObjectTypesToProcess | Yes | binary, page, toc, publication, index | Which type of objects in the __packages.xml should be parsed to look for file references. Multiple types need to be separated with ", " (comma+space). | |
| ConvertElementsHavingAttributes | No | [empty] | Valid attribute names | The attribute names that need to be read from the XML in order to check whether their attribute value matches one of the Object OriginalFile entry in the __packages.xml. If the attribute value matches it is replaced with the Id of the Object and the XML element name is renamed to tcdl:Link or tcdl:Image. |
| ConvertValuesForAttributes | No | [empty] | Valid attribute names | The attribute names that need to be read from the XML in order to check whether their attribute value matches one of the Object OriginalFile entry in the __packages.xml. If the attribute value matches it is replaced with the Id of the Object. |
context.Items collection
| Item Key | Required | Default value | Item Value Type | Description |
|---|---|---|---|---|
| TransportPackageRootDirectory | Yes | string | The root transport package folder (typically ...\Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP). | |
| ExtendedOverallPackageObjectFilePath | Yes | string | File path of the XML that contains an overview of all the files that need to be transported to Dynamic Delivery (typically full file path to __packages.xml). |
The files that need to be parsed have to be present in the folder provided in the RootWorkDirectory property of the context and should contain XML.
Plugin Outcome
- The XML attribute values of the parsed files that match one of the
OriginalFileattributes ofObjectin the __packages files are replaced with the correspondingish:xxx-yyy-zzzidentifier (and potentially the attribute's XML element name is renamed totcdl:Imageortcdl:Link).
Values set in the context as a result: None.
Values set in the context.Items collection as a result: None.
plugin name="ISHDITADELIVERYCONVERTPAGEREFS" and name="ISHDITADELIVERYCONVERTNAVREFS" example
<plugin name="ISHDITADELIVERYCONVERTPAGEREFS" handler="DitaDeliveryConvertRefs">
<description>Parses files of type "page" in the "TP\ALL" folder, and replaces "a href=GUID-X", "img src=GUID-X", "object data=GUID-X", etc. elements to "tcdl:Link" or "tcdl:Image" elements with a "ref=ish:xxx-yyy-zzz" (only if the attribute value matches the OriginalFile in the __packages.xml) and saves the changes to the same filename again
</description>
<initialize>
<parameters>
<parameter name="ObjectTypesToProcess">page</parameter>
<parameter name="ConvertElementsHavingAttributes">href, src, data, cite, poster</parameter>
</parameters>
</initialize>
</plugin>
<plugin name="ISHDITADELIVERYCONVERTNAVREFS" handler="DitaDeliveryConvertRefs">
<description>Parses files of type "toc" or "index" in the "TP\ALL" folder, and replaces "ref" or "target" attribute values of the form "GUID-X" with "ish:xx-yy-zz" (only if the attribute value matches the OriginalFile in the __packages.xml) and saves the changes to the same filename again
</description>
<initialize>
<parameters>
<parameter name="ObjectTypesToProcess">toc, index</parameter>
<parameter name="ConvertValuesForAttributes">ref, href</parameter>
</parameters>
</initialize>
</plugin>
Example of a resulting page file
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" type="text/css" href="commonltr.css" class="stylesheet" />
<title>Saving names and numbers</title>
</head>
<body id="GUID-67F1627E-FFBA-4E03-A62D-F70030C52596">
<h1 class="title topictitle1" id="GUID-67F1627E-FFBA-4E03-A62D-F70030C52596__GUID-91208EF2-9DF8-4968-95C3-7B281273B8A0">Saving names and numbers</h1>
<div class="body taskbody">
<p class="shortdesc" />
<p class="p">Existing image: <tcdl:Image class="image refonly" type="ish:Image" ref="ish:39137-6312-16"/></p>
<p class="p">Unexisting image: <tcdl:Image class="image refunexists" type="ish:Image" ref="ish:39137-0-16"/></p>
<p class="p">Image on google: <img class="image refexternal" src="http://www.google.com/images/globe.jpg"/></p>
<p class="p">Image with alt text: <tcdl:Image class="image refonlywithtext" type="ish:Image" ref="ish:39137-6312-16">Globe image</tcdl:Image></p>
</p>
</div>
<div class="related-links">
<div class="familylinks">
<div class="parentlink">
<tcdl:Link class="link refonly" ref="ish:39137-6228-16" type="ish:Page" title="Save your contacts.">Contacts</tcdl:Link>
<tcdl:Link class="link refwithanchor" ref="ish:39137-6228-16" addanchor="Saving" type="ish:Page">Contacts (How to save)</tcdl:Link>
<tcdl:Link class="link refunexists" ref="ish:39137-0-16">Hyperlink to an unexisting topic</a>
<a class="link refexternal" href="https://www.google.com">Hyperlink to Google</a>
<tcdl:Link class="link refonlytobinary" ref="ish:39137-6312-16" type="ish:Binary">Hyperlink to an image</tcdl:Link>
</div>
</div>
</div>
</body>
</html>
Example of a resulting table of contents file
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" type="text/css" href="commonltr.css" class="stylesheet" />
<title>User Guide</title>
</head>
<body id="GUID-C9CA7357-CBA3-43B3-A4B2-B977AD1B7D1E">
<h1 class="title topictitle1">User Guide</h1>
<div>
<ul xml:lang="en" lang="en" class="map">
<naventry class="topicref existing1" ref="ish:39137-6229-16">
<title>Dear Customer</title>
<naventry class="topicref external" ref="http://www.google.com">
<title>For your safety</title>
</naventry>
</naventry>
<naventry class="topicref unexisting" ref="ish:39137-0-16">
<title>Your phone</title>
<naventry class="topicref existing2" ref="ish:39137-6228-16">
<title>Keys overview</title>
</naventry>
</naventry>
<naventry class="topicref existingwithanchor" ref="ish:39137-6229-16">
<title>Dear Customer</title>
</naventry>
</ul>
</div>
</body>
</html>
Plugin flow
- The plugin first builds a list with all the
Contentattributes of all theObjectentries in the __packages.xml file that match one of the types configured in theObjectTypesToProcessparameter. That file is provided in the Items collection of the context with the keyExtendedOverallPackageObjectFilePath. - Every file in the list that matches the given
ObjectTypesToProcessis loaded as XML in memory, parsed, and the attribute values of attributes matching theConvertElementsHavingAttributesorConvertValuesForAttributesparameters are gathered. - When the attribute value matches an
OriginalFileentry in the __packages.xml file, the following happens:- When the attribute name is in the
ConvertElementsHavingAttributesparameter:- If the XML element name having the attribute is
img, the element name is replaced withtcdl:Imageand atypeish:Imageattribute, otherwise the element name is replaced withtcdl:Linkwithtypeish:Pageorish:Binary. - If the original XML element name differs from
imganda, the original element name is kept in ahtmlelementnameattribute. - If the original attribute value is of the form GUID-X.html#SECTION1, the part after the
#is kept in aaddanchorattribute. - In all cases, the attribute name is changed to
refand the attribute value is replaced with theIdattribute of the matchingObjectin the __packages.xml file. - All other attributes names and values are kept.
- If the XML element name having the attribute is
- When the attribute name is in the
ConvertValuesForAttributesparameter:- The attribute value is replaced with the
Idattribute of the matchingObjectin the __packages.xml.
- The attribute value is replaced with the
- When the attribute name is in the
- When the attribute value does not match an
OriginalFileentry in the __packages.xml file, the following happens:- When the attribute value starts with
http://orhttps://, the value is kept as is and no conversion is done. - When the attribute value does not start with
http://orhttps://, the valueish:<puboutputid>-0-16is used to indicate the object does not exist (yet) and the same conversion rules are used that happen if a matchingOriginalFileentry in the __packages.xml was found.
- When the attribute value starts with
- Eventually the changed file content is saved to the same file name.