mlreportgen.dom.Container class

Package: mlreportgen.dom

Container of document objects

Description

Creates a container element. Use the mlreportgen.dom.Container.append method to append document elements to the container. Use an mlreportgen.dom.Container object in a report to apply formats to all of the children of the container.

In HTML output, a Container object generates an HTML element of the type specified by its HTMLTag property and containing HTML elements corresponding to its DOM contents. For example, a Container object with the HTMLTag property div and that contains the text Hello World generates this markup:

<div><p><span>Hello World</span></p></div>

The generated HTML container element has the class and style properties specified by the Container object StyleName and Style properties, respectively. The rules of HTML CSS format inheritance assure that the generated children of the Container object inherit the formats specified by the Container object Style and StyleName properties. For example, if the Container object specifies red as its text color and none of its text children specify a color, the text children are colored red.

For Microsoft^® Word and PDF report output, a Container object simulates container format inheritance, applying the formats specified by the Container object Style attribute to each child, unless overridden by the child, and then appending the child to the output. Word and PDF output ignore the HTMLTag and StyleName properties of the Container object.

Tip

You can use mlreportgen.dom.Container or mlreportgen.dom.Group objects to produce collections of document elements.

• Use a container object to apply format inheritance to a set of objects and to create HTML container elements not otherwise supported by the DOM, such as div, section, and article.

• Use a group object to append the same content in multiple places in a document without cloning the group.

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

Class Attributes

HandleCompatible	true
ConstructOnLoad	true

For information on class attributes, see Class Attributes.

Creation

Description

containerObj = Container() creates a container with an HTML tag name div.

containerObj = Container(HTMLtag) creates a container with the specified HTML tag name (for example, div, section, or article).

Input Arguments

HTMLtag — HTML container tag name

character vector

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

Note

Word output ignores the HTML container tag.

Output Arguments

containerObj — Container of document objects

mlreportgen.dom.Container object

Container of document objects, returned as an mlreportgen.dom.Container object.

Properties

OutputPath — Path and name of output file or folder for this document

string scalar | character vector

Path and name of the output file or folder for this document, specified as a string scalar or character vector. You can specify an absolute path or a path relative to the current folder. You can set this property only before opening the document.

The default value is the path of a file or folder named untitled in the current folder. If OutputPath specifies a file and you do not specify the file extension, the DOM API adds an extension based on the Type property.

Whether OutputPath specifies the path of a file or folder depends on the value of the PackageType property, as shown in the table.

PackageType	OutputPath Value
"zipped" or "single-file"	Path and name of ZIP file or single file
"unzipped"	Folder for the unzipped files
"both"	Path and name of ZIP file and folder for the unzipped files

Note

Generating a PDF report on a cloud drive, such as MATLAB^® Drive™, can result in an error that is caused by file contention between the report generation software and the cloud drive synchronization software. To avoid this error, generate reports on a local drive that does not synchronize with the cloud. Consider writing a script that generates a report on a local drive and then copies the report to the cloud drive.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

PackageType — Packaging for generated files

"zipped" | "unzipped" | "both" | "single-file"

Packaging used for the generated files, specified as one of the values in the table. You can specify PackageType as a string scalar or character vector.

Value	Supported Report Types	Description
"zipped"	"docx"or "html"	Generates the report as a ZIP file at the location specified by the OutputPath property. The ZIP file has an extension that matches the document type (.docx for Word output or .htmx for HTML output.) For example, if the document Type is docx and OutputPath is s:\docs\MyDoc, the output is packaged in a ZIP file named s:\docs\MyDoc.docx.
"unzipped"	"docx" or "html"	Generates the report as separate files in a folder that has the file name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc, the output folder is s:\docs\MyDoc.
"both"	"docx" or "html"	Generates zipped and unzipped outputs.
"single-file"	"pdf" or "html-file"	Generates the report as a single file.

To generate an HTML report that you can open without unzipping, set Type to "html" and PackageType to "unzipped" or "both". In the folder that contains the generated files, open the root.html file.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

ForceOverwrite — Whether to overwrite existing output file

true (default) | false

Whether to overwrite an existing output file, specified as true or false. Set this property to true to overwrite an existing output file with the same name. If this property is false and a writable file with the same name exists, closing this document causes an error. If the existing file is read-only, closing this document causes an error regardless of this property setting.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

StreamOutput — Option to stream output to disk

false (default) | true

Option to stream the output to disk, specified as true or false. By default, document elements are stored in memory until the document is closed. Set this property to true to write the document elements to disk as the elements are appended to the document.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

TitleBarText — Text for HTML browser title bar

string scalar | character vector

Text for the HTML browser title bar, specified as a string scalar or character vector. For HTML documents, this property specifies the text that appears in the title bar of the browser used to display this document. Word and PDF documents ignore this property.

Set this property before opening the document.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

HTMLHeadExt — Custom content for HTML header

string scalar | character vector

Custom content for the HTML header, specified as a string scalar or character vector. The value of this property is appended to the <head> element of this document after the content specified by the head section of the document template. Set this property only before opening the document.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

TemplatePath — Path of template to use

string scalar | character vector

Full path of the template to use, specified as a string scalar or character vector.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Type — Type of output

"html" (default) | "docx" | "pdf" | "html-file"

Type of output, specified as one of these string scalars or character vectors:

• "html" — HTML output packaged as a zipped or unzipped folder that contains the HTML document text, image, style sheet, and JavaScript^® files

• "docx" — Word output

• "pdf" — PDF output

• "html-file" — A single HTML file that contains the text, style sheets, JavaScript, and images for the report

If you specify a template using the TemplatePath property, the template must be consistent with the Type argument. You must specify a template with a Word template extension (.dotx) for Word output, an HTML template package extension (.htmtx) for HTML output, a PDF template package extension (.pdftx) for PDF output, and a single-file HTML template extension (.htmt) for html-file output.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

CurrentHoleId — ID of current hole in document

character vector

ID of the current hole in the document, specified as a character vector.

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

CurrentHoleType — Type of current hole

'Inline' | 'Block'

Type of the current template hole, specified as 'Inline' or 'Block'.

• An inline hole is for document elements that a paragraph element can contain: Text, Image, LinkTarget, ExternalLink, InternalLink, CharEntity, or AutoNumber.

• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList, DocumentPart, or Group element.

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

CurrentPageLayout — Current page layout of this document

mlreportgen.dom.DOCXPageLayout object | mlreportgen.dom.PDFPageLayout object | []

Current page layout of this document, specified as an mlreportgen.dom.DOCXPageLayout object, mlreportgen.dom.PDFPageLayout object, or []. This property applies to Word and PDF documents. For Word documents, the value is a DOCXPageLayout object that specifies the current page layout. For PDF documents, the value is a PDFPageLayout object if the document currently specifies a page layout. For HTML documents, the value is always [].

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

OpenStatus — Open status of document

'unopened' (default) | 'open' | 'closed'

Open status of this document, specified as 'unopened', 'open', or 'closed'.

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

Parent — Parent of this DOM API object

DOM API object

Parent of this DOM API object, specified as a DOM API object.

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

Children — Children of this DOM API object

array of DOM API objects

Children of this DOM API object, specified as an array of DOM API objects.

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

Tag — Tag for this DOM API object

character vector | string scalar

Tag for this DOM API object, specified as a character vector or string scalar.

The DOM 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. Specifying your own tag value can help you to identify where an issue occurred during document generation.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Id — ID for this DOM API object

character vector | string scalar

ID for this DOM API object, specified as a character vector or string scalar. The DOM generates a session-unique ID when it creates the document element. You can specify your own ID.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Methods

Public Methods

append	Append DOM object to container
clone	Copy container object

Examples

Create Container for Word Report Formatting

Create a container object. Word output ignores the HTML container element tag (in this example, the div tag).

import mlreportgen.dom.*;
rpt = Document('MyReport','docx');

c = Container();

Color all of the container text red.

c.Style = {Color('red')};

Append content to the container and append the container to the report.

append(c,Paragraph('Hello'));
append(c,Table(magic(5)));
append(rpt,c);

Close and generate the report.

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

Version History

Introduced in R2015a