Skip to content
PDF

Rend

What is it?

The rendition extension package allows you to programmatically invoke a third party rendition engine to convert documents from one format to another, the most common use case is to convert HTML documents to PDF documents. Using the rendition extension package, you will be able to convert documents in real time and without interrupting the script execution flow.

The installation procedure for the rendition extension package isn't different from any other extension package, although it requires a couple of additional steps to be completed.

Install the third party rendition engine

The CS Rendition Extension package only provides the API to interface with a third party engine capable of converting documents.

This software is distributed separately by the third party and has to installed separately.

Although potentially compatible with different engines, the rendition extension package is pre-configured and tested to use on of the following options:

  • an open source engine named wkhtmltopdf

  • an open engine AnswerModules R&D Team derived from the open source project Puppeteer named rend

The installation and configuration of the two above mentioned solutions is pretty similar.

Which software should I use ?

WKTMLTOPDF is based on an older version of the QT library and uses WebKit as the core browser technology, while AnswerModules's Rend is based on Puppeteer thus uses Chromium as the core browser technology. Both engines allow precise control over the browser's internal rendering of HTML documents, however Rend leverages newer technologies and on average is more accurate in rendering HTML documents that use a significant amount of JavaScript or non-ANSII charsets.

wkhtmltopdf

Installation
  • Follow the software developers instructions to perform the installation on each server in the OTCS cluster on which the extension is needed.

  • Upon a successful installation, the main executable has to be made available to the Content Script Extension Package as a dropin.

    To do so:

    • locate the wkhtmltopdf installation path
    • locate the wkhtmltopdf.exe executable in the folder
    • copy the wkhtmltopdf.exe in the CS Rendition Extension package dropin folder, located in: 
         <OTCS_HOME>/module/anscontentscript_x_x_x/amlib/rend/dropin
Configuration

  • Configure the Rendition extension package in order to use the wkhtmltopdf executable in the Module Suite Base Configuration

    Section rend

    Configuration Property Configuration Property Value
    amcs.rend.html2pdf.dropin wkhtmltopdf
    amcs.rend.html2pdf.cmdline -B 10 -T 10 -L 5 -R 5 --viewport-size 1920x1080 ${source} --print-media-type --cookie ${cookie} --run-script "am_printFix()" ${destination}
    amcs.rend.html2pdfForm.cmdline ${source} --cookie ${cookie} -p ${destination} --format A4 --marginBottom 100px --marginTop 120px --marginLeft 30px --marginRight 30px --scale 0.8 --viewport 1240x1754
    amcs.rend.html2pdf.timeout 60000
    Configuration Property Configuration Proerty Meaning
    amcs.rend.html2pdf.dropin The relative path to the engine's executable. For security reasons, the root of this path is the extension package's dropin folder.
    amcs.rend.html2pdf.cmdline The template of the command line instruction to be used when performing rendition (**). A few replacement tags can be used in this command line template. (a) ${source} : represent the absolute path for the input resource you want to render. Its value is automatically injected by the rendition extension package. Since the rendition extension package works on Content Script Resources, you do not have to worry about file system housekeeping. (b) ${destination} :represent the absolute path for the output resource, the engine is going to generate. Its value is automatically injected by the rendition extension package. Since the rendition extension package works on Content Script Resources, you do not have to worry about file system housekeeping. c ${cookie} : represent a local authentication cookie
    amcs.rend.html2pdf.timeout the default maximum wait time, in milliseconds, after which a rendition attempt will be aborted.

(**)

Please refer to the third-party rendition engine's guide for a detailed explanation of all the available command line parameters

rend

Installation (Windows)

External conversion engine package is provided as a compressed archive rend-win.zip. The Archive contains following items:

  • chromium – folder containing an up to date version of Chromium engine.
  • rend – pre-built NodeJS application leveraging Puppeteer

To install it:

  • Extract the conversion engine package in the following location: 
       <OTCS_HOME>/module/anscontentscript_x_x_x/amlib/rend/dropin
Installation (Unix)

External conversion engine package is provided as a compressed archive rend.tar.gz. The Archive contains following items:

  • chromium – folder containing an up to date version of Chromium engine.
  • rend – pre-built NodeJS application leveraging Puppeteer
  • run_rend – a script that will be called by the Content Suite and will launch the application

To install it:

  • Extract the conversion engine package in the following location: 
       <OTCS_HOME>/module/anscontentscript_x_x_x/amlib/rend/dropin

   e.g.
   >tar -C <OTHOME>/module/anscontentscript_x_y_0/amlib/rend/dropin -xvf rend.tar.gz
    Note: files inside dropin folder should belong to user that is used to run Content Server service. Thus you can either perform extraction under the OTCS service user or change ownership of the extracted files accordingly.
Configuration

  • Configure the Rendition extension package in order to use the rend executable in the Module Suite Base Configuration

    Section rend

    Windows

    Configuration Property Configuration Property Value
    amcs.rend.html2pdf.dropin rend-win
    amcs.rend.html2pdf.cmdline "${source}" --cookie "${cookie}" -p "${destination}" --format A4 --marginBottom 100px --marginTop 120px --marginLeft 30px --marginRight 30px --scale 0.8 --viewport 1240x1754
    amcs.rend.html2pdf.timeout 60000

    Unix

    Configuration Property Configuration Property Value
    amcs.rend.html2pdf.dropin run_rend
    amcs.rend.html2pdf.cmdline "${source}" --cookie "${cookie}" -p "${destination}" --format A4 --marginBottom 100px --marginTop 120px --marginLeft 30px --marginRight 30px --scale 0.8 --viewport 1240x1754
    amcs.rend.html2pdf.timeout 60000
    Configuration Property Configuration Proerty Meaning
    amcs.rend.html2pdf.dropin The relative path to the engine's executable. For security reasons, the root of this path is the extension package's dropin folder.
    amcs.rend.html2pdf.cmdline The template of the command line instruction to be used when performing rendition (**). A few replacement tags can be used in this command line template. (a) ${source} : represent the absolute path for the input resource you want to render. Its value is automatically injected by the rendition extension package. Since the rendition extension package works on Content Script Resources, you do not have to worry about file system housekeeping. (b) ${destination} :represent the absolute path for the output resource, the engine is going to generate. Its value is automatically injected by the rendition extension package. Since the rendition extension package works on Content Script Resources, you do not have to worry about file system housekeeping. c ${cookie} : represent a local authentication cookie
    amcs.rend.html2pdf.timeout the default maximum wait time, in milliseconds, after which a rendition attempt will be aborted.
    Dropin options

    -“${source}” – replacement tag that will be substituted by the URL to the generated HTML Form. This argument is mandatory and not editable.

    -ck, --cookie [cookie] – value will be replaced by replacement tag that corresponds to the current user’s session cookie. Should be in form “Name Value”. This argument is mandatory and not editable.

    -p, --path \<path> – identifies target PDF file location. Value will be substituted by the replacement tag. This argument is mandatory and not editable.

    -f, --format [format] – PDF option. Paper format. If set, takes priority over width or height options. Defaults to 'Letter'. Available options: Letter, Legal, Tabloid, Ledger, A[0-6].

    -d – Debug is on. If specified debugging information is written to the log file. Use only for debugging purposes. Log file located in \<OTHOME>\logs\cs_rend.log or when running application manually in \<appDir>\log\cs_rend.log

    -mb, --marginBottom [margin] - Bottom margin, accepts values labeled with units.

    -mt, --marginTop [margin] - Top margin, accepts values labeled with units.

    -mr, --marginRight [margin] - Right margin, accepts values labeled with units.

    -ml, --marginLeft [margin] - Left margin, accepts values labeled with units.

    -vp, --viewport [cookie] - PDF option. Set the viewport. Width and height of the page in pixels

    -prt, --printmediatype - Use print media type. Boolean. Default: true.

    -s, --scale [scale] - Scale of the webpage rendering.

    -dhf, --displayHeaderFooter - Display header and footer. Boolean. Default: false.

    -ht, --headerTemplate [template] - HTML template for the print header.

    -ft, --footerTemplate [template] - HTML template for the print footer.

    -pb, --printBackground - Print background graphics. Boolean. Default: true.

    -pr, --pageRanges - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.

    -w, --width [width] - Paper width, accepts values labeled with units.

    -h, --height [height] - Paper height, accepts values labeled with units.

    -wu, --waitUntil [choice] - WaitUntil accepts choices load, domcontentloaded, networkidle0, networkidle2. Defaults to 'networkidle2'.

    For more detailed description of the option please refer to official Puppeteer documentation