Documentation

Merge HTML content

General considerations

Docxpresso, upon which the DXCloud REST API is built, is a general tool to generate online reports and business documentation in PDF, ODF, Word and RTF formats that, among other possibilities, allows for the merging, insertion and styling of its contents using HTML5 and CSS.

Even if you can generate with Docxpresso pretty sophisticated documents using HTML5 code, Docxpresso is not meant as a tool to exactly reproduce an arbitrary web page. If nice formatting is a must you may need to carefully craft the HTML and CSS code so you render a version of the web page that better adapts to the limitations of paged media.

As it is described in the explanation of the general "replace" property there are two main ways to merge data using a template variable, and they both apply in the particular case of HTML content:

  • inline: in tis case (the default one) only the HTML "inline content", see below for a more detail explanation, will replace the chosen variable. For example, if the merge value is of the form: "<strong>John</strong> <em>Smith</em>" the variable will be replaced by John Smith but if we use instead: "<p><strong>John</strong> <em>Smith</em></p>" the p tags will be removed and the same formatted text will be inserted as before, i.e. Docxpresso will "inlinearize" the HTML.
  • block: in this case the paragraph containing the variable will be completely removed (with any other text or element contained) and it will be replaced for the full merging HTML code that may include, paragraphs, tables or even charts if we use "extended HTML" content as defined below.

In order to better support some general document components not covered by the HTML5 standard Docxpresso extends it in a simple way to include:

  • Footnotes and endnotes
  • Charts
  • Page numbering
  • Table of Contents
  • Math

Moreover we have adapted to what we considered as their natural "paged document" equivalents some of the standard HTML5 tags like:

  • header and footer,
  • section,
  • table header,
  • etcetera.

This also applies to a few CSS properties that have been reinterpreted to better suite the needs of standard paged media.

Let us get now deeper into details.

Replacing a variable by complex HTML

Before getting into the details let us do an example that will cover much of the ground that will be explained in detail in what follows.

Let us first consider the following HTML code:

<html>
    <head>
        <style>
        p {font-family: Verdana; font-size: 10pt}
        h1 {color: #b70000; margin-bottom: 12pt; font-family: "Century Gothic"; page-break-before: always}
        footnote {font-family: Verdana; font-size: 8pt}
        .headerTable {width: 15cm; border: none}
        .headerImage {width: 5cm}
        .headerTitle {width: 10cm; vertical-align: middle;}
        .headerTitle p {font-size: 12pt; font-weight: bold; color: #567896; font-family: "Century Gothic"}
        .docFooter {border-top: 1px solid #777; color: #555; text-align: right; font-family: Verdana; font-size: 10pt}
        .red {color: #b70000; font-size: 8pt; font-weight: bold}
        </style>
    </head>
    <body>
        <h1>Sample document generated with HTML5</h1>
        <p>This example only aims to illustrate how <strong>HTML5PDF</strong> renders a sample
        web page in different document formats.</p>
        <p>We include a footnote<footnote>Just some random text with a 
        <span class="red"> little formatting</span>.</footnote>
        and a simple pie chart so we get a little more sophisticated example:</p>
        <chart type="pie" style="width: 15cm">
            <legend />
            <category name="First" value="30" />
            <category name="Second" value="20" />
            <category name="Third" value="25" />
            <category name="Fourth" value="10" />
        </chart>
        <h1>Another page</h1>
        <p>This is just to check how the header and footer are included in every 
        single page with the correct page numbering.</p>
    </body>
</html>

This just looks like ordinary HTML code it it were not for a few weird tags like chart, footnote or page.

Let us see what we can achive with a basically empty template with just one variable {{content}} and the following JSON code:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "content",
                 "value": ["insert here the previous HTML code with quotes escaped"],
                 "block-type": true
                }
            ]
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variable by block HTML

Supported HTML5 tags

The parsed HTML5 tags include:

  • a: Defines a hyperlink.
  • abbr: Defines an abbreviation.
  • acronym: Defines an acronym.
  • address: Defines contact information for the author/owner of a document.
  • article: Defines an article.
  • aside: Defines content aside from the page content.
  • b: Defines bold text.
  • base: Specifies the base URL/target for all relative URLs in a document.
  • bdi: Isolates a part of text that might be formatted in a different direction from other text outside it.
  • bdo: Overrides the current text direction.
  • big: Not supported in HTML5. Use CSS instead. Defines big text.
  • blockquote: Defines a section that is quoted from another source.
  • body: Defines the document's body.
  • br: Defines a single line break.
  • button: Defines a clickable button.
  • caption: Defines a table caption.
  • center: Defines centered text (supported although deprecated in HTML5).
  • chart: Docxpresso extension.
  • cite: Defines the title of a work.
  • code: Defines a piece of computer code.
  • col: Specifies column properties for each column within a 'colgroup' element .
  • colgroup: Specifies a group of one or more columns in a table for formatting.
  • command: Defines a command button that a user can invoke.
  • datalist: Specifies a list of pre-defined options for input controls.
  • date: Docxpresso extension.
  • dd: Defines a description/value of a term in a description list.
  • del: Defines text that has been deleted from a document.
  • details: Defines additional details that the user can view or hide.
  • dfn: Defines a definition term.
  • div: Defines a group of elements to be formatted via CSS.
  • dl: Defines a description list.
  • dt: Defines a term/name in a description list.
  • em: Defines emphasized text .
  • endnote: Docxpresso extension.
  • fieldset: Groups related elements in a form.
  • figcaption: Defines a caption for a 'figure' element.
  • figure: Specifies self-contained content.
  • footer: Defines a footer for a document or section.
  • footnote: Docxpresso extension.
  • form: Defines an HTML form for user input.
  • h1: Defines a HTML heading level 1.
  • h2: Defines a HTML heading level 2.
  • h3: Defines a HTML heading level 3.
  • h4: Defines a HTML heading level 4.
  • h5: Defines a HTML heading level 5.
  • h6: Defines a HTML heading level 6.
  • head: Defines information about the document.
  • header: Defines a header for a document or section.
  • hr: Defines a thematic change in the content.
  • html: Defines the root of an HTML document.
  • i: Defines italic text.
  • img: Defines an image.
  • input: Defines an input control.
  • ins: Defines a text that has been inserted into a document.
  • label: Defines a label for an 'input' element.
  • legend: Defines a caption for a 'fieldset' element.
  • li: Defines a list item.
  • math: Docxpresso extension.
  • mark: Defines marked/highlighted text.
  • menu: Defines a list/menu of commands.
  • menuitem: an element of a menu list.
  • nav: Defines navigation links.
  • ol: Defines an ordered list.
  • option: Defines an option in a drop-down list.
  • outline: Docxpresso extension. Set the format of the different TOC elements
  • output: Defines the result of a calculation.
  • p: Defines a paragraph.
  • page: Docxpresso extension.
  • q: Defines a short quotation.
  • ref: Docxpresso extension. Allows to get the page or text of a bookmarked element.
  • samp: Defines sample output from a computer program.
  • section: Defines a section in a document.
  • select: Defines a drop-down list.
  • small: Defines smaller text.
  • span: Defines a chunk of formatted text.
  • strike: Not supported in HTML5. Use 'del' instead. Defines strikethrough text.
  • strong: Defines important text.
  • sub: Defines subscripted text.
  • summary: Defines a visible heading for a 'details' element.
  • sup: Defines superscripted text.
  • tab: Docxpresso extension.
  • table: Defines a table.
  • td: Defines a cell in a table.
  • textarea: Defines a multiline input control (text area).
  • tfoot: Groups the footer content in a table.
  • th: Defines a header cell in a table.
  • time: Defines a date/time.
  • toc: Docxpresso extension.
  • tr: Defines a row in a table.
  • tt: Defines teletype text (deprecated in HTML5).
  • u: Defines text that should be stylistically different from normal text.
  • ul: Defines an unordered list.
  • var: Defines a variable.
  • wbr: Defines a possible line-break.

Supported CSS properties

The parsed CSS properties include:

Color properties

  • color: font color in hexadecimal/rgb format or standard CSS color list.
  • opacity: a number between 0 and 1 determining the transparancy of the element.

Background and Border Properties

  • background: shorthand for background properties.
  • background-color: a color in hexadecimal/rgb format or standard CSS color.
  • background-image: the absolute or relative url of the image to be used as background.
  • background-position: tha background image position. It can be given like a combination of the top, right, bottom, left and center properties or with standard CSS units.
  • background-repeat: specifies if the background image is to be repeated and how (there is no support for the repeat-x and repeat-y properties).
  • border: shorthand for all border properties.
  • border-bottom: shorthand for the bottom border properties.
  • border-bottom-color: bottom border color in hexadecimal/rgb format or standard CSS color.
  • border-bottom-style: bottom border style.
  • border-bottom-width: bottom border width in standard CSS units.
  • border-color: sets all border color properties in one shot.
  • border-left: shorthand for the left border properties.
  • border-left-color: left border color in hexadecimal/rgb format or standard CSS color.
  • border-left-style: left border style.
  • border-left-width: left border width in standard CSS units.
  • border-right: shorthand for the right border properties.
  • border-right-color: right border color in hexadecimal/rgb format or standard CSS color.
  • border-right-style: right border style.
  • border-right-width: right border width in standard CSS units.
  • border-style: sets all border style properties in one shot.
  • border-top: shorthand for the top border properties.
  • border-top-color: top border color in hexadecimal/rgb format or standard CSS color.
  • border-top-style: top border style.
  • border-top-width: top border width in standard CSS units.
  • border-width: sets all border width properties in one shot.

Basic Box Properties

  • bottom: distance from the bottom in standard CSS units.
  • display: sets the element display properties.
  • float: sets the relative positioning.
  • height: height in standard CSS units.
  • left: distance from the left in standard CSS units.
  • padding: shorthand for the different padding properties of an element.
  • padding-bottom: padding bottom in standard CSS units.
  • padding-left: padding left in standard CSS units.
  • padding-right: padding right in standard CSS units.
  • padding-top: padding top in standard CSS units.
  • position: sets the element type of positioning.
  • right: distance from the right in standard CSS units.
  • top: distance from teh top in standard CSS units.
  • visibility: sets the visibility of the element.
  • width: width in standard CSS units.
  • vertical-align: vertical alignment (only top, middle or bottom are parsed)
  • z-index: the z-index of an absolutely positiones element.

Flexible Box Layout

  • margin: shorthand for the different margin properties of an element.
  • margin-bottom: margin bottom in standard CSS units.
  • margin-left: margin left in standard CSS units.
  • margin-right: margin right in standard CSS units.
  • margin-top: margin top in standard CSS units.
  • max-height: maximum height in standard CSS units.
  • max-width: maximum width in standard CSS units.
  • min-height: minimum height in standard CSS units.
  • min-width: minimum width in standard CSS units.

Text Properties

  • hyphens: specifies how to go about splitting words.
  • letter-spacing: spacing between characters in standard CSS units.
  • line-break: specify how (or if) to break lines.
  • line-height: sets the line height in standard CSS units.
  • text-align: sets the type of text alignment (center, left, ...)
  • text-align-last: specifies how to align the last line of a text.
  • text-indent: text indent in standard CSS units.
  • text-transform: convert to lower or uppercase the text of an element.

Text Decoration Properties

  • text-decoration: sets the text decoration of the element text.
  • text-decoration-color: text decoration line color.
  • text-decoration-line: text decoration line type.
  • text-decoration-style: text decoration line style
  • text-shadow: text shadow (incomplete support).

Font Properties

  • font: shorthand for font properties.
  • font-family: font family (Arial, Verdana, ...).
  • font-kerning: sets the character kerning.
  • font-size: sets the font size in standard CSS units
  • font-style: sets the font style.
  • font-variant: sets the font variant.
  • font-weight: sets the font weight (bold, normal, ...)

Writing Modes Properties

  • direction: specifies the text direction/writing direction (left or right)
  • writing-mode: the same as above but allows also to control the top/bottom direction.

Table Properties

  • border-collapse: sets the border collapse mode.
  • border-spacing: sets the border spacing (incomplete support).
  • empty-cells: determines if empty table cells are shown.

Lists Properties

  • list-style: shorthand for list properties
  • list-style-type: the list style type (disc, circle, ...).

Transform Properties

  • transform: transformation to be applied to the element (only rotation is supported).

Basic User Interface Properties

  • outline: shorthand for the outline properties
  • outline-color: outline color.
  • outline-style: outline style
  • outline-width: outline width in standard CSS units.

Multi-column Layout Properties

  • break-after: sets if there may be a break after an element.
  • break-before: sets if there may be a break after an element.
  • break-inside: sets if there may be a break within an element.
  • column-count: number of columns.
  • column-gap: separation between columns in standard CSS units.
  • column-rule: shorthand for the rule between columns.
  • column-rule-color: rule color
  • column-rule-style: rule line style
  • column-rule-width: rule line width.
  • column-width: width of a column in standard CSS units.
  • columns: shorthand for column properties.

Paged Media

  • orphans: determines the minimum number of orphan lines in a page.
  • widows: determines the minimum number of widow lines in a page.
  • page-break-after: sets if there may be a page break after an element
  • page-break-before: sets if there may be a page break before an element
  • page-break-inside: sets if there may be a page break within an element

Some addtional examples

Here we include for your convenience a few commented Docxpresso scripts that mainly use HTML5 + CSS to generate standard document elements.

Nicely formatted table

It is very simple to generate nice tables from plain HTML (this time we will omit the explicit JSON code that is exactly the same that in the first example):

<html>
    <head>
        <style>
        body {font-family: Calibri; font-size: 11pt}
        .niceTable {border-collapse: collapse}
        .niceTable td {border: 1px solid #657899; padding: 2px 5px; width: 5cm; margin: 0}
        .niceTable th {vertical-align: bottom; border-bottom: 1px solid #657899 !important; padding: 2px 5px; width: 5cm; font-weight: bold; margin: 0}
        .niceTable th.firstCol {font-style: italic; border: none; text-align: right; background-color: white}
        .niceTable td.firstCol {font-style: italic; border: none; border-bottom: 1px solid #ffffff !important; text-align: right; background-color: white}
        .odd {background-color: #d5e0ff}
        </style>
    </head>
    <body>
        <p>Just a nicely formatted table:</p>
        <table class="niceTable">
            <tr>
                <th class="firstCol">Table title</th>
                <th>Column 1</th>
                <th>Column 2</th>
            </tr>
            <tr class="odd">
                <td class="firstCol">Row 1</td>
                <td class="odd">Cell_1_1</td>
                <td class="odd">Cell_1_2</td>
            </tr>
            <tr>
                <td class="firstCol">Row 2</td>
                <td>Cell_2_1</td>
                <td>Cell_2_2</td>
            </tr>
        </table>
    </body>
</html>

DOWNLOAD: Template JSON Doc

The table formatting is inspired in one of the typical Word table formats. Notice that some of the CSS styles are redundant, this is due to assure nice rendering in all possible formats. The .pdf, .odt and .doc formats do not require, for example, the reiterative inclusion of the odd class attribute in table cells.

table in HTML fromat

Extended HTML

General considerations

Although HTML5 is by all means an amazingly complete standard it has not been designed with paged media in mind, so it lacks certain elements that are common in standard documents:

  • Charts.
  • Dates.
  • Footnotes and endnotes.
  • Math equations.
  • Page numbering.
  • Tabs
  • Table of contents.

The Docxpresso extensions of plain HTML5 are thought to remedy, in the most possibly simple way, those deficiencies. What follows is the result of this goal.

Charts

Of all the current included HTML5 extensions this is with no doubt the more extensive one.

Before getting into the details of the associated XML schema let us run a simple example that will give you a pretty clear taste of what is going on:

<style>
.centeredText {text-align: center; font-family: Georgia; font-size: 16pt; color: #5689dd}
</style>
<p style="margin-bottom: 20pt">A 3D column bar chart in HTML format:</p>
<p class="centeredText">Sales (K$)</p>
<p class="centeredText">
    <chart type="3Dcolumn" stacked="true" style="width: 10cm;">
        <legend legend-position="bottom"/>
        <component type="floor" fill-color="#fff0f0" />
        <series>
            <ser name="Europe" />
            <ser name="America" />
            <ser name="Asia" />
        </series>
        <categories>
            <category name="2010">
                <data value="650" />
                <data value="470" />
                <data value="400" />
            </category>
            <category name="2011">
                <data value="680" />
                <data value="540" />
                <data value="430" />
            </category>
            <category name="2012">
                <data value="650" />
                <data value="600" />
                <data value="600" />
            </category>
            <category name="2013">
                <data value="750" />
                <data value="640" />
                <data value="580" />
            </category>
        </categories>
    </chart>
</p>

Let us see what we can achive with a basically empty template with just one title and the variable {{content}} and the following JSON code:

{   
    "template": "insert here the given template base64 encoded",
    "output": "pdf",
    "replace": [
        {
            "vars": [
                {
                 "var": "content",
                 "value": ["insert here the previous HTML code with quotes escaped"],
                 "block-type": true
                }
            ]
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variable by block HTML

We would like to point out that currently the support for HTML charts in Word format output is "incomplete". For that case we recommend to use the replaceChartData option.

In principle one may control from HTML5 code all the customizable components of the Docxpresso chart public API, i.e.

  • General chart properties: <chart> tag.
  • Legend properties: <legend> tag.
  • Chart axis (x, y or z): <axis> tag.
  • Chart wall and floor components: <component> tag
  • Chart data: <series> and <categories> tags
  • 3D transformations: <transform3D> tag

That we pass to explain in further detail.

<chart>

The <chart> element is the main chart wrapper that accepts the following childs and attributes:

Child elements

  • legend
  • axis
  • component
  • series
  • categories

Attributes

  • data-label-number (type: string, default: none). The possible values are: none, value or percentage.
  • label-position (type: string). The possible values are: avoid-overlap, center, top, top-right, right, bottom-right, bottom, bottom-left, left, top-left, inside, outside or near-origin.
  • label-position-negative (type: string). It only applies if the data value is negative. If not given the value for data-label-position will be used. Possible values are: top-left, inside, outside or near-origin.
  • hole-size (type: integer), specifies the diameter of the inner hole of a ring chart as percentage of the outer diameter of the outermost ring.
  • pie-offset (type: integer), specifies the distance of a segment from the center of the circle in case of circle charts. The offset is given as an integer which is interpreted as a percentage of the radius of the circle. In case of ring charts specifies an additional distance of a segment from the center of the circle. The distance is given as percentage of the thickness of the ring.
  • angle-offset (type: integer), specifies in degrees a counter clockwise rotation of a polar coordinate in a circle, ring or polar chart.
  • stacked (type: boolean, default: false). It specifies the accumulation of the series values per category. Each value is in addition to the other values in the same category.
  • chart-interpolation (type: string). The possible values are none (if points are to be connected by a straight line, b-spline or cubic-spline.
  • spline-resolution (type: integer). It only applies if the chart-interpolation option is not equal to none.
  • deep (type: boolean, default: false). If true the series will be shown in 3D one behind the other and not side by side. It only applies to 3D charts.
  • solid-type (type: string, default: cuboid). Possible values are: cuboid, cylinder, cone or pyramid. It only applies to 3D bar charts.
  • style (type: string). A list of properties in CSS format that only set the global properties of the chart.

<legend>

The <legend> element controls the legend display properties:

Child elements

  • No child elements.

Attributes

  • legend-position (type: string, default: bottom). Possible values are: top, right, bottom or left.
  • color (type: string). The legend font color in hexadecimal format.
  • font-family (type: string). The legend text font family.
  • font-size (type: string). The legend text font size in points, e.g. 11pt.
  • font-weight (type: string, default: normal). The legend text font weight: normal or bold.
  • font-style (type: string, default: normal). The legend text font style: normal or italic.
  • fill-color (type: string). The data point color in hexadecimal format.
  • opacity (type: string, default: 100%), specifies the fill color opacity as a percentage.
  • stroke (type: string, default: solid). It can be none, solid or dash.
  • stroke-width (type: string), specifies the line width.
  • stroke-color (type: string), specifies the line color in hexadecimal format.
  • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.
  • stroke-linejoin (type: string, default: round). Possible values are: round, bevel, middle, miter or none.
  • stroke-linecap (type: string, default: butt). Possible values are: butt, round or squared.

<axis>

The <axis> element allows to customize the x, y or z (only 3D charts) axis:

Child elements

  • No child elements.

Attributes

  • $axis (type: string). Possible values are: x, y or z.
  • visible (type: boolean, default: true). If true the axis is shown.
  • logarithmic (type: boolean, default: false). If true the axis is shown with a logarithmic scale.
  • font-color (type: string). The axis font color in hexadecimal format.
  • font-family (type: string). The axis text font family.
  • font-size (type: string). The axis text font size in points, e.g. 11pt.
  • axis-position (type: mixed, default: start). It can be start (default), end or a numeric value dictating where the perpendicular axis should cross. In the case of the y-axis it refers to the category, i.e. 1 before the first category, 2 behind the second and so long so forth.
  • minimum (type: float), specifies the minimum value of an axis.
  • maximum (type: float), specifies the maximum value of an axis.
  • label-arrangement (type: string). Possible values are: side-by-side, stagger-even or stagger-odd.
  • display-label (type: boolean, default: true). If true displays the axis label.
  • axis-label-position (type: string, default: near-axis). Possible values are: near-axis, near-axis-other-side, outside-end or outside-start.
  • reverse-direction (type: boolean, default: false). If true reverses the axis direction.
  • text-overlap (type: boolean, default: false). It specifies whether axis labels may overlap each other.
  • line-break (type: boolean, default: true). It specifies whether text wrapping for axis labels is allowed.
  • stroke (type: string, default: solid). It can be none, solid or dash.
  • stroke-width (type: string), specifies the line width.
  • stroke-color (type: string), specifies the line color in hexadecimal format.
  • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.
  • stroke-linejoin (type: string, default: round). Possible values are: round, bevel, middle, miter or none.
  • stroke-linecap (type: string, default: butt). Possible values are: butt, round or squared.
  • interval-major (type: float), specifies the separation between major intervals within an axis.
  • interval-minor-divisor (type: integer), specifies the number of divisions between to major interval lines.
  • tick-marks-major-inner (type: boolean, , default: false). If true it shows inner major tick marks.
  • tick-marks-minor-inner (type: boolean, , default: false). If true it shows inner minor tick marks.
  • tick-marks-major-outer (type: boolean, , default: false). If true it shows outer major tick marks.
  • tick-marks-minor-outer (type: boolean, , default: false). If true it shows outer minor tick marks.

<grid>

The <grid> element allows to customize the x, y or z (only 3D charts) grid lines:

Child elements

  • No child elements.

Attributes

  • $axis (type: string, default: x). Possible values are: x, y or z.
  • $type (type: string, default: major). Grid type. Possible values are: major or minor.
  • stroke (type: string, default: solid). It can be none, solid or dash.
  • stroke-width (type: string), specifies the line width. The default values are: 0.75pt for major grids and 0.5pt for minor grids.
  • stroke-color (type: string), specifies the line color in hexadecimal format. For major grids the default is #d9d9d9 and #f0f0f0 for minor grids.
  • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.
  • stroke-linejoin (type: string, default: round). Possible values are: round, bevel, middle, miter or none.
  • stroke-linecap (type: string, default: butt). Possible values are: butt, round or squared.

<component>

The <transform3D> element allows for the customization of the wall and floor components of a chart:

Child elements

  • No child elements.

Attributes

  • $component (type: string, default: wall). Component type. Possible values are: wall or floor.
  • fill-color (type: string). The data point color in hexadecimal format.
  • opacity (type: string, default: 100%), specifies the fill color opacity as a percentage.
  • stroke (type: string, default: solid). It can be none, solid or dash.
  • stroke-width (type: string), specifies the line width.
  • stroke-color (type: string), specifies the line color in hexadecimal format.
  • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.
  • stroke-linejoin (type: string, default: round). Possible values are: round, bevel, middle, miter or none.
  • stroke-linecap (type: string, default: butt). Possible values are: butt, round or squared.

<transform3D>

The <transform3D> element allows to rotate and change the default perspective in 3D charts:

Child elements

  • No child elements.

Attributes

  • rotate-x (type: integer, default: 11 ). Rotation angle respect the x-axis.
  • rotate-y (type: integer, default: 25 ). Rotation angle respect the y-axis.
  • rotate-z (type: integer, default: 5 ). Rotation angle respect the z-axis.
  • perspective (type: integer, default: 20 ). Given as a percentage.
  • right-angled-axes (type: boolean, , default: 20). If true the rotate-z parameter is ignored.

<series>

The <series> element is a wrapper element for the different series that compose the chart data.

This element is not allowed for 2 & 3D pie and donut charts.

Child elements

  • ser

Attributes

  • This element does not have any attribute.

<ser>

The <ser> element contains the relevant data for a particular chart series.

This element is not allowed for 2 & 3D pie and donut charts.

Child elements

  • No child elements.

Attributes

  • fill-color (type: string). The data point color in hexadecimal format.
  • opacity (type: string, default: 100%), specifies the fill color opacity as a percentage.
  • stroke (type: string, default: solid). It can be none, solid or dash.
  • stroke-width (type: string), specifies the line width.
  • stroke-color (type: string), specifies the line color in hexadecimal format.
  • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.

<categories>

The <caegories> element is a wrapper element for the different category elements that compose the chart data.

Child elements

  • ser

Attributes

  • This element does not have any attribute.

<category>

The <category> element contains the actual data. Its structure depends on the chart type.

Child elements

  • Pie and donut type charts:
    • No child elements
  • All other chart types:
    • ser

Attributes

  • name (type: string). The category name (ignored for bubble charts).
  • The following attributes are exclusive for pie and donut charts:
    • value (type: float). The actual data point value.
    • fill-color (type: string). The data point color in hexadecimal format.
    • opacity (type: string, default: 100%), specifies the fill color opacity as a percentage.
    • stroke (type: string, default: solid). It can be none, solid or dash.
    • stroke-width (type: string), specifies the line width.
    • stroke-color (type: string), specifies the line color in hexadecimal format.
    • stroke-opacity (type: string, default: 100%), specifies the line color opacity as a percentage.

<data>

The <data> element contains the actual value for each data point.

Child elements

  • No child elements.

Attributes

  • value (type: float). The actual data point value.

Charts reference HTML

The general structure of a chart element may be summarized in this sample code:

<chart  style="CSS styles"
        type="column|bar|pie|donut|area|line|scatter|bubble|radar|filled-radar|column-line|3Dcolumn|3Dbar|3Dpie|3Ddonut|3Darea|3Dline|3Dscatter"  
        data-label-number="none|value|percentage"
        label-position="avoid-overlap|center|top|top-right|right|bottom-right|bottom|bottom-left|left|top-left|inside|outside|near-origin"
        label-position-negative="top-left|inside|outside|near-origin"
        hole-size="integer"
        pie-offset="integer"
        angle-offset="integer"
        stacked="boolean"
        gap-width="integer"
        overlap="integer"
        percentage="boolean"
        chart-interpolation="none|b-spline|cubic-spline"
        spline-resolution="integer"
        deep="boolean"
        solid-type="cuboid|cylinder|cone|pyramid" >
    <title  color="hexadecimal color"
            font-family="string"
            font-size="float(pt|cm|in|mm)"
            font-weight="normal|bold"
            font-style="normal|italic"
            stroke="solid|dash|none"
            fill-color="hexadecimal color"
            opacity="integer%"
            stroke-width="float(pt|cm|in|mm)"
            stroke-color="hexadecimal color"
            stroke-opacity="integer%"
            stroke-linejoin="round|bevel|middle|miter|none"
            stroke-linecap="butt|round|square" >Title</title>
    <legend name="" //only applies to bubble charts
            legend-position="left|right|top|bottom" 
            color="hexadecimal color"
            font-family="string"
            font-size="float(pt|cm|in|mm)"
            font-weight="normal|bold"
            font-style="normal|italic"
            stroke="solid|dash|none"
            fill-color="hexadecimal color"
            opacity="integer%"
            stroke-width="float(pt|cm|in|mm)"
            stroke-color="hexadecimal color"
            stroke-opacity="integer%"
            stroke-linejoin="round|bevel|middle|miter|none"
            stroke-linecap="butt|round|square"/>
    <grid   dimension="x|y|z"
            type="major|minor"
            stroke="solid|dash|none"
            stroke-width="float(pt|cm|in|mm)"
            stroke-color="hexadecimal color"
            stroke-opacity="integer%"
            stroke-linejoin="round|bevel|middle|miter|none"
            stroke-linecap="butt|round|square" />
    <axis   dimension="x|y|z" 
            visible="boolean"
            logarithmic="boolean"
            font-color="hexadecimal color"
            font-size="float(pt|cm|in|mm)"
            axis-position="start|end"
            origin="float"
            maximum="float"
            minimum ="float"
            label-arrangement="side-by-side|stagger-even|stagger-odd"
            display-level="boolean"
            axis-label-position="near-axis|near-axis-other-side|outside-end|outside-start"
            reverse-direction="boolean"
            text-overlap="boolean"
            line-break="boolean"
            stroke="solid|dash|none"
            stroke-width="float(pt|cm|in|mm)"
            stroke-color="hexadecimal color"
            stroke-opacity="integer%"
            stroke-linejoin="round|bevel|middle|miter|none"
            stroke-linecap="butt|round|square"
            interval-major="float"
            interval-minor-divisor="integer"
            tick-marks-major-inner="boolean"
            tick-marks-minor-inner="boolean"
            tick-marks-major-outer="boolean"
            tick-marks-minor-outer="boolean" />
    <component      type="wall|floor" 
                    fill-color="hexadecimal color"
                    opacity="integer%"
                    stroke="solid|dash|none"
                    stroke-width="float(pt|cm|in|mm)"
                    stroke-color="hexadecimal color"
                    stroke-opacity="integer%"
                    stroke-linejoin="round|bevel|middle|miter|none"
                    stroke-linecap="butt|round|square" />
    <transform3D    rotate-x="integer" 
                    rotate-y="integer" 
                    rotate-z="integer" 
                    right-angled-axes="true|false" 
                    perspective="integer" />
    <!-- for pie and donut charts -->
    <categories>
        <category       name="" 
                        value=""
                        fill-color="hexadecimal color"
                        opacity="integer%"
                        stroke="solid|dash|none"
                        stroke-width="float(pt|cm|in|mm)"
                        stroke-color="hexadecimal color"
                        stroke-opacity="integer%" />
        <category       name="" 
                        value=""
                        fill-color="hexadecimal color"
                        opacity="integer%"
                        stroke="solid|dash|none"
                        stroke-width="float(pt|cm|in|mm)"
                        stroke-color="hexadecimal color"
                        stroke-opacity="integer%" />
        <category       name="" 
                        value=""
                        fill-color="hexadecimal color"
                        opacity="integer%"
                        stroke="solid|dash|none"
                        stroke-width="float(pt|cm|in|mm)"
                        stroke-color="hexadecimal color"
                        stroke-opacity="integer%" />
    </categories>
    <!-- for bubble charts -->
    <series>
        <ser    name="" 
                fill-color="hexadecimal color"
                opacity="integer%"
                stroke="solid|dash|none"
                stroke-width="float(pt|cm|in|mm)"
                stroke-color="hexadecimal color"
                stroke-opacity="integer%" />
    </series>
    <categories>
        <category>
            <data value="" />
            <data value="" />
            <data value="" />
        </category>
        <category>
            <data value="" />
            <data value="" />
            <data value="" />
        </category>
        <category>
            <data value="" />
            <data value="" />
            <data value="" />
        </category>
    </categories>
    <!-- for all other charts -->
    <series>
        <ser    name="" 
                fill-color="hexadecimal color"
                opacity="integer%"
                stroke="solid|dash|none"
                stroke-width="float(pt|cm|in|mm)"
                stroke-color="hexadecimal color"
                stroke-opacity="integer%" />
        <ser    name="" 
                fill-color="hexadecimal color"
                opacity="integer%"
                stroke="solid|dash|none"
                stroke-width="float(pt|cm|in|mm)"
                stroke-color="hexadecimal color"
                stroke-opacity="integer%" />
    </series>
    <categories>
        <category name="">
            <data value="" />
            <data value="" />
        </category>
        <category name="">
            <data value="" />
            <data value="" />
        </category>
        <category name="">
            <data value="" />
            <data value="" />
        </category>
    </categories>
</chart>

Date

The <date> tag allows for the insertion of the current date into the document.

A simple example of use is given by the following HTML:

<p>Today is the <date format="('day', '/', 'month', '/', 'year')" />.</p>
<p>If the requested document output is Word or Open Document format the date can be updated by the user. 
The actual procedure may depend on the program used to open the file (MS Word, Libre Office, etcetera).</p>

DOWNLOAD: Template JSON Doc

Its corresponding schema is very simple.

<date>

Child elements

  • No child elements

Attributes

  • format (type: string). The date is built
    by concatenating the different tokens enclosed between parenthesis. The tokens may be:
    • A character or string of text.
    • A day, month or year in the following formats:
      • day: day of the month with two digits.
      • day-short: day of the month with one/two digits (as required).
      • day-of-week: day of the week in textual format.
      • day-of-week-short: abbreviated day of the week in textual format.
      • month: month of the year with two digits.
      • month-short: month of the year with one/two digits (as required) .
      • month-of-year: month of year in textual form.
      • month-of-year-short: month of year in abbreviated textual form.
      • year: year number with four digits.
      • year-short: year number with 2 digits.

Endnotes and footnotes

The <endnote> and <footnote> tags allow for the insertion of endnotes and footnotes in the current document.

A simple example of use is given by:

<p>This is a very beautiful<footnote>Beauty is <em style="color:red">in the eye</em> of the beholder.</footnote> document with a footnote.</p>

DOWNLOAD: Template JSON Doc

<endnote> & <footnote>

Child elements

  • Any HTML5 inline tag: span, strong, i, em, ...

Attributes

  • No attributes.

Math equations

The <math> tag allows for the insertion of math equation into the current document in MathML 1.0 format.

A simple example on how to do so is just given by the following HTML code:

<p>A document with some math inserted as extended HTML:</p>
<p style="text-align: center">
    <math base-font-size="18">
        <mrow>
            <mrow>
                <mstyle mathvariant="bold">
                    <mrow>
                        <mi>A</mi>
                    </mrow>
                </mstyle>
                <mo stretchy="false">=</mo>
                <mfenced open="[" close="]">
                    <mrow>
                        <mtable>
                            <mtr>
                                <mtd>
                                    <mrow>
                                        <mi>a</mi>
                                    </mrow>
                                </mtd>
                                <mtd>
                                    <mrow>
                                        <mi>b</mi>
                                    </mrow>
                                </mtd>
                            </mtr>
                            <mtr>
                                <mtd>
                                    <mrow>
                                        <mi>c</mi>
                                    </mrow>
                                </mtd>
                                <mtd>
                                    <mrow>
                                        <mi>d</mi>
                                    </mrow>
                                </mtd>
                            </mtr>
                        </mtable>
                    </mrow>
                </mfenced>
            </mrow>
        </mrow>
    </math>
</p>

DOWNLOAD: Template JSON Doc

The support of Math in Word formats (.doc and .docx) is only partial because there are some limitations in the formatting of the equations.

<math>

Child elements

  • Any MathML 1.0 content.

Attributes

  • No attributes.

Page numbering

The <page> tag allows for the insertion of page numbering into the document.

A simple example of use is given by:

<footer style="min-height: 1cm">
<p style="text-align: right; font-weight:bold; color: #777;"> Page <page/> of <page type="count"/></p>
</footer>
<p>A simple document with two pages.</p>
<p style="page-break-before: always">The second page.</p>

DOWNLOAD: Template JSON Doc

Its corresponding schema is given by:

<page>

Child elements

  • No child elements

Attributes

  • type (type: string, default: number). The possible values are number (current page number) or count (toal page count).
  • format (type: string, default: 1). The possible values are: 1,a,A,i or I.
  • offset (type: integer, default: 0). The starting value.

Tabs

The <tab> tag allows for the insertion of tabs in the document.

A simple example of use is given by:

<p>
First
<tab position="200" type="right" leader="dotted" />
Second
<tab position="200" type="right" leader="dotted"/>
Third.
</p>

DOWNLOAD: Template JSON Doc

Its corresponding schema is given by:

<tab>

Child elements

  • No child elements

Attributes

  • type (type: string, default: left). Specifies tab alignment, possible values are: left, center, right or char.
  • leader (type: string, default: .). The character used for alignment (ignored if the type does not equal char).
  • character (type: string, default: none). Specifies the leader char. The available options are: none, dash, dot-dash, dot-dot-dash, dotted, long-dash, solid and wave.
  • position (type: integer). Distance from the left margin or the left indent given in points (if not given the default value for each document format will be used).

Table of contents

The <toc> tag allows for the insertion of a table of contents within the document.

A simple example of use is given by:

<style>
h1{font-family: Arial; font-size: 18pt; color: #b70000; page-break-before: always;}
h2{font-family: Arial; font-size: 16pt; color: #4456ff}
</style>
<p style="font-size: 16pt; font-weight: bold; color: #5566cc;">Table of Contents</p>
<toc>
	<outline level="1" style="font-weight: bold" />
	<outline level="2" style="color: #000077" />
</toc>
<h1>First title</h1>
<p>Sample text.</p>
<h2>Subtitle</h2>
<p>Another text.</p>
<h1>Second title</h1>
<p>Final text.</p>

DOWNLOAD: Template JSON Doc

Its corresponding schema is composed of two elements:

<toc>

Child elements

  • outline: this optional child element specifies the formatting of the different TOC levels.

Attributes

  • title (type: string). An optional TOC title (level 0 for styling). The possible values are number (current page number) or count (toal page count).
  • leader (type: string, default: '.'). The leader char joining the toc entry with the corresponding page number.
  • linked (type: boolean, default: true). If true the toc entries are a link the corresponding content.
  • level (type: integer, default: 6). The highest heading level that is parsed in the TOC.

<outline>

Child elements

  • No child elements.

Attributes

  • level (type: integer). The level to which appy the style (from 0 to 6).
  • style (type: string). The entry styles in CSS format.