Cookbook

phpdocx has the necessary methods to add headings to documents, either with the addHeading method or transforming HTML/CSS.

Before checking the available methods and options, it is important to understand that DOCX documents define the outline level of the contents with a tag, w:outlineLvl, that builds the Table of Contents and doesn't affect the apperance of the text. On the other hand, the content may have a style highlighted on the interface of the DOCX editor.

Therefore, it is possible to create a content for the Table of Contents with no style applied from the ones available on the MS Word interface. Default styles on new documents, such as Heading 1 or Heading 2, use the w:outlineLvl tag automatically. The base phpdocx template doesn't include the Heading 1 or Heading 2 styles but some other ones called Heading1PHPDOCX, Heading2PHPDOCX...

To define contents as headings you can insert and choose the phpdocx styles or others available on templates or imported from external DOCX documents.

Getting heading style names

Default heading style names depend on the MS Word language used to generate the document. For example, using an english version of MS Word the styleId for heading 1 is Heading1, a german version generates it as berschrift1, a french version as Titre1, and so on. These names can also be customized.

The following methods can be used to get the heading style names available in a document: getWordStyles, parseStyles and indexer.

Using PHP methods

The method addHeading adds a text with the specified outline level on the second parameter:

Unless different styles are stated, addHeading automatically applies some default styles: bold, keepLines, keepNext, widowControl, size depending on the outline level and Cambria as font. Those styles can be modified with the options available in the method.

If, instead of addHeading, the method addText is chosen, the parameter headingLevel defines the content outline level, without applying additional default styles:

The methods seen so far state the outline level but don't highlight any style on the MS Word interface. The parameter pStyle, compatible with both methods, indicates the style to be applied:

As the Heading2PHPDOCX style already has a defined outline level, it is not mandatory to specify it again.

One can choose not to work with the heading styles included in the base template of phpdocx and call other ones instead, like Heading1, Heading2, and so on. This can be done with MS Word, by creating a template with those styles included:

External styles can be imported into the current document:

Adding HTML contents

The embedHTML and replaceVariableByHTML methods allow to transform heading tags (h1, h2, h3, h4, h5, h6), to apply predefined styles to them and to insert the pertinent outline level:

Predefined styles can be modified with CSS in the HTML meant for conversion.

To associate tags with an specific style it is required to use the option wordStyles:

Premium licenses come with HTML Extended, which simplifies this association process with the help of the data-style attribute:

Just like with the addHeading and addText methods, the HTML methods allow to use both the template and the imported styles instead of the predefined ones of the base phpdocx template:

In order to apply just the heading styles while omitting the majority of the predefined CSS styles it is mandatory to enable the strictWordStyles option:

HTML Extended integrates the phpdocx_heading tags in order to invoke the addHeading method with HTML. This tag can work as a substitute of the standard heading tags and has a larger number of options for applying styles.