HTML Extended

HTML Extended

Introduction

Thanks to the HTML Extended functionality, it is possible to invoke phpdocx methods, styles and options not available through standard HTML tags. 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 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 also has 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 uses the original placeholder styles (pPr y rPr) instead of the ones defined by the imported HTML and CSS.
  • support overwriting styles in level lists: create lists with different styles in the same levels.
  • extraHTMLExtendedOptions: transform additional contents just like tabs.
Supported contents

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
  • 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
  • modifyPageLayout: phpdocx_modifypagelayout

As explained further on, tags used on each method 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:

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

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

  • 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 styles

Custom styles

This is the complete list of supported custom styles and their attribute names:

  • 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-tblpr: table style
  • data-trpr: row style
  • data-tcpr: cell style
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:

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

Place headers and footers:

Add comments, endnotes and footnotes:

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

Apply custom styles:

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:

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:

Replace placeholders keeping styles

The replaceVariableByHTML method replaces a placeholder for HTML. This procedure leads to the application of the styles imported from HTML and the removal of the original placeholder ones. When using the stylesReplacementType option, the styles imported from the HTML are ignored, and the ones defined in the replaced placeholder are applied.

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

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:

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