PDFCrowd JavaScript Library

Overview

The Pdfcrowd JavaScript library provides useful helper functions that enable to dynamically modify the converted document. You can insert a table of contents, disable hyperlinks, remove elements and many others.

The library is automatically injected into the converted HTML document. There are two ways to call the libPdfcrowd functions:

You can call the library from the JavaScript code passed to the setOnLoadJavascript() or setCustomJavascript() API methods:
```
client.setCustomJavascript("libPdfcrowd.insertTableOfContents()");
```

Or you can call the library directly in the converted document in the onLoadPdfcrowd callback:

<script>
  window.onLoadPdfcrowd = function() {
    libPdfcrowd.insertTableOfContents();
  }
</script>

Function Reference

function libPdfcrowd.insertStyle(PlainObject options)

Inserts custom CSS into the document.

options

An object of the following options:

style

The CSS string to be inserted.

destination

Specifies the location in the document where to insert the style. Allowed values are:

first - the first child of <head>
last - the last child of <head>
last-in-body - the last child of <body>

Available for converters >= 20.10. See versioning.

Default: first

asLast

Set to true to insert CSS at the end of <body>, false to insert it at the beginning of <head>.
This option is deprecated, use destination instead.

recursive

Set to true to descend into all iframes.

Default: false

Example:

Set the body text color to red.

libPdfcrowd.insertStyle({style: 'body { color: red; }'});

function libPdfcrowd.disableHyperlinks(PlainObject options)

Disables hyperlinks, the href attribute is removed from all <a> elements.

options

An object of the following options:

element

The DOM root element.

Default: document

recursive

Set to true to descend into all iframes.

Default: false

Example:

Disable all hyperlinks in the document <body>.

libPdfcrowd.disableHyperlinks({element: document.body});

function libPdfcrowd.removeBySelector(PlainObject options)

Removes elements from HTML.

options

An object of the following options:

selector

A CSS selector specifying the elements to be removed.

element

The DOM root element.

Default: document

recursive

Set to true to descend into all iframes.

Default: false

Example:

Remove all images from the document.

libPdfcrowd.removeBySelector({selector: 'img', recursive: true});

function libPdfcrowd.removeZIndexHigherThan(PlainObject options)

Removes <div>, <nav>, <header>, <footer> and <aside> elements with z-index greater than the specified value.

options

An object of the following options:

zlimit

The maximal visible z-index value.

element

The DOM root element.

Default: document

recursive

Set to true to descend into all iframes.

Default: false

Example:

Remove all elements with z-index greater than 1000.

libPdfcrowd.removeZIndexHigherThan({zlimit: 1000});

function libPdfcrowd.highlightHtmlElements(PlainObject options)

Visually highlights all HTML elements by altering their style. This function is useful for renderer debugging. The padding and margin options can be used to set a space between all elements to distinguish them. elementIdColor can be used to add a label with an element ID to find the element easily.

options

An object of the following options:

backgroundColor

A background color. Use null to not to modify the background color.

Default: 'rgba(255, 191, 0, 0.1)'

borderColor

A border color. Use null to not to modify the border color.

Default: 'orange'

elementIdColor

The color of the label that displays the element's ID. Use null to disable this feature.

Default: 'red'

randomColors

Set to true to use random colors.

Default: false

padding

A padding added to all elements to better distinguish the elements in the page.

Default: null

margin

A margin added to all elements to better distinguish the elements in the page.

Default: null

Example:

Highlight elements and add spacing around them so the complete element's hierarchy is visualized.

libPdfcrowd.highlightHtmlElements({backgroundColor: null, padding: '4px', margin: '4px'});

function libPdfcrowd.insertTableOfContents(PlainObject options)

Creates a customizable table of contents (TOC). The TOC is inserted as the first child of the <body> element by default.
The functions returns the created DOM node representing the generated TOC.

options

An object of the following options:

target

A CSS selector or a DOM node determining where to insert the TOC. If set to null or an empty string, the TOC is not inserted to the document and its DOM representation is returned.

Default: document.body

placement

A string value specifying the placement of the TOC within its parent.

Allowed values:

'first'
The first child of the target.
'last'
The last child of the target.
'single'
The only child of the target.
'replace'
The target element is completely replaced by the TOC.

Default: 'first'

selectors

A string or an array of CSS selectors specifying the source elements for the TOC.

Default: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']

Examples:

Only <h2> headings are used for the TOC.

'h2'
<h1> and <h2> headings are used for the TOC.

['h1', 'h2']
Elements with CSS class toc1 are used for the 1st TOC level, toc2 are used for the 2nd TOC level.

['.toc1', '.toc2']
All hyperlinks used in the document.

'a'
All <h1> elements except the 1st one.

'h1:not(:first-of-type)'

source

A CSS selector or a DOM node specifying the root element for applying selectors.

Default: document.body

Example:

The TOC consists only from the elements found in the subtree of the element with ID content.

'#content'

title

A string used as the TOC title.

Default: 'Table of Contents'

Example:

A custom title with styling.

'<span style='color: aqua;'>My Book TOC</span>'

numberingPlacement

Specifies where the numbering should be placed. Use null or an empty string to disable numbering.

Allowed values:

'toc-and-headings'
The numbering is added to the TOC and the elements referred to by the TOC.
'toc'
The numbering is added to the TOC only.
'headings'
The numbering is added to the referred elements only.

Default: 'toc-and-headings'

numberingFormat

A string determining the numbering format or an array of formats for individual TOC levels.
If the array is used, each level may contain a string with an optional numbering specifier: $1 for arabic, $I for roman, $i for roman-lowercase, $A for alphabet, $a for alphabet-lowercase.

Allowed values:

'arabic'
Arabic numerals.
'roman'
Roman numerals.
'roman-lowercase'
Roman numerals in lowercase.
'alphabet'
Letters from the English alphabet.
'alphabet-lowercase'
Letters from the English alphabet in lowercase.

Default: 'arabic'

Examples:

All numberings use the English alphabet letters.

'alphabet'
The custom numbering format.

['my <strong>$i-th</strong>', 'my sublevel <span class="my-class">$A</span>']

numberingSublevels

The number of sublevels in the heading numbering. It may be the string all or an array of integers.

Default: 'all'

Example:

The first level shows 1 sublevel numbering, the second and third levels show 2 sublevels numbering.

[1, 2, 2]

indents

A string or an array specifying the indentation of each TOC level. Use null or an empty string for no indentation.

Default: '10pt'

Examples:

Each level is indented from the previous level by 1cm.

'1cm'
The first level is indented by 10pt, the second level is indented by 2in.

['10pt', '2in']

leaders

A string or an array specifying the leaders to be displayed between the TOC headings and page numbers. Use null or an empty string for no leaders.

Default: '. '

Examples:

An ellipsis are used for all levels.

'…'
A plus sign is used for the first level and a minus sign for the second level.

['+', '-']
Unicode character 'white small square' (U+25AB) plus a space is used for all levels.

'\u25AB '
An image is used for the first level and three plus signs are used for the second level.

['<img src="level1.png"/>', '<b>+++</b>']

leadersRepeat

A boolean determining if the leaders should be repeated in a TOC row. If set to false, the page number is placed right next to the leader.

Default: true

pageNumbers

The page number format. It can be a string or an array of strings for individual levels. Set to null or an empty string to disable page numbers in TOC.

Allowed values:

'arabic'
Arabic numerals.
'roman'
Roman numerals.
'roman-lowercase'
Roman lowercase numerals.

Default: 'arabic'

Examples:

Use Roman numerals.

'roman'
Do not show page numbers on the first level and show Arabic numerals on other levels.

[null, 'arabic']

pageBreak

A string value determining whether to insert a page break. Use null or an empty string for no page break.

Allowed values:

'before'
A page break is inserted before the TOC.
'after'
A page break is inserted after the TOC.
'before-and-after'
A page break is inserted before and after the TOC.

Default: null

width

The CSS width of the created TOC element. If not specified, the width is inherited from the target element.

style

The CSS style applied to the created TOC element.

Default: null

Example:

"background: #f4f4f4 none repeat scroll 0 0; border: 1px solid #aaa; padding: 1em; box-sizing: border-box;"

className

The name of the class to set on the created TOC element.

Default: null

tocId

The ID set on the created TOC element. If not specified, the ID is autogenerated.

onGetEntryText

A function allowing customization of the text of TOC entries. It is called for each TOC entry and should return a string/HTML. The function accepts the following argument:

element - the source element (heading) for the entry

Default: function(element) { return element.textContent; }

onBuildEntry

A function allowing customization of TOC entries. It is called for each TOC entry and should return a DOM element representing the TOC entry. The function accepts the following arguments:

element - the source element (heading) for the entry
level - the current TOC level
numbering - an array with the current numbering for each level
entry - the TOC entry element created by libPdfcrowd

Default: function(element, level, numbering, entry) { return entry; }

Examples:

Insert a TOC.
```
libPdfcrowd.insertTableOfContents();
```

Insert a TOC created only from <h3> elements.

libPdfcrowd.insertTableOfContents({selectors: 'h3'});

Insert a list of images used in a document. The value of the image's alt atribute is used as the list entry.

libPdfcrowd.insertTableOfContents({
    placement: 'last',
    selectors: 'img',
    title: 'Image List',
    onGetEntryText: function(element) {
        return element.getAttribute('alt');
    }
});

Insert a TOC with red page numbers.

libPdfcrowd.insertStyle({
    style: '.pdfcrowd-toc-page-nr { color: red; }'
});
libPdfcrowd.insertTableOfContents();

Create a TOC and insert it manually to the document.

var toc = libPdfcrowd.insertTableOfContents({target: null});
document.getElementById('#toc').appendChild(toc);

Use the setOnLoadJavascript API method to replace the table of contents of a Wikipedia page with a new one having numbering and page numbers. You can see the resulting PDF here.

html2pdfClient.setOnLoadJavascript("
    libPdfcrowd.insertTableOfContents({
        source: '#content',
        target: '#toc',
        className: 'toc',
        placement: 'replace',
        selectors: ['h2 .mw-headline', 'h3 .mw-headline', 'h4 .mw-headline'],
        title: 'Contents <span style="font-size: 10px">powered by Pdfcrowd</span>'
    });
");
html2pdfClient.convertUrlToFile("https://en.wikipedia.org/wiki/PDF", "example.pdf");

The HTML code created by libPdfcrowd.insertTableOfContents({tocId: 'my-toc', className: 'my-class'}). It shows the TOC structure and the classes that you style in your CSS.

<div id="my-toc" class="my-class pdfcrowd-toc pdfcrowd-toc-style-1">
  <div class="pdfcrowd-toc-title">Table of Contents
  </div>
    <table class="pdfcrowd-toc-row">
      <tbody>
        <tr class="pdfcrowd-toc-level pdfcrowd-toc-level-1">
          <td class="pdfcrowd-toc-caption pdfcrowd-toc-caption-level-1">
            <a href="#my-toc-el-1">
              <div class="pdfcrowd-toc-text pdfcrowd-toc-text-level-1">
                <span class="pdfcrowd-toc-numbering pdfcrowd-toc-numbering-level-1">
                  1.
                </span>
                <span class="pdfcrowd-toc-text-content pdfcrowd-toc-text-content-level-1">
                  Heading Level 1
                </span>
              </div>
            </a>
          </td>
          <td class="pdfcrowd-toc-page-number pdfcrowd-toc-page-number-level-1">
            <a data-pdfcrowd-link="my-toc-el-1"
               data-pdfcrowd-number-format="arabic" class="pdfcrowd-toc-page-nr" href="#my-toc-el-1">
              <div>$N
              </div>
            </a>
          </td>
        </tr>
      </tbody>
    </table>
    <table class="pdfcrowd-toc-row">
      <tbody>
        <tr class="pdfcrowd-toc-level pdfcrowd-toc-level-2">
          <td class="pdfcrowd-toc-caption pdfcrowd-toc-caption-level-2">
            <a href="#my-toc-el-2">
              <div class="pdfcrowd-toc-text pdfcrowd-toc-text-level-2">
                <span class="pdfcrowd-toc-numbering pdfcrowd-toc-numbering-level-2">
                  1.1.
                </span>
                <span class="pdfcrowd-toc-text-content pdfcrowd-toc-text-content-level-2">
                  Heading Level 2
                </span>
              </div>
            </a>
          </td>
          <td class="pdfcrowd-toc-page-number pdfcrowd-toc-page-number-level-2">
            <a data-pdfcrowd-link="my-toc-el-2"
               data-pdfcrowd-number-format="arabic" class="pdfcrowd-toc-page-nr" href="#my-toc-el-2">
              <div>$N
              </div>
            </a>
          </td>
        </tr>
      </tbody>
    </table>
    <table class="pdfcrowd-toc-row">
      <tbody>
        <tr class="pdfcrowd-toc-level pdfcrowd-toc-level-3">
          <td class="pdfcrowd-toc-caption pdfcrowd-toc-caption-level-3">
            <a href="#my-toc-el-3">
              <div class="pdfcrowd-toc-text pdfcrowd-toc-text-level-3">
                <span class="pdfcrowd-toc-numbering pdfcrowd-toc-numbering-level-3">
                  1.1.1.
                </span>
                <span class="pdfcrowd-toc-text-content pdfcrowd-toc-text-content-level-3">
                  Heading Level 3
                </span>
              </div>
            </a>
          </td>
          <td class="pdfcrowd-toc-page-number pdfcrowd-toc-page-number-level-3">
            <a data-pdfcrowd-link="my-toc-el-3"
               data-pdfcrowd-number-format="arabic" class="pdfcrowd-toc-page-nr" href="#my-toc-el-3">
              <div>$N
              </div>
            </a>
          </td>
        </tr>
      </tbody>
    </table>
</div>