Documentation Center

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

Plugin configuration parameters
ParameterRequiredDefault valueAllowed valuesDescription
ObjectTypesToProcessYesbinary, page, toc, publication, indexWhich type of objects in the __packages.xml should be parsed to look for file references. Multiple types need to be separated with ", " (comma+space).
ConvertElementsHavingAttributesNo[empty]Valid attribute namesThe 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.
ConvertValuesForAttributesNo[empty]Valid attribute namesThe 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.
Input expected in the context.Items collection
Item KeyRequiredDefault valueItem Value TypeDescription
TransportPackageRootDirectoryYesstringThe root transport package folder (typically ...\Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP).
ExtendedOverallPackageObjectFilePathYesstringFile 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

Changes made to the file system:
  • The XML attribute values of the parsed files that match one of the OriginalFile attributes of Object in the __packages files are replaced with the corresponding ish:xxx-yyy-zzz identifier (and potentially the attribute's XML element name is renamed to tcdl:Image or tcdl: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 DitaDeliveryConvertRefs does the following:
  • The plugin first builds a list with all the Content attributes of all the Object entries in the __packages.xml file that match one of the types configured in the ObjectTypesToProcess parameter. That file is provided in the Items collection of the context with the key ExtendedOverallPackageObjectFilePath.
  • Every file in the list that matches the given ObjectTypesToProcess is loaded as XML in memory, parsed, and the attribute values of attributes matching the ConvertElementsHavingAttributes or ConvertValuesForAttributes parameters are gathered.
  • When the attribute value matches an OriginalFile entry in the __packages.xml file, the following happens:
    • When the attribute name is in the ConvertElementsHavingAttributes parameter:
      • If the XML element name having the attribute is img, the element name is replaced with tcdl:Image and a type ish:Image attribute, otherwise the element name is replaced with tcdl:Link with type ish:Page or ish:Binary.
      • If the original XML element name differs from img and a, the original element name is kept in a htmlelementname attribute.
      • If the original attribute value is of the form GUID-X.html#SECTION1, the part after the # is kept in a addanchor attribute.
      • In all cases, the attribute name is changed to ref and the attribute value is replaced with the Id attribute of the matching Object in the __packages.xml file.
      • All other attributes names and values are kept.
    • When the attribute name is in the ConvertValuesForAttributes parameter:
      • The attribute value is replaced with the Id attribute of the matching Object in the __packages.xml.
  • When the attribute value does not match an OriginalFile entry in the __packages.xml file, the following happens:
    • When the attribute value starts with http:// or https://, the value is kept as is and no conversion is done.
    • When the attribute value does not start with http:// or https://, the value ish:<puboutputid>-0-16 is used to indicate the object does not exist (yet) and the same conversion rules are used that happen if a matching OriginalFile entry in the __packages.xml was found.
  • Eventually the changed file content is saved to the same file name.