Name

cx:css-formatter — Format a document using CSS.

Synopsis

<p:declare-step type="cx:css-formatter" xmlns:cx="http://xmlcalabash.com/ns/extensions">
     <p:input port="source" primary="true"/>
     <p:input port="parameters" kind="parameter"/>
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="css" required="false"/>                       <!-- ListOfURIs -->
     <p:option name="content-type"/>                               <!-- string -->
</p:declare-step>

Description

This method calls the underlying CSS formatter. Two formatters are supported, Antenna House and Prince.

XML Calabash does not provide a license for either of these products. You must have the relevant classes on your classpath in order to use them. You may also need to purchase a license.

API Change in XML Calabash 1.1.7

The signature for this step was changed in XML Calabash version 1.1.7. Previously, the CSS stylesheet(s) were specified as input documents on a port. Unfortunately:

  1. The underlying implementations expect them as URIs, not documents.

  2. Writing the documents out as temporary files to create URIs naturally changes the base URIs of the CSS stylesheets.

  3. Changing the base URIs breaks any @import URIs.

  4. CSS provides no mechanism for specifying a different base URI.

Therefore, the new signature has a css option that accepts a space-delimited list of URIs. If you want to construct CSS dynamically in the pipeline, use p:store to write the CSS to the filesystem, make sure this step depends on that store step, and use the resulting store URI.

For backwards compatibility reasons, XML Calabash will continue to accept the old signature for some time.

Antenna House Formatter

To specify the Antenna House Formatter, use the value com.xmlcalabash.util.CssAH for the css-processor configuration item.

The following parameters are supported:

  • OptionsFileURI

  • ExitLevel

  • EmbedAllFontsEx

    The accepted values are “part”, “base14”, and “all”.

  • ImageCompression

  • NoAccessibility

  • NoAddingOrChangingComments

  • NoAssembleDoc

  • NoChanging

  • NoContentCopying

  • NoFillForm

  • NoPrinting

  • OwnersPassword

  • TwoPassFormatting

For further information on the value of these parameters and their meanings, consult the Antenna House documentation.

Prince Formatter

To specify the Prince Formatter, use the value com.xmlcalabash.util.CssPrince for the css-processor configuration item.

The following parameters are supported:

  • exePath

    The exePath must be specified to identify the location of the Prince formatter. It can also be specified using the com.xmlcalabash.css.prince.exepath Java system property.

  • baseURL

  • compress

  • debug

  • embedFonts

  • encrypt

  • keyBits

  • userPassword

  • ownerPassword

  • disallowPrint

  • disallowModify

  • disallowCopy

  • disallowAnnotate

  • fileRoot

  • html

  • httpPassword

  • httpUsername

  • httpProxy

  • inputType

  • javascript

  • log

  • network

  • subsetFonts

  • verbose

  • XInclude

  • scripts

    Prince accepts an arbitrary number of JavaScript files. In order to support that in a parameter, this value is treated as a space-delimited list of URIs.

For further information on the value of these parameters and their meanings, consult the Prince documentation.

As of Prince 9.0, there's still a bug that prevents the formatter from producing error and warning messages. Your best bet until this bug is fixed is to specify a log parameter.

Implementation

This step is implemented by the xmlcalabash1-print module. The jar file from that project must be in the class path in order to use this step.

Module Compatability Warning

As a consequence of the signature change in XML Calabash version 1.1.7, described above, XML Calabash version 1.1.7 can only be used with the XML Calabash Print module version 1.1.4 or later. (And conversely, earlier versions of XML Calabash can only be used with module version 1.1.3 or earlier.)

Apologies for the inconvenience.