mlreportgen.dom.HTML Class

Namespace: mlreportgen.dom
Superclasses: mlreportgen.dom.Container

Use HTML markup to create DOM document

Description

Use an object of the mlreportgen.dom.HTML class to convert a string of HTML markup to DOM objects and appends them to an HTML object that it also creates. You can append the HTML object to a DOM document of any type, including Word and PDF documents.

To see what DOM objects you can append an mlreportgen.dom.HTML object to, see Append mlreportgen.dom.HTML object to DOM class object.

The mlreportgen.dom.HTML class is a handle class.

Creation

Description

htmlObj = HTML creates an empty HTML object.

htmlObj = HTML(htmlText) converts HTML text to an HTML object containing DOM objects having the same content and format. Unsupported HTML elements and attributes are ignored. In addition, HTML objects accept HTML that contains custom CSS properties, which begin with a hyphen. Custom CSS properties are supported in HTML, Microsoft^® Word, and PDF output.

For a complete list of supported HTML elements and CSS formats, see the More About section.

Input Arguments

htmlText — HTML text

character vector

HTML text, specified as a character vector

Example: html = HTML("<p><b>Hello</b> <i style="color:green"> World</i></p>");

Properties

HTMLTag — HTML tag name of container

"div" (default) | character vector | string scalar

HTML tag name of container, specified as a character vector or string scalar. The name must be an HTML element, such as "div", "section", or "article".

Note

Microsoft Word output ignores the HTML tag name.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

KeepInterElementWhiteSpace — Whether to convert white space between elements

0 (false) (default) | 1 (true)

Whether to convert white space between elements, specified as true or false.

• 1 (true) — The DOM API converts white space between elements in the input HTML markup to mlreportgen.dom.Text objects.

• 0 (false) — The DOM API ignores white space between elements.

Setting the KeepInterElementWhiteSpace property to true does not preserve white space. To preserve white space, set the KeepInterElementWhiteSpace property to true and add an mlreportgen.dom.WhiteSpace format object to the Style property of the HTML object. The WhiteSpace property of the WhiteSpace object must be set to "preserve". For example:

import mlreportgen.dom.*
d2 = mlreportgen.dom.Document("ex2","pdf");
h2 = HTML();
h2.Style = {WhiteSpace("preserve")};
h2.KeepInterElementWhiteSpace = true;
append(h2,"<p>    <span>Hello</span>    <span>World!</span></p>");
append(d2,h2);
close(d2);
rptview(d2)

If the input HTML preserves white space using a style attribute, you do not need to use the KeepInterElementWhiteSpace property and WhiteSpace object. For example:

import mlreportgen.dom.*
d1 = mlreportgen.dom.Document("ex1","pdf");
h1 = HTML();
append(h1,"<p style="white-space:pre"> <span>Hello</span>    <span>World!</span></p>");
append(d1,h1);
close(d1);
rptview(d1);

If the input HTML uses a CSS style to preserve white space, the DOM API does not preserve the white space unless you use the KeepInterElementWhiteSpace and the WhiteSpace object. For example:

import mlreportgen.dom.*
d3 = mlreportgen.dom.Document("ex3","pdf");
h3 = HTML();
h3.Style = {WhiteSpace("preserve")};
h3.KeepInterElementWhiteSpace = true;
append(h3,[ ...
    "<style type="text/css">.myStyle { white-space: pre}</style>" ...
    "<p class="myStyle"> <span>Hello</span>    <span>World!</span></p>"]);
append(d3,h3);
close(d3);
rptview(d3);

Alternatively, if the input HTML uses a CSS style to preserve white space, you can prepare the HTML using mlreportgen.utils.html2dom.prepHTMLString or mlreportgen.utils.html2dom.prepHTMLFile. Then, create an HTML object from the prepared HTML. For example:

import mlreportgen.dom.*
d3 = mlreportgen.dom.Document("ex3","pdf");
h3 = HTML();
htmlStr = ["<style type="text/css">.myStyle { white-space: pre}</style>" ...
    "<p class="myStyle"> <span>Hello</span>    <span>World!</span></p>"];
preppedhtml = mlreportgen.utils.html2dom.prepHTMLString(htmlStr);
append(h3,preppedhtml);
append(d3,h3);
close(d3);
rptview(d3);

See Prepare HTML Before Conversion.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: logical

EMBaseFontSize — Font size of one em unit in points

12 (default) | integer

Font size of one em unit, in points, specified as an integer. If a style in the HTML text specifies font size in em units, the number of em units is multiplied by the value of the EMBaseFontSize property to determine the font size in points. For example, the following code results in a font size of 20 points.

h = HTML();
     h.EMBaseFontSize = 10;
     append(h, "<p style="font-size:2em">Hello</p>");
 

Set the EMBaseFontSize property in an empty mlreportgen.dom.HTML object. Then add the HTML to the object. For example:

import mlreportgen.dom.*; 
rpt = Document("MyReport","pdf");  
htmlobj = HTML();
htmlobj.EMBaseFontSize = 14;
append(htmlobj,"<p style="font-size:2em">Hello</p>");
append(rpt,htmlobj); 
close(rpt);
rptview("MyReport.pdf");

Setting the EMBaseFontSize property in an mlreportgen.dom.HTML object that already contains the HTML has no effect.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: double

StyleName — Name of stylesheet-defined style

[] (default) | character vector | string scalar

Name of stylesheet-defined style, specified as a character vector or string scalar. The style name is the name of a style specified in the style sheet of the document or document part to which this element is appended. The specified style defines the appearance of this element in the output document unless the formats specified by the Style property of this element override it. To learn more about using style sheets, see Use Style Sheet Styles.

Note

Microsoft Word reports ignore style names that are not defined in the document template. For more information on Microsoft Word templates, see Templates for DOM API Report Programs.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Style — Format specification

{} (default) | array of format objects

Formatting to apply to this document element object, specified as a cell array of DOM format objects. The formats specified by this property override corresponding formats specified by the StyleName property of this element. Formats that do not apply to this element are ignored.

Note

The children of this document element object inherit any of these formats that they do not override.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: cell

Parent — Parent of this object

document element object

Parent of this object, specified as a document element object. A document element must have only one parent.

Attributes:

GetAccess	public
SetAccess	private
NonCopyable	true

Children — Children of this HTMLFile object

cell array of mlreportgen.dom.Element objects

Children elements of this HTMLFile object, specified as an array of mlreportgen.dom.Element objects.

Attributes:

GetAccess	public
SetAccess	private

Data Types: cell

Tag — Tag

character vector | string scalar

Tag, specified as a character vector or string scalar. The DOM API generates a session-unique tag as part of the creation of this object. The generated tag has the form CLASS:ID, where CLASS is the object class and ID is the value of the Id property of the object. Use this value to help identify where an issue occurs during document generation.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Id — Identifier for HTML object

character vector | string scalar

A session-unique identifier is generated as part of HTML object creation. You can specify your own value for Id.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Methods

Public Methods

Method	Purpose
append	Append HTML string to HTML object
clone	copiedObj = clone(soureceObj) returns a copy of the mlreportgen.dom.HTML object specified by soureceObj. The copy includes the children of the source object, but not the parent. Note Do not append the same object to a document more than once. Use clone to create a copy when you want to reuse the same content elsewhere in a document. Input Arguments soureceObj — Object to clone, specified as an mlreportgen.dom.HTML object Return Values copiedObj— Object copy, returned as an mlreportgen.dom.HTML object For more information, see the equivalent method for the mlreportgen.dom.Paragraph class, clone. Example: Copy an HTML Object

Examples

Convert HTML Markup to a Word Report

Create an mlreportgen.dom.HTML object from HTML markup and add it to a Word report.

import mlreportgen.dom.*;
rpt = Document("MyReport", "docx");
html = HTML("<p><b>Hello</b> <i style="color:green"> World</i></p>");
append(html, "<p>This is <u>me</u> speaking</p>");
append(rpt, html);
close(rpt);
rptview(rpt.OutputPath);

The resulting Word report looks like this:

Copy an HTML Object

Create an HTML object from HTML text, to use for a Microsoft Word report.

import mlreportgen.dom.*;
rpt = Document("ClonedHTMLReport","docx");     
htmlObj1 = HTML("<p><b>Hello</b> <i style="color:green">World</i></p>");

Append the HTML object to the report.

append(rpt,htmlObj1);

Copy the HTML object and append the copy to the report.

htmlObj2 = clone(htmlObj1);
append(rpt,htmlObj2);

Generate the report.

close(rpt);
rptview(rpt.OutputPath);

More About

Append content to mlreportgen.dom.HTML object

You can append an mlreportgen.dom.CustomElement object to an mlreportgen.dom.HTML object.

append(classObj,customElementObj);

Append mlreportgen.dom.HTML object to DOM class object

You can append an mlreportgen.dom.HTML object to these DOM class objects:

• mlreportgen.dom.Container

• mlreportgen.dom.CustomElement

• mlreportgen.dom.Document

• mlreportgen.dom.DocumentPart

• mlreportgen.dom.DOCXPageFooter

• mlreportgen.dom.DOCXPageHeader

• mlreportgen.dom.Group

• mlreportgen.dom.HTML

• mlreportgen.dom.HTMLFile

• mlreportgen.dom.HTMLPage (since R2024a)

• mlreportgen.dom.PDFPageFooter

• mlreportgen.dom.PDFPageHeader

• mlreportgen.dom.TableEntry

• mlreportgen.dom.TableHeaderEntry

• mlreportgen.dom.Template

• mlreportgen.dom.TemplateDocumentPart (since R2023b)

Supported HTML elements

This table lists the HTML elements supported in an HTMLFile object.

HTML Element	Attributes
a	class, style, href, name
address	class, style
b	class, style
big	class, style
blockquote	class, style
body	class, style
br	n/a
center	class, style
cite	class, style
code	class, style
dd	class, style
del	class, style
dfn	class, style
div	class, style
dl	class, style
dt	class, style
em	class, style
font	class, style, color, face, size
h1, h2, h3, h4, h5, h6	class, style, align
hr	class, style, align
i	class, style
ins	class, style
img	class, style, src, height, width
kbd	class, style
li	class, style
mark	class, style
nobr	class, style
ol	class, style
p	class, style, align
pre	class, style
s	class, style
samp	class, style
small	class, style
span	class, style
strike	class, style
strong	class, style
sub	class, style
sup	class, style
table	class, style, align, bgcolor, border, cellspacing, cellpadding, frame, rules, width
tbody	class, style, align, valign
tfoot	class, style, align, valign
thead	class, style, align, valign
td	class, style, bgcolor, height, width, colspan, rowspan,align, valign, nowrap
th	class, style, bgcolor, height, width, colspan, rowspan,align, valign, nowrap
tr	class, style, align,bgcolor, valign
tt	class, style
u	class, style
ul	class, style
var	class, style

For more information about these elements, see https://developer.mozilla.org/en-US/docs/Web/HTML/Element.

Tips

• For HTML markup to display correctly in your report, you must include end tags for empty elements and enclose attribute values in quotation marks. If you want to show a reserved XML markup character as text, you must use its equivalent named or numeric XML character.

  Reserved Character	Description	Equivalent Character
  >	Greater than	>
  <	Less than	&lt;
  &	Ampersand	&amp;
  "	Double quotation mark	&quot;
  '	Single quotation mark	&apos;
  %	Percent	&#37;

• MATLAB^® Report Generator™ mlreportgen.dom.HTML or mlreportgen.dom.HTMLFile objects typically cannot accept the raw HTML output of third-party applications, such as Microsoft Word, that export native documents as HTML markup. In these cases, your Report API report generation program can use the mlreportgen.utils.html2dom.prepHTMLString and mlreportgen.utils.html2dom.prepHTMLFile functions to prepare the raw HTML for use with the mlreportgen.dom.HTML or mlreportgen.dom.HTMLFile objects. Typically, your program will have to further process the prepared HTML to remove valid but undesirable objects, such as line feeds that were in the raw content.

• Word and PDF documents require inline elements, such as text and links, to be contained in a paragraph. To meet this requirement, the HTML parser creates wrapper paragraphs to contain inline elements that are not already in a paragraph. If you create an mlreportgen.dom.HTML or mlreportgen.dom.HTMLFile object from HTML that contains inline elements that are not in paragraphs and add the object to an HTML document, the generated HTML can differ from the input HTML. To generate the inline elements without the added wrapper paragraphs, insert the HTML markup into an HTML document by using an mlreportgen.dom.RawText object.

• By default, the DOM API uses a base font size of 12 points to convert em units to actual font sizes. For example, a font size specified as 2em converts to 24 points. To specify a different base font size, add your content to a report by using an mlreportgen.dom.HTML object. Set the EMBaseFontSize property of the object to the base font size. For example, if you set the EMBaseFontSize property to 14, a font size of 2em converts to 28 points.

Version History

Introduced in R2015a