Custom DITA-OT parameters for custom PDF

[Patrik]

Hi,

I successfully created my own pdf customization and also added custom parameters like this:
in plugin.xml I added

Code: Select all

<feature extension="dita.conductor.pdf2.param" file="insert-parameters.xml"/>

and insert-parameters.xml looks like this:

Code: Select all

<dummy>

    <param name="my-param" expression="#CCCCFF"/>

</dummy>

This works but now I'd like to make these parameters configurable in my transformation scenario for my custom transtype. Is this possible?

Thanks and regards,
Patrik

[xephon]

Hi Patrik,

this is indeed possible. You should read Passing parameters to existing XSLT steps. Take a look at the ~/dita-ot-2.x.x/plugins/org.dita.pdf2/build.xml and search for args. This should help you.

Depending on what you are trying to achieve, it is also possible to generate new XSL-Stylesheets during the publication process using parameters. If you are interested in doing that, take a look at org.doctales.pdf (development branch). The purpose of this plugin (early development stage) is exactly that. Creating a huge config file and generating stylesheets based on the chosen settings and parameters. You're welcome to contribute.

Greetings,
Stefan

[Patrik]

Hi Stefan,

thanks fot the answer, but I couldn't see how it should help me.

As I wrote I have alreay successfully added a parameter into the PDF2-XSLT-Stylesheet (e.g. "my-param") and I'm also evaluating it in my pdf customization. But so far it is passed only with the contant value "#CCCCFF". And I want to make it configurable as parameter in the oxygen transformation scenario.

I probably have to change the parameter declaration to something like

Code: Select all

<param name="my-param" expression="${my-param}" if="my-param"/>

to fillit with the value of an ant property. But how do I define an ant-property in such a way that oxygen will allow me to set a value for it?

Thanks and regards,
Patrik

[xephon]

Hi Patrik,

please have a look at this build.xml:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>



<target name="reveal" description="Generate a reveal.js based web presentation.">

    <antcall target="integrate"/>

    <ant antfile="${dita.dir}\build.xml">

        <!-- The input DITA map. -->

        <property name="args.input" value="[YOURMAP].ditamap"/>



        <!-- The output directory. -->

        <property name="output.dir" value="out/reveal"/>



        <!-- The transformation type. -->

        <property name="transtype" value="reveal"/>





        <!-- OPTIONAL PROPERTIES -->



        <!-- Path to custom template file -->

        <property name="reveal.css" value="my-template.css"/>



        <!--

            The template. Possible values:

            "default", "sky", "beige", "simple",

            "serif", "night", "moon", "solarized"

            If you use a custom template, the name

            of the template is the filename without its

            extensions, e.g. "my-template"

        -->

        <property name="args.reveal.css" value="default"/>



        <!-- Display controls in the bottom right corner. -->

        <property name="args.reveal.controls" value="true"/>



        <!-- Display a presentation progress bar. -->

        <property name="args.reveal.progress" value="true"/>



        <!-- Display the page number of the current slide. -->

        <property name="args.reveal.slidenumber" value="false"/>



        <!-- Push each slide change to the browser history. -->

        <property name="args.reveal.history" value="false"/>



        <!-- Enable keyboard shortcuts for navigation. -->

        <property name="args.reveal.keyboard" value="true"/>



        <!-- Enable the slide overview mode. -->

        <property name="args.reveal.overview" value="true"/>



        <!-- Enable the vertical centering of slides. -->

        <property name="args.reveal.center" value="true"/>



        <!-- Enable touch navigation on devices with touch input. -->

        <property name="args.reveal.touch" value="true"/>



        <!-- Loop the presentation. -->

        <property name="args.reveal.loop" value="false"/>



        <!-- Change the presentation direction to be right-to-left. -->

        <property name="args.reveal.rtl" value="false"/>



        <!-- Turn fragments on and off globally. -->

        <property name="args.reveal.fragments" value="true"/>



        <!--

            Flags if the presentation is running in an embedded mode,

            i.e. contained within a limited portion of the screen.

        -->

        <property name="args.reveal.embedded" value="false"/>



        <!--

            Number of milliseconds between automatically proceeding to the

            next slide, disabled when set to 0, this value can be overwritten

            by using a data-autoslide attribute on your slides.

        -->

        <property name="args.reveal.autoslide" value="0"/>



        <!-- Stop auto-sliding after user input. -->

        <property name="args.reveal.autoslidestoppable" value="true"/>



        <!-- Enable slide navigation via mouse wheel. -->

        <property name="args.reveal.mousewheel" value="false"/>



        <!-- Hide the address bar on mobile devices. -->

        <property name="args.reveal.hideaddressbar" value="true"/>



        <!-- Open links in an iframe preview overlay. -->

        <property name="args.reveal.previewlinks" value="false"/>



        <!--

            Set the transition style. Possible values:

            "default", "cube", "page", "concave",

            "zoom", "linear", "fade", "none"

        -->

        <property name="args.reveal.transition" value="default"/>



        <!--

            Set the transition speed. Possible values:

            "default", "fast", "slow"

        -->

        <property name="args.reveal.transitionspeed" value="default"/>



        <!--

            Set the transition style for full page

            slide backgrounds. Possible values:

            "default", "none", "slide", "concave", "convex", "zoom"

        -->

        <property name="args.reveal.backgroundtransition" value="default"/>



        <!-- Set the number of slides away from the current that are visible. -->

        <property name="args.reveal.viewdistance" value="3"/>



        <!--

            Set the parallax background image.

            Example:

            "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"

        -->

        <property name="args.reveal.parallaxbackgroundimage" value=""/>



        <!--

            Set the parallax background size.

            Example:

            "2100px 900px"

        -->

        <property name="args.reveal.parallaxbackgroundsize" value=""/>

    </ant>

</target>

For example, the property args.reveal.css in the build.xml overrides the default value of the XSL parameter <xsl:param name="reveal.css" select="'black'"/> in the reveal.xsl styleheet.

You can also do this via an Oxygen transformation scenario. Open the parameters tab of a transformation scenario and click the New button. Enter args.reveal.css as name and sky as value.

Greetings,
Stefan

[Patrik]

Hi Stefan,

Silly me... All the time I was expactin oXygen to automatically add my own parameter to the list. Simply by adding a new parameter manually with the appropriate name it's working fine now. Thanks again.

However, I'm still wondering if there is a way to declare my parameter with a description and default value in a way that Oxygen will automatically list it for my custom transtype!? I vaguely recall that there was some discussion about this at the DIT-OT day.

Regards,
Patrik

[Radu]

Hi Patrik,

About this question:

However, I'm still wondering if there is a way to declare my parameter with a description and default value in a way that Oxygen will automatically list it for my custom transtype!

Indeed, a description of how the plugin.xml should be annotated is in my presentation from DITA OT Day:

https://www.oxygenxml.com/events/2015/D ... tadata.pdf

Also as a hands-on example, if you open the plugin.xml from a DITA OT 2.x distribution:

DITA-OT2.x\plugins\org.dita.pdf2\plugin.xml

it has content like this:

Code: Select all

<plugin id="org.dita.pdf2">

..............................

  <transtype name="pdf pdf2" desc="PDF">

  ...................................

    <param name="args.artlbl" desc="Specifies whether to generate a label for each image; the label will contain the image file name." type="enum">

      <val>yes</val>

      <val default="true">no</val>

    </param>

  ......................

  </transtype>

....................................

</plugin>

We also have a new file template for creating a DITA OT plugin.xml which shows in the content completion the allowed elements and values for this kind of metadata.

Regards,
Radu

[Patrik]

Hi Radu,

thanks, but I don't have a transtype element since I'm only customizing the existing pdf2 transtype. My plugin.xml looks like this:

Code: Select all

<plugin id="org.dita-semia.pdf">

	<require plugin="org.dita.pdf2"/>

	<feature extension="dita.conductor.transtype.check" value="dita-semia-pdf"/>

	<feature extension="dita.transtype.print" 			value="dita-semia-pdf"/>

	<feature extension="dita.conductor.target.relative" file="integrator.xml"/>

	<feature extension="dita.conductor.pdf2.param" 		file="insert-parameters.xml"/>

</plugin>

And accoding to the schema (dita-ot/plugin.rnc) there is no other place where I could add a param element!?

Thanks and regards,
Patrik

[Radu]

Hi Patrik,

If you are using for validation the plugin.rnc from a DITA OT 2.x installation, the plugin.xml can have a new "transtype" element inside it:

Code: Select all

<plugin id="org.dita-semia.pdf">

    <require plugin="org.dita.pdf2"/>

    <feature extension="dita.conductor.transtype.check" value="dita-semia-pdf"/>

    <feature extension="dita.transtype.print"          value="dita-semia-pdf"/>

    <feature extension="dita.conductor.target.relative" file="integrator.xml"/>

    <feature extension="dita.conductor.pdf2.param"       file="insert-parameters.xml"/>

    <transtype name="dita-semia-pdf" extends="pdf2" desc="My custom PDF transformation">

        <param name="extraParam" type="enum" desc="My extra parameter">

            <val default="true">yes</val>

            <val>no</val>

        </param>

    </transtype>

</plugin>

The transtype element and all its contents is metadata, it is ignored by the integrator process. But Oxygen picks up this metadata and will present the descriptions, custom parameters and their values (along with the parameters from the base extended transtype) when you create a new DITA OT scenario of your custom type.
Such metadata can also be added to the plugin.xml from a DITA OT 1.8 installation because the integration process just ignores any element that it does not know of.

Regards,
Radu

[Patrik]

Hi Radu,

I didn't realize that transtype itself is metadata as well. Thanks, I will try that.

Regards,
Patrik

[Patrik]

After adding the transtype element is my parameters are listed now. Really nice solution! Thanks again.

Patrik

[Frank Ralf]

Hi Radu,

I'm trying to add a parameter to my custom PDF Review plugin.

build_reviews.xml
I've added the following line to build_reviews.xml:

Code: Select all

<param name="ct.change-bar.color" expression="$(ct.change-bar.color)" if="ct.change-bar.color" />

The value of the parameter gets passed to the XLST script but the expression is not resolved with the settings from the transformation scenario. A literal value like this does work:

Code: Select all

<param name="ct.change-bar.color"  expression="red" />

plugin.xml
I've also added the following line to plugin.xml but these changes don't show up anywhere in the transformation scenario settings. Changes to the already existing parameters also don't show in the transformation scenario settings.

Code: Select all

<param name="ct.change-bar.color" desc="Change bar color for Oxygen tracked changes, specified as a plain color (i.e. black, red, blue), or with a hexadecimal equivalent (i.e. #FFFFFF).  The default value is 'green'." type="string">

Re-running the integrator script doesn't help either. What am I missing here?

Best regards,
Frank

[Radu]

Hi Frank,

When Oxygen presents parameters in the "Parameters" list while editing a transformation scenario, it does not detect those parameters from the ANT build files. It would be wrong to do so because most parameters in the build files are for internal use and are not intended to be set from the outside.
But if you look in the plugin.xml, it has something like:

Code: Select all

<transtype name="pdf" desc="PDF">
    <param name="show.changes.and.comments" desc="Show Oxygen track changes and comments" type="enum">
      <val desc="No" default="true">no</val>
      <val desc="Yes">yes</val>
    </param>
    <param name="ct.insert.color" desc="Insertion color for Oxygen tracked changes, specified as a plain color (i.e. red, yellow, blue), or with a hexadecimal equivalent (i.e. #FFFFFF).
      The default value is 'blue'." type="string"/>
    <param name="ct.delete.color" desc="Deletion color for Oxygen tracked changes, specified as a plain color (i.e. red, yellow, blue), or with a hexadecimal equivalent (i.e. #FFFFFF).
      The default value is 'red'." type="string"/>
    <param name="ct.comment.bg.color" desc="Comment background color for Oxygen tracked changes, specified as a plain color (i.e. red, yellow, blue), or with a hexadecimal equivalent (i.e. #FFFFFF).
      The default value is 'yellow'." type="string"/>
  </transtype>

That is the place where the public parameters are declared and from where Oxygen picks up parameters shown in the Parameters list.
So you should also declare the parameters in the plugin.xml.

https://www.oxygenxml.com/doc/versions/ ... stype.html
https://www.dita-ot.org/dev/topics/plug ... aid-title1

Regards,
Radu

[Frank Ralf]

Hi Radu,

Sorry for the late reply. I will have another look and try your suggestion.

Best regards,
Frank