HTML to Word

HTML to Word

Introduction

The conversion of HTML into Word is one of the most requested functionalities of phpdocx. PHP was born as a server tool for the generation of dynamical HTML pages, so it is no wonder that many of our phpdocx users are pretty familiar with that type of task and they want to take advantage of those skills for the generation of Word documents.

Since v2.5 phpdocx offers pretty sophisticated ways to include HTML formatted content into a Word document. The purpose of this tutorial is to offer a detailed account on how one can do it and how to get the most of it.

There are currently two methods to include HTML into a Word document generated from scratch (the case of templates will be treated further below) with phpdocx:

  • addExternalFile()
  • embedHTML()

The first of them uses internally the “alternative content” element available in the OOXML standard (on which Word is based) and it is simple to use although it has two main drawbacks:

  • It is not compatible with Open Office and/or PDF conversion.
  • There is no much flexibility in the rendering options.

This said, it may be an interesting option if none of the above represents an issue for a given application.

In what follows we will concentrate in the embedHTML method and the replaceTemplateVariableByHTML (its avatar for working with Word templates).

The main advantages of the embedHTML methods are summarised in:

  • The HTML code is translated into native WordML code so the resulting document may be rendered in Open Office and transformed to PDF with the help of the phpdocx conversion plugin (included in the PRO+ and CORPORATE versions of the library).
  • One may use native Word styles for paragraphs and tables.
  • One may filter the HTML content by ids, CSS classes and HTML tags or even by simple XPath expressions.
  • One may include the images included in the HTML code within the Word document or as external resources.
  • If there are headings thay may get included into a Table of Contents.
  • It allows for the direct insertion of HTML+CSS code or the embedding an preprocessing of an external web page.
  • Since v3.0 the resulting WordML may be also inserted in headers and footers.

And once again with a single line of PHP code.

But, let us now get down to the nitty-gritty.

Basic Examples

Let us first offer a few simple examples that illustrate the basic procedures:

Simple HTML code

The code needed to insert some plain HTML is as simple as this:

                                require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='

This is a simple paragraph with text in bold.

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2
Cell 2 1 Cell 2 2
'; $docx->embedHTML($html); $docx->createDocx('simpleHTML');

And you will get as a result (download the corresponding document):

Let us first offer a few simple examples that illustrate the basic procedures:

                                require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='

								

This is a simple paragraph with text in bold.

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2
Cell 2 1 Cell 2 2
'; $docx->embedHTML($html); $docx->createDocx('simpleHTML');

And you will get as a result (download the corresponding document):

 

External HTML source

Sometimes one may need to get the HTML and CSS from existing external files but as we will now show this also turns to be extremely simple.

Let us assume that the HTML code above proceeds from an external html page: simpleHTML.html that links to a CSS stylesheet: styles.css.

Then the following code will render exactly the same results:

                                require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='http://www.2mdc.com/PHPDOCX/simpleHTML.html';

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

								$docx->createDocx('simpleHTML');
                            

Notices that the only differences are:

  • The $html variable is now the path to an external HTML page.
  • The option isFile is set to true to indicate phpdocx that the variable $html is a path rather than HTML code.

HTML code embeded within a Word table

It may well be that we choose not to embed directly the HTML code into the document but rather insert it within another document element like a table or a header/footer.

This can be achieved in a very simple way by setting the rawWordML option to true.

We may modify slightly the previous example:

                                require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='http://www.2mdc.com/PHPDOCX/simpleHTML.html';

								$myHTML = $docx->embedHTML($html, array('isFile' => true, 'rawWordML' => true));

								$HTMLFragment = $docx->createWordMLFragment(array($myHTML));

								$values = array(array(11,12),array($HTMLFragment,22));
								$options = array('border' => 'single','border_sz' => 20);
								$docx->addTable($values, $options);

								$docx->createDocx('simpleHTML'); 
                            

Obtaining now the following result (download the corresponding Word document):

 

Embedding images

To include images is equally simple. One may choose to include the images within the document (with the option downloadImages set to true) or keep them as an externally linked resource (in that case you should make sure that the image is available to the final users).

A simple example that makes use of this simple web page with an image reads as follows:

                                require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='http://www.2mdc.com/PHPDOCX/simpleHTML_Image.html';

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

								$docx->createDocx('simpleHTML'); 
                            

The resulting Word document looks as follows (download the corresponding document):

Notice that like in this case we have not declared the width and height attributes of the image, phpdocx reads its properties from the image header and inserts it with a resolution of 96 dpi (default resolution). One may, of course, choose custom width and height to obtain the desired results.

Supported HTML tags and attributes

phpdocx parses all the most commonly used HTML tags and attibutes.

It is important to take into account that the HTML and OOXML that Word is based on have different goals so at some points the translation from one to the other should include certain compromises that are not universally valid for all applications. Fortunately it is not difficult to find convenient workarounds that offer a close to perfect Word rendering.

The list of currently parsed HTML elements include:

Block type HTML elements

  • div: although this tag is probably the most used in modern HTML code it does not have a direct translation into Word.phpdocx offer different parsing options:
    • Only use it for the CSS inheritance and parse consequently its child elements.
    • Parse them as a "p" element with the option "parseDivs" set to "paragraph"(this may be an useful option when using HTML code coming from a WYSIWYG editor).
    • Parse it as a table with the option "parseDivs" set to "table" . This may be the most accurate option if one may decide to preserve all available formatting but may produce complicated Word documents that may be later difficult to edit manually (if that is an interesting option).
  • p: this is, of course a native Word element so it is parsed as expected.
  • h1, h2, h3, h4, h5 and h6: they are parsed as Word headings and as such they may show up in a TOC included in the Word document.
  • ul and ol: are respectively parsed as unordered or ordered Word lists.
  • li: are parsed like individual list items belonging to a predefined ordered or unordered list.
  • dl, dt, dd: are treated like definition lists in standard HTML.
  • table: are, of course, parsed as Word tables and the following attributes are taken into account:border, align and cellspacing. Of course all its child are consequently parsed: thead, tbody, tr, th and td and its corresponding colspan and rowspan attributes.
  • img: images are converted into Word images and they can be integrated in the Word document by setting the option "downloadImages" to true or, if prefered, be kept like an external resource (this option could be particularly interesting if we expect the image to change with time), this, of course, requires an open Internet connection whenever the Word document is visualised. Besides the src attribute the width and height are also parsed. All other styling options should be defined via CSS properties.
  • br and hr: they include, respectively, a line break and an horizontal ruler in the Word document.

Inline type HTML elements

  • a: are parsed as external links, internal links or bookmarks (with the parseAnchors set to true in the last two cases) depending on the value of the href or name attribute.
  • strong, b, i, em, u, span, sup, sub, blockquote, address, center, listing, plaintext, xmp, pre, cite, var, dfn, tt, code, kbd, ins, s, strike, del, big, small: are parsed as text with tehir corresponding default properties unless they are overwritten by explicit CSS style properties.

HTML web form elements

  • input: The inputs are parsed depending on their type attribute:
    • text: is converted into a Word text field. The size attribute determines the corresponding length in the Word field.
    • checkbox and radio: in both cases they are converted into Word checkboxes. The checked is parsed and activates the checked elements in the Word document.
  • select and option: They transform into the corresponding Word dropdown field element with their corresponding options. Once again if there is a selected option in the HTML code it appears selected by default in the Word document.

    WARNINGS:

  • That a tag is not parsed does not mean that its content dissapears from the Word document. It only implies that their associated HTML properties are not taken directly into account. Their childs and text content will be parsed and rendered with their corresponding styles into the Word document.
Supported CSS properties

Currently almost all CSS properties, that are posibly applicable to a document, are parsed and translated into their Word counterparts.

In order to achieve the best posible results it is important to know how these CSS properties are applied and their known limitations regarding the final document rendering.

The list of currently parsed CSS styles include:

Border styles and background color

The following border properties are parsed:

  • border: one may introduced combined properies as, for example, "1px solid red". Some comments about units and format:
    • Units: one may use pixels, points or ems.
    • Styles: the available styles are: none, dotted, dashed, solid, double, groove, inset, outset.
    • Colors: one can use hexadecimal values like #ff0000 or, if it exits, standard CSS colors like "red" (standard CSS color names list).
  • border-[top, right, bottom, left]: same as above but letting you to choose different borders styles for top, right, bottom and left borders.
  • border-[top, right, bottom, left]-color: sets up independently the color for each border.
  • border-[top, right, bottom, left]-style: sets up independently the style (solid, dotted, …) for each border.
  • border-[top, right, bottom, left]-width: sets up independently the size (in pixels, points or ems) for each border.
  • border-collapse: allows for collapse or separate.
  • background-color: hexadecimal or standard CSS value.

Margins and paddings

The concept of padding has not a general direct counterpart in Word so it is usually interpreted as extra margin space.

  • margin and padding: one may use pixels, points or ems.
  • margin-[top, right, bottom, left] and padding-[top, right, bottom, left]: same as above but letting you to choose different margins and paddings for top, right, bottom and left.

Page break properties

This properties are partially supported:

  • page-break-after: if set to avoid is equivalent to the Word property of "Keep with next paragraph".
  • page-break-inside: if set to avoid is equivalent to the Word property of "Keep lines together".
  • page-break-before: if set to always is equivalent to the Word property of "Break page before". If it is set to avoid turns on Word widow/orphan control.

Font and text properties

The units may be pixels, points or ems and the colors follow the same scheme as above. The suported properties include:

  • font: if one uses the shorthand prperties one need to preserve the following order: font: font-style font-variant font-weight font-size/line-height font-family.
  • font-family: make sure to include a font family that may be supported by the Word interface (practically all the usual ones). The default value is "serif".
  • font-size: The default size is 12pt.
  • font-style: may be normal, italic or oblique.
  • font-variant: may be normal or small-caps.
  • font-weight: only recognise bold or bolder that are converted into bold in Word.
  • line-height: may be set in any of the available units.
  • color: hexadecimal value or standard CSS values.
  • text-decoration: may be underline or line-through.
  • text-align: the available values are left, center, right or justify.
  • text-indent: may be set in any of the available units.
  • text-transform: may be set to uppercase.

Positioning

phpdocx tries to adapt as best as posible the positioning properties of elements to equivalent Word properties. If you need to position precisely elements in the resulting Word document the best and simplest way is to use tables.

You may also instruct phpdocx to parse divs as tables (see, for example, above) or to parse floats with the "parseFloats" set to true (image floats are always parsed by default).

In any case results are usually pretty good and cover all but the most sophisticated examples.

The parsed properties include:

  • float: can be none, left or right.
  • vertical-align: can be given in pixels, points or ems or like super, sub, top, text-top, middle, baseline, bottom and text-bottom.

Lists

Since version 3.5 phpdocx handles pretty well the rendering f HTML lists and their associated CSS styles. Nevertheless, if you want to use bullets beyond the most standard ones you should the phpdocx embedding HTML methods in conjunction with the createListStyle method (by setting the 'useCustomStyles' option to true) to obtain the desired results.

In order to do so one should create a custom style that mimics the HTML result and give it the same name that is used in the HTML code for the corresponding class or id attribute. phpdocx will automatically use the corresponding formatting (bullets, indents, etcetera) previously defined by us.

In any case results are usually pretty good and cover all but the most sophisticated examples.

In case that we do not bother to define any custom list style the corresponding CSS list style property is parsed as follows:

  • list-style and list-style-type: when any of them is set to none no bullets or numbering is included and the CSS properties on margin and padding are used, for all other lists types the standard Word defaults are used.
Using native Word formatting with HTML

One of the nicest features of the embedHTML method is that it allows to use customized Word formatting for paragraphs and tables.

One may write plain HTML with little or none styling and yet generate a very sophisticated Word document.

The default base template already includes all standard Word styles for headings, paragraphs and tables. You may get all the available styles via the phpdocx parseStyles method.

Of course, yo may use a different base template that better suit your needs or even explicitely import styles from other docx via the phpdocx importStyles method.

Let us now go over a simple example that illustrates this functionality:

                                
								require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='
								

The title of the HTML page

A normal paragraph.

This is a simple paragraph with text in bold.

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2 Cell 1 3
Cell 2 1 Cell 2 2 Cell 2 3
'; $wordStyles = array('
' => 'LightListAccent3PHPDOCX, '

' => 'Heading1PHPDOCX' , '.heading2' => 'Heading2PHPDOCX'); $docx->embedHTML($html, array('strictWordStyles' => true, 'wordStyles' => $wordStyles)); $docx->createDocx('simpleHTML_wordStyles_true');

Notice that we have set the option strictWordStyles to true so the HTML parser will ignore the CSS properties and will apply exclusively the selected Word styles.

The resulting Word document looks as follows:

If one removes the option strictWordStyles or set it to false (its default value), phpdocx will try to combine the Word and HTML styles.

The resulting Word document reads (download the corresponding Word document):

 

Filtering HTML

Another useful functionality of the embedHTML method is the possibility to filter the HTML content that gets included in the Word document.

One may want to reuse HTML code that has been generated with a different goal in you Word document. A typical example is given by the contents of an existing web page from which we just want to extract its contents without menus or navigation that does not really fit into a Word document.

The filtering can be done in two different ways that we now pass to examine.

Basic expressions

One can select a set of HTML elements by tag, id or class (’’, ‘#myId’ or ‘.myClass’) in a very simple way as follows:

                                
								require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='

								

The title of the HTML page

A normal paragraph.

This is a simple paragraph with text in bold.

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2 Cell 1 3
Cell 2 1 Cell 2 2 Cell 2 3
'; $wordStyles = array('
' => 'LightListAccent3PHPDOCX', '

' => 'Heading1PHPDOCX' , '.heading2' => 'Heading2PHPDOCX'); $docx->embedHTML($html, array('strictWordStyles' => true, 'wordStyles' => $wordStyles, 'filter' => '
')); $docx->createDocx('simpleHTML_filtered');

The resulting Word document reads (download the corresponding Word document):

 

Using XPath expressions

One may choose to filter by more complex expressions that should take the form of valid PHP XPath expressions.

For example, if in the previous example we would have set up the filter option to: //p[@class="heading2"]|//ul|//table we would have obtained instead a Word document that will only include the paragraph with class heading2, the unordered list and the table.

                                
								require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$html='

								

The title of the HTML page

A normal paragraph.

This is a simple paragraph with text in bold.

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2 Cell 1 3
Cell 2 1 Cell 2 2 Cell 2 3
'; $wordStyles = array('
' => 'LightListAccent3PHPDOCX', '

' => 'Heading1PHPDOCX' , '.heading2' => 'Heading2PHPDOCX'); $docx->embedHTML($html, array('strictWordStyles' => true, 'wordStyles' => $wordStyles, 'filter' => '//p[@class="heading2"]|//ul|//table')); $docx->createDocx('simpleHTML_filtered');

We obtain this time (download the corresponding Word document):

 

Other general options

Besides all the options that have been carefully analysed before there are are other general options that we now pass to comment briefly.

  • ‘parseAnchors’ (boolean): if set to true it will parse the anchors included in the HTML file. Its default value is false.
  • ‘parseDivs’ (paragraph, table): although all CSS properties of div tags are inherited divs themselves are not parsed by default because there is no WordML element that exactly resemble its properties. When set to paragraph the phpdocx parser tries to parse them as standard paragraphs (this may be an useful option for HTML coming from certain WYSIWYG editors). If set to table renders the div as a Word table. Its default values is false.
  • ‘parseFloats’ (boolean): when set to true phpdocx tries to parse the floating divs and paragraphs as floating tables. Sometimes the results are impredictable, so use with care. Its default values is false.
  • ‘baseURL’ (boolean): forces the base URL of the relative links to the desired value. This option may be particularly useful if the HTML code is obtained via the PHP file_get_contents method or any similar procedure.
Inserting HTML into Word templates

All the precceding examples have their match in the case we are working with templates by means of the replaceTemplateVariableByHTML method.

All the available options are the same as before although we have to give two extra pieces of extra info, namely:

  • The name of the variable we wish to substitute.
  • The type of substitution that may be:
    • block: the whole paragraph containing the variable is replaced by the corresponding HTML.
    • inline: only the variable itself is replaced by the ‘inline’ HTML content (block elements are removed from the code).

A simple example will better illustrate all this.

Let us start with a simple template that looks like this:

The following code:

                                
								require_once 'pathToPHPDocX/classes/CreateDocx.inc';

								$docx = new CreateDocx();

								$docx->addTemplate('simpleTemplate.docx');

								$html='

								

A normal paragraph.

This is a simple paragraph with text in bold

Now we include a list:

  • First item.
  • Second item with subitems:
    • First subitem.
    • Second subitem.
  • Third subitem.

And now a table:

Cell 1 1 Cell 1 2 Cell 1 3
Cell 2 1 Cell 2 2 Cell 2 3

And that is it.

'; $docx->replaceTemplateVariableByHTML('HTMLBLOCK', 'block', $html); $docx->replaceTemplateVariableByHTML('HTMLINLINE', 'inline', $html, array('filter' => '.example')); $docx->createDocx('simpleTemplateReplaced');

Fields (download the corresponding Word document):