Metadata

In the merged map file, the metadata section is placed inside the <oxy:front-page> element. This is different from the original placement in the map or bookmap (after the title), but allows for the usage of information from it in the title page.

<bookmap xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
  xmlns:opentopic-index="http://www.idiominc.com/opentopic/index" cascade="merge" 
    class="- map/map bookmap/bookmap "
  ditaarch:DITAArchVersion="1.3" >
    
  <oxy:front-page xmlns:oxy="http://www.oxygenxml.com/extensions/author">
       
   <bookmeta xmlns:dita-ot="http://dita-ot.sourceforge.net/ns/201007/dita-ot"
     class="- map/topicmeta bookmap/bookmeta ">
     <author class="- topic/author ">Howe Tuduit</author>
     <bookid class="- topic/data bookmap/bookid ">
       <isbn class="- topic/data bookmap/isbn ">071271271X</isbn>
       <booknumber class="- topic/data bookmap/booknumber ">SG99-9999-00</booknumber>
        <maintainer class="- topic/data bookmap/maintainer ">
        <organization class="- topic/data bookmap/organization ">ACME Tools</organization>
        <person class="- topic/data bookmap/person "/>
       </maintainer>
     </bookid>
     <bookrights class="- topic/data bookmap/bookrights ">
        ...
         <bookowner class="- topic/data bookmap/bookowner ">
  <organization class="- topic/data bookmap/organization ">ACME Tools, Inc.</organization>
         </bookowner>
     </bookrights>
        </bookmeta>
        
        <oxy:front-page-title>
            ...
...

<div 
    class="- map/map bookmap/bookmap bookmap" ... >
    
   <div class=" front-page/front-page front-page">
       
   <div 
     class="- map/topicmeta bookmap/bookmeta boometa">
     <div class="- topic/author author">Howe Tuduit</div>
     <div class="- topic/data bookmap/bookid bookid">
       <div class="- topic/data bookmap/isbn isbn">071271271X</div>
       <div class="- topic/data bookmap/booknumber booknumber">SG99-9999-00</div>
       <div class="- topic/data bookmap/maintainer maintainer">
          <div class="- topic/data bookmap/organization organization">ACME Tools</div>
          <div class="- topic/data bookmap/person person"/>
        </div>
      </div>
      <div class="- topic/data bookmap/bookrights bookrights">
        ...
         <div class="- topic/data bookmap/bookowner bookowner">
              <div class="- topic/data bookmap/organization organization">
                                          ACME Tools, Inc.
              </div>
         </div>
       </div>
     </div>
        
     <div class=" front-page/front-page-title front-page-title">
            ...
...

<map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
    xmlns:opentopic-index="http://www.idiominc.com/opentopic/index" 
          cascade="merge" class="- map/map "
    ditaarch:DITAArchVersion="1.3">
    ...
    
<oxy:front-page xmlns:oxy="http://www.oxygenxml.com/extensions/author">
    
  <topicmeta class="- map/topicmeta ">
      <author class="- topic/author ">Dan C</author>
      <metadata class="- topic/metadata ">
         <prodinfo class="- topic/prodinfo ">
             <prodname class="- topic/prodname ">oXygen PDF CSS DITA Plugin</prodname>
         </prodinfo>
      </metadata>
      <audience class="- topic/audience "/>
  </topicmeta>
...

<div xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
    xmlns:opentopic-index="http://www.idiominc.com/opentopic/index" 
          cascade="merge" class="- map/map "
    ditaarch:DITAArchVersion="1.3">
    ...
    
<div class=" front-page/front-page front-page">
    
  <div class="- map/topicmeta topicmeta">
      <div class="- topic/author author">Dan C</div>
      <div class="- topic/metadata metadata">
         <div class="- topic/prodinfo prodinfo">
             <div class="- topic/prodname prodname">oXygen PDF CSS DITA Plugin</div>
         </div>
      </div>
      <div class="- topic/audience audience"/>
  </topicmeta>
...

The [PLUGIN_DIR]/css/print/p-meta.css file contains the rules that extract metadata.

<map>
    ...
    <topicmeta>
        ...
        <audience type="programmer" job="programming" experiencelevel="expert"/>

To collect the @type attribute, add the following in your customization CSS:

*[class ~= "map/map"] > *[class ~= "map/topicmeta"] > *[class ~= "topic/audience"] {
    -oxy-pdf-meta-custom: "Audience" attr(type);
}

-oxy-pdf-meta-custom: "Audience" attr(type), "Job" attr(job)

The metadata is displayed in the Custom tab of the Document Properties dialog box from Acrobat Reader:

The header and footer are composed of page margin boxes that can be populated with static text by using string-sets.

*[class ~= "front-page/front-page"] > 
  *[class ~= "map/topicmeta"] > 
    *[class ~= "topic/critdates"] > 
      *[class ~= "topic/created"]{
    string-set: mapcreated attr(date);
}
    

@page front-page {
     @top-center {
          content: "Created: " string(mapcreated);
     }
}

This topic explains how to present metadata information that is normally hidden in the published output. For the example that follows, this will be the revision history list:

<task id="task_3ml_qm3_rf">
    <title>Removing the battery</title>
    <shortdesc/>
    <prolog>
        <change-historylist>
            <change-item>
                <change-revisionid>abd3</change-revisionid>
                <change-completed>Build no 1.</change-completed>
            </change-item>
            <change-item>
                <change-revisionid>bc72</change-revisionid>
                <change-completed>Build no 2.</change-completed>
            </change-item>
        </change-historylist>
....

*[class~="topic/prolog"]:has(*[class~="relmgmt-d/change-historylist"] ){
    display:block;
    color:inherit;
    font-size:1rem;
    width:auto;
    height:auto;
}

*[class~="topic/prolog"]:has(*[class~="relmgmt-d/change-historylist"]) > *:not([class~="relmgmt-d/change-historylist"]) {
    display:none;
}

*[class~="relmgmt-d/change-item"],
*[class~="relmgmt-d/change-revisionid"],
*[class~="relmgmt-d/change-completed"] {
    display:block;   
}

*[class~="relmgmt-d/change-historylist"] {
    font-size:1rem;
    border: 3pt solid silver;
    padding: 0.5em;
}
*[class~="relmgmt-d/change-historylist"]:before {
    content: "Revision History:";
    font-weight:bold;
}

/* Example of styling some of the descendends of the history list. */
*[class~="relmgmt-d/change-item"] {
    margin:1em;
}
*[class~="relmgmt-d/change-revisionid"]:before {
    content: "Revision ID: " !important;
    font-weight:bold;
}
*[class~="relmgmt-d/change-completed"]:before {
    content: "Completed: "  !important;
    font-weight:bold;
}

In the output, the history list is now visible:

The keywords defined in the prolog sections of topics are automatically collected and set as PDF keywords. These are shown by the readers in the PDF document properties window.

If you need to remove them, you can use the following CSS snippet in your customization CSS:

:root {
	-oxy-pdf-meta-keywords:"";
}

To change them, if you have a hard-coded list, you just enumerate each of them in the property content, separating them with comma:

:root {
	-oxy-pdf-meta-keywords:"alpha, beta, gamma";
}

If you need to extract them by other criteria from the merged map, you can use the oxy_xpath() function instead of the hard-coded list.

The title defined in the PDF reader is automatically collected from the map's main title.

If you want to display the map name instead of the title, you can use one of the following rules in your customization CSS:

/* 
 * Titles (maps).
 */
*[class ~= "front-page/front-page-title"] *[class ~= "topic/title"]:not([class ~= 'bookmap/booktitle']) {
    -oxy-pdf-meta-title: unset;
}

/* 
 * Titles (bookmaps).
 */
*[class ~= "front-page/front-page"] *[class ~= "bookmap/booktitle"] > *[class ~= "bookmap/mainbooktitle"] {
    -oxy-pdf-meta-title: unset;
}

The <title> element of a bookmap is quite complex and contains elements for the book library and an alternate title:

 <booktitle>
    <booklibrary>Retro Tools</booklibrary>
    <mainbooktitle>Main Book Title</mainbooktitle>
    <booktitlealt>Book Title Alternative</booktitlealt>
  </booktitle>

For the publication title, the built-in CSS uses only the content of the <mainbooktitle>. If you want to collect all of the text from the <booktitle>, you can add the following rule to your customization CSS:

:root {
    -oxy-pdf-meta-title: oxy_xpath('(//*[contains(@class, "bookmap/booktitlealt")])[1]/text()');
    -oxy-pdf-meta-description: "";
}

An XPath expression is used to collect all the <booktitlealt> elements from the merged map, select the first one, then use its text.

The built-in CSS uses the <booktitlealt> as the PDF description. In the example above, this property is cleared since it was moved as a title.

To use a key value in the CSS, the key must be referenced from the content (either a topic or map).

If you do not have it referenced, you may force a reference by using the <topicmeta> or <bookmeta> section of your map and a <data> element. This has no effect on the published content, but allows the CSS rules to use its content.

  <bookmeta>
    ....
    <data keyref="my_key"/>
    ....
  </bookmeta>

This is expanded in the merged HTML file to:

<div class="- map/topicmeta bookmap/bookmeta topicmeta bookmeta">
	...
	<div keyref="my_key" class="- topic/data data">
		<div class="- topic/keyword keyword">KEY VALUE</div>
	</div>
	...
</div>

Suppose that you need the expanded key value in the footer of the publication. You can define a string-set on this data element:

*[class ~= "topic/data"][keyref="my_key"] {
	string-set: key-string content(text);
}
@page {	
	@bottom-left {
		content: "My key is: " string(key-string) !important;		
	}
}

Or you can use the value from a :before pseudo-element, like the one for the title:

*[class ~= "topic/title"]:before {
	content: oxy_xpath("//*[contains(@class, 'topic/data')][@keyref = 'my_key']//text()");
}

Another use-case is to use the key as a source for a custom PDF document property:

*[class ~= "topic/data"][keyref="my_key"] {
	-oxy-pdf-meta-custom: attr(keyref) content(text);
}

The PDF document may contain settings for the PDF Viewer. This helps to make the viewing experience common for all of the readers. For example, you can specify the zoom level that the document is presented, or whether the outline view should be displayed.

There are several CSS properties you can use. These properties should be set on the root element. If they are set on multiple elements, the first one will be taken into account.