Working with headings using PHP methods and HTML contents

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.

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:

Styles can be imported too:

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.