Main Content

mlreportgen.dom.HTML class

Package: mlreportgen.dom
Superclasses:

Use HTML markup to create DOM document

Description

Converts 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.

Construction

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.

An HTML object supports these HTML elements and attributes. 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.

HTML ElementAttributes
aclass, style, href, name
bclass, style
bodyclass, style
brn/a
codeclass, style
delclass, style
divclass, style
fontclass, style, color, face, size
h1, h2, h3, h4, h5, h6class, style, align
hrclass, style, align
iclass, style
insclass, style
imgclass, style, src, height, width
liclass, style
olclass, style
pclass, style, align
preclass, style
sclass, style
spanclass, style
strikeclass, style
subclass, style
supclass, style
tableclass, style, align, bgcolor, border, cellspacing, cellpadding, frame, rules, width
tbodyclass, style, align, valign
tfootclass, style, align, valign
theadclass, style, align, valign
tdclass, style, bgcolor, height, width, colspan, rowspan, valign, nowrap
trclass, style, bgcolor, valign
ttclass, style
uclass, style
ulclass, style

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

Input Arguments

expand all

HTML text, specified as a character vector

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

Properties

expand all

Note

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 CharacterDescriptionEquivalent Character
>Greater than&gt;
<Less than&lt;
&Ampersand&amp;
"Double quotation mark&quot;
'Single quotation mark&apos;
%Percent&#37;

A session-unique ID is generated as part of HTML object creation. You can specify an ID to replace the generated ID.

Tag name of HTML container element, specified as a character vector, such as 'div', 'section', or 'article' corresponding to this HTML object. This property applies only to HTML output.

This read-only property lists child elements that the HTML object contains.

This read-only property lists the parent of this HTML object.

Formatting to apply to this HTML object, specified as a cell array of DOM format objects. The children of this HTML object inherit any of these formats that they do not override.

Style name of this HTML object, specified as a character vector. Use a name of a style specified in the style sheet of the document to which this HTML object is appended. The specified style defines the appearance of the HTML object in the output document where not overridden by the formats specified by this StyleName property of the HTML object.

Tag for HTML object, specified as a character vector.

A session-unique ID is generated as part of HTML object creation. The generated tag has the form CLASS:ID, where CLASS is the class of the element and ID is the value of the Id property of the object. You can specify a tag to replace the generated tag.

Specify your own tag value, for example, to make it easier to identify where an issue occurred during document generation.

Whether to convert white space between elements, specified as true or false. If KeepInterElementWhiteSpace is true, the DOM API converts white space between elements in the input HTML markup to mlreportgen.dom.Text objects. If 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.

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.

Methods

appendAppend HTML string to HTML object
cloneCopy HTML object

Examples

collapse all

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:

Tips

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

Introduced in R2015a