HTML Extended and CSS Extended

Introduction

Thanks to HTML Extended and CSS Extended functionality, it is possible to invoke phpdocx methods, styles and options not available through standard HTML tags or CSS styles. Thus, you can add contents such as headers, footers, comments, table of contents, cross-references and many other contents types, insert new sections, access properties and styles not available in CSS and even add WordFragments.

This feature, available for Premium licenses, integrates with the embedHTML and replaceVariableByHTML methods with a set of custom tags that can be combined even with other HTML and CSS contents.

HTML Extended and CSS Extended have an extra set of methods and options designed to make conversions more flexible and efficient:

addBaseCSS: defines a base CSS for all HTML conversions.
stylesReplacementType: available for the replaceVariableByHTML method, it allows using the original placeholder styles (pPr y rPr) instead of the ones defined by the imported HTML and CSS, and mix HTML and placeholder styles.
embedFonts: embeds TTF fonts from @font-face rules.
support overwriting styles in level lists: create lists with different styles in the same levels.
extraHTMLExtendedOptions: transform additional contents just like tabs.

The HTML API documentation includes an exhaustive list of tags and styles included in HTML Extended and CSS Extended.

Supported contents

This is the complete list of supported contents and their default tags:

addBookmark: phpdocx_bookmark
addBreak: phpdocx_break
addComment: phpdocx_comment
addCrossReference: phpdocx_crossreference
addDateAndHour: phpdocx_dateandhour
addEndnote: phpdocx_endnote
addFooter: phpdocx_footer
addFootnote: phpdocx_footnote
addFormElement: phpdocx_formelement
addHeader: phpdocx_header
addHeading: phpdocx_heading
addImage: phpdocx_image
addLink: phpdocx_link
addMathEquation: phpdocx_mathequation
addMergeField: phpdocx_mergefield
addOle: phpdocx_ole
addOnlineVideo: phpdocx_onlinevideo
addPageNumber: phpdocx_pagenumber
addSection: phpdocx_section
addShape: phpdocx_shape
addSimpleField: phpdocx_simplefield
addStructuredDocumentTag: phpdocx_structureddocumenttag
addTableContents: phpdocx_tablecontents
addTableFigures: phpdocx_tablefigures
addText: phpdocx_text
addTextBox: phpdocx_textbox
addWordFragment: phpdocx_wordfragment
addWordML: phpdocx_wordml
math: MathML equation
meta: document properties
modifyPageLayout: phpdocx_modifypagelayout
title: document title

As explained further on, almost all tags can be customized.

Tag types

Tags are divided in two types: inline and block.

The inline ones do not admit children elements. They are the following:

meta
phpdocx_bookmark
phpdocx_break
phpdocx_crossreference
phpdocx_dateandhour
phpdocx_formelement
phpdocx_heading
phpdocx_image
phpdocx_link
phpdocx_mathequation
phpdocx_mergefield
phpdocx_ole
phpdocx_onlinevideo
phpdocx_pagenumber
phpdocx_section
phpdocx_shape
phpdocx_simplefield
phpdocx_structureddocumenttag
phpdocx_tablecontents
phpdocx_text
phpdocx_textbox
phpdocx_wordfragment
phpdocx_wordml
title

The block ones allow children, either of the HTML or the HTML Extended tags. They are the following:

math
phpdocx_comment
phpdocx_endnote
phpdocx_footer
phpdocx_footnote
phpdocx_header

Options for each method are added with custom data attributes. You just need to write the option name after the prefix data-. E.g.: data-bold="true", data-type="start" o data-type="default".

Supported custom attributes and styles

Custom styles and custom attributes

In addition to the previous methods and styles, CSS Extended supports custom styles and attributes in HTML standard tags:

font-face: embed a TTF font
border-spacing: paragraph border spacing
data-depth: force a level in a li tag
data-fit-text: fit the width of the cell
data-font-size: "initial" avoids applying a font size
data-em: emphasis mark type
data-heading-level: set outline level to contents without using heading tags
data-highlight: highlight style
data-label: set a custom label to apply to captions
data-lang: set a custom language: language-region (en-US)
data-listppr: paragraph style in numberings
data-listrpr: run-of-text style in numberings
data-ppr: paragraph style
data-rpr: run-of-text style
data-style: apply a custom character/paragraph/table style
data-tblpr: table style
data-trpr: row style
data-tcpr: cell style
max-height: image max height
max-width: image max width

Insert &#9; to add tabs.

Examples

HTML Extended is as easy to use as standard HTML tags. It is just necessary to enable the useHTMLExtended option to start working with the custom tags and styles.

Insert two bookmarks and a paragraph:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$html = '
    <phpdocx_bookmark data-type="start" data-name="bookmark_name" />
    <p>Text with a bookmark</p>
    <phpdocx_bookmark data-type="end" data-name="bookmark_name" />
';
$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_1');

Add a TOC based on headings created with HTML and phpdocx tags:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

// add a table of contents
$html = '<phpdocx_tablecontents data-autoUpdate="true" data-stylesTOC="document.docx"/>';
$docx->embedHTML($html, array('useHTMLExtended' => true));

// add HTML headings
$html = '
    <h1 style="color: #b70000">1st level heading</h1>
    <h2 style="color: #b70000">2nd level heading</h2>
    <h3 style="color: #b70000">3rd level heading</h3>
';
$docx->embedHTML($html, array('useHTMLExtended' => true));

// add phpdocx headings
$html = '
    <phpdocx_heading data-text="Custom heading" data-level="2" />
';
$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_2');

Place headers and footers:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$html = '
    <head>
        <style>
            p {font-style: italic;}
            p.header {font-size: 20px; font-weight: bold;}
            div.footer {font-size: 10px;}
        </style>
    </head>
    <phpdocx_header data-type="default">
        <p class="header">
            Custom header <strong>with strong style</strong>
            <phpdocx_link data-text="External link" data-url="http://www.google.es" />
        </p>
    </phpdocx_header>
    <p>Lorem ipsum dolor sit amet.</p>
    <phpdocx_footer>
        <div class="footer">
            <table border="1" style="border-collapse: collapse" width="600">
                <tbody>
                    <tr width="600">
                        <td>Cell A</td>
                        <td><img src="image.png" width="35" height="35" style="vertical-align: -15px"></p></td>
                        <td><phpdocx_pagenumber data-target="defaultFooter" data-type="page-of" data-textAlign="right" /></td>
                    </tr>
                </tbody>
            </table>
        </div>
    </phpdocx_footer>
';

$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_3');

Add comments, endnotes and footnotes:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$html = '
    <head>
        <style>
            p.italicc {font-style: italic;}
        </style>
    </head>
    <phpdocx_comment>
        <p>Here comes the </p>
        <phpdocx_comment_textdocument data-text=" comment " data-italic="true" />
        <phpdocx_comment_textcomment>
            <p class="italicc">Text <strong>comment</strong></p>
        </phpdocx_comment_textcomment>
        <p>and some other text.</p>
    </phpdocx_comment>
    <h1 style="color: #b70000">A HTML Extended example.</h1>
    <phpdocx_endnote>
        <p>Here comes the </p>
        <phpdocx_endnote_textdocument data-text=" endnote" data-italic="true" />
        <phpdocx_endnote_textendnote>
            <p class="italicc">Text <strong>endnote</strong></p>
        </phpdocx_endnote_textendnote>
        <p>and some other text.</p>
    </phpdocx_endnote>
    <phpdocx_comment>
        <phpdocx_comment_textdocument data-text="Here comes another comment " data-italic="true" data-bold="true" />
        <phpdocx_comment_textcomment>
            <p>This is some HTML code with a link to <a href="https://www.phpdocx.com">phpdocx.com</a> and a random image:
            <img src="image.png" width="35" height="35" style="vertical-align: -15px"></p>
        </phpdocx_comment_textcomment>
        <p> and some other text.</p>
    </phpdocx_comment>
    <phpdocx_footnote>
        <p>Here comes the </p>
        <phpdocx_footnote_textdocument data-text=" footnote" data-bold="true" />
        <phpdocx_footnote_textfootnote>
            <p>Text <em>footnote</em></p>
        </phpdocx_footnote_textfootnote>
        <p> and some other text.</p>
    </phpdocx_footnote>
';


$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_3');

As shown in this example, comments, endnotes and footnotes require a specific structure in order to correctly add all their content.

Apply custom styles:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$html = '
    <p>HTML content.</p>
    <p data-ppr="'.htmlentities('<w:pageBreakBefore val="on"/>').'">HTML with <span data-rpr="'.htmlentities('<w:strike/>').'">custom</span> <span data-rpr="'.htmlentities('<w:dstrike/>').'">attributes</span> in tags.</p>
';

$html .= '<table border="1" style="border-collapse: collapse" width="600">
            <tbody>
                <tr width="600" data-trpr="'.htmlentities('<w:trHeight w:val="1200" w:hRule="exact"/>').'">
                    <td style="background-color: yellow" data-tcpr="'.htmlentities('<w:tcFitText w:val="on"/>').'">1_1</td>
                    <td rowspan="3" colspan="2">1_2</td>
                </tr>
                <tr width="600">
                    <td>Some random text.</td>
                </tr>
                <tr width="600">
                    <td>
                        <ul>
                            <li>One</li>
                            <li>Two <b>and a half</b></li>
                        </ul>
                    </td>
                </tr>
                <tr width="600">
                    <td>3_2</td>
                    <td>3_3</td>
                    <td>3_3</td>
                </tr>
            </tbody>
        </table>';

$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_4');

How to customize the tags

Tags related to each method can be customized with two static variables: HTMLExtended::$tagsBlock and HTMLExtended::$tagsInline.

For example, to define "header" and "footer" as tags associated to addHeader and addFooter:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

HTMLExtended::$tagsBlock['header'] = 'addHeader';
HTMLExtended::$tagsBlock['footer'] = 'addFooter';

$html = '
    <head>
        <style>
            p {font-style: italic;}
            p.header {font-size: 20px; font-weight: bold;}
            div.footer {font-size: 10px;}
        </style>
    </head>
    <header data-type="default">
        <p class="header">
            Custom header <strong>with strong style</strong>
            <phpdocx_link data-text="External link" data-url="http://www.google.es" />
        </p>
    </header>
    <p>Lorem ipsum dolor sit amet.</p>
    <footer>
        <div class="footer">
            <table border="1" style="border-collapse: collapse" width="600">
                <tbody>
                    <tr width="600">
                        <td>Cell A</td>
                        <td><img src="image.png" width="35" height="35" style="vertical-align: -15px"></p></td>
                        <td><phpdocx_pagenumber data-target="defaultFooter" data-type="page-of" data-textAlign="right" /></td>
                    </tr>
                </tbody>
            </table>
        </div>
    </footer>
';

$docx->embedHTML($html, array('useHTMLExtended' => true));

$docx->createDocx('htmlExtended_4');

Set a base CSS

The addBaseCSS method inserts a group of CSS styles to be applied for every HTML import. This allows to convert HTML contents that share a common set of styles without the need of adding them after each embedHTML call. These base styles can be overwritten with new styles when importing HTML.

For example, the next code adds a base CSS to be applied to all paragraphs imported from HTML, then overwrites the style with embedHTML:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

// set a base CSS to be applied. These styles can be overwritten using style tags and inline styles
$docx->addBaseCSS('
        p {font-weight: bold;font-size: 18px;}
');

$html = '
    <p>HTML content.</p>
';
$docx->embedHTML($html);

$html = '
    <style>
        p {font-size: 10px;font-style: italic;}
    </style>
    <p>HTML content.</p>
';

$docx->embedHTML($html);

$html = '
    <p style="font-size: 14px;font-weight: normal;">HTML content.</p>
';
$docx->embedHTML($html);

$docx->createDocx('htmlExtended_5');

Replace placeholders keeping styles

The replaceVariableByHTML method replaces a placeholder by HTML. This procedure leads to the application of the styles imported from HTML and the removal of the original placeholder ones. Using the stylesReplacementType option, the applied styles can be changed:

usePlaceholderStyles: styles from the imported HTML are ignored.
mixPlaceholderStyles: mix placeholder styles, placeholder styles overwrite HTML styles with the same name. Used with stylesReplacementTypeIgnore, this option allows choosing the styles to be applied. The stylesReplacementTypeOverwrite option allows HTML styles to overwrite placeholder styles.

For example, the code that follows replaces VAR for HTML, preserving the styles defined in the placeholder template:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocxFromTemplate('template');

$docx->replaceVariableByHTML('VAR', 'inline', '<p>New HTML <b>content</b></p>', array('stylesReplacementType' => 'usePlaceholderStyles'));

$docx->createDocx('htmlExtended_6');

The following code mixes HTML and placeholder styles, ignoring the font size from the HTML:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocxFromTemplate('template');

$docx->replaceVariableByHTML('VAR', 'inline', '<p>New HTML <b>content</b></p>', array('stylesReplacementType' => 'mixPlaceholderStyles', 'stylesReplacementTypeIgnore' => array('w:sz', 'w:szCs')));

$docx->createDocx('htmlExtended_7');

List level override

With custom list styles, you may import HTML while applying different styles for each level.

The following code creates a list with three items and defines different list styles for the secondary sublevels:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

// custom options
$latinListOptions = array();
$latinListOptions[0]['type'] = 'lowerLetter';
$latinListOptions[0]['format'] = '%1.';
$latinListOptions[1]['type'] = 'lowerRoman';
$latinListOptions[1]['format'] = '%1.%2.';

// override
$overrideListStyleOptionsFirst = array();
$overrideListStyleOptionsFirst[0]['type'] = 'upperRoman';
$overrideListStyleOptionsFirst[0]['format'] = '%1.';
$overrideListStyleOptionsFirst[1]['type'] = 'lowerRoman';
$overrideListStyleOptionsFirst[1]['format'] = '%2.';

$overrideListStyleOptionsSecond = array();
$overrideListStyleOptionsSecond[0]['type'] = 'upperLetter';
$overrideListStyleOptionsSecond[0]['format'] = '%1.';

$overrideListStyle = array();
$overrideListStyle[0] = array(
    'listOptions' => $overrideListStyleOptionsFirst,
    'name' => 'latinUR',
);
$overrideListStyle[1] = array(
    'listOptions' => $overrideListStyleOptionsSecond,
    'name' => 'latinUL',
);

// create the list style with name: latin
$docx->createListStyle('latin', $latinListOptions, $overrideListStyle);

$html = '
<ul class="latin">
    <li>First item.</li>
    <li>Second item with subitems:
        <ul class="latinUR">
            <li>First subitem.</li>
            <li>Second subitem.</li>
            <li>Third subitem.</li>
        </ul>
    </li>
    <li>Third item with subitems and other styles:
        <ul class="latinUL">
            <li>First subitem.</li>
            <li>Second subitem.</li>
        </ul>
    </li>
    <li>Last item.</li>
</ul>';
$docx->embedHTML($html, array('customListStyles' => true, 'useHTMLExtended' => true));

$docx->createDocx('htmlExtended_8');

Embed fonts

Enabling the embedFonts option, TTF fonts included in CSS styles using @font-face rules will be added to the DOCX as embedded fonts.

The following code embeds Lato-Regular.ttf in the DOCX and sets it as font family of the paragraph:

require_once 'pathToPHPDocX/classes/CreateDocx.php';

$docx = new CreateDocx();

$html = '
    <style>
        @font-face {
            font-family: latto;
            src: url(lato-fonts/Lato-Regular.ttf);
        }
    </style>
    <p style="font-family: latto;">Paragraph with Latto as font family.</p>
';
$docx->embedHTML($html, array('useHTMLExtended' => true, 'embedFonts' => true));

$docx->createDocx('htmlExtended_9');

CSS Extended: inheritance

In addition to the set of styles that CSS Extended expands with regard to the standard styles, it also allows to define new styles for the descendant elements to inherit from their parent ones.

The static variable HTMLExtended::$cssExtendedStylesInherited allows to define and add new inherited styles.

Additional information

Section tags can be added only once for each embedHTML call.

HTML Extended and CSS Extended