mlreportgen.dom.DocumentPart Class

Namespace: mlreportgen.dom

Create a document part object

Description

Define a document part, a repeatable part of a report. A document part typically has holes that you fill during report generation. You can append a part to a document or to a document part of the same output type.

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

Creation

Description

documentPartObj = DocumentPart creates an HTML document part using the default HTML template.

documentPart = DocumentPart(type) creates a document part of the specified type (for example, Microsoft^® Word) based on the default template for that part.

documentPartObj = DocumentPart(type,templatePath) creates a document part based on the specified template.

documentPartObj = DocumentPart(type,templatePath,docPartTemplateName) creates a document part based on the specified document part template in the specified template.

documentPartObj = DocumentPart(templateSrc,docPartTemplateName) creates a document part based on the specified document part template stored in the template used by the specified source. The source can be a document or a document part.

Input Arguments

type — Type of output

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

Type of output, specified as one of these values:

• "html" — HTML output

• "pdf" — PDF based on a PDF template

• "docx" — Word output

• "html-file" — HTML output, using a single file that contains the CSS, JavaScript^®, and images for the report

• "html-multipage" — HTML output containing the HTML document text divided into pages, image, style sheet, and JavaScript files (since R2024a)

If you specify a template using the templatePath argument, the value for type must match the template type.

templatePath — Path of this part’s template

[] (default) | character vector | string scalar

Full path of this part’s template file or folder, specified as a character vector or string scalar. If you omit a file extension, the template type is based on the document type, for example, .docx for Word.

Data Types: char

docPartTemplateName — Document part template name

character vector | string scalar

Document part template name, specified as a character vector or string scalar. Specify where the part is stored using the templatePath or templateSrc argument.

templateSrc — Document or document part that holds the document part template

mlreportgen.dom.Document object | mlreportgen.dom.DocumentPart object

Document or document part object whose template contains the template for this document part, specified as an mlreportgen.dom.Document object for a document or an mlreportgen.dom.DocumentPart object for a document part.

Properties

CurrentHoleId — ID of current hole in document

'' (default) | character vector | string scalar

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

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

CurrentHoleType — Type of current hole

'' (default) | "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:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

CurrentPageLayout — Current page layout of this document

[] (default) | 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:

SetAccess	private
Transient	true
NonCopyable	true

OpenStatus — Open status of document element

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

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

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

TemplateName — Name of this part’s template

'' (default) | character vector | string scalar

The name of this part's template if the template is stored in the document part template library of the template specified by this part's TemplatePath property, specified as a string scalar or a character vector. If this property is [], the template specified by the TemplatePath property is used as this part's template.

Attributes:

NonCopyable

true

Data Types: char

TemplatePath — Path of the template

character vector | string scalar

Path of this part's template or of a template whose template library contains this part's template, specified as a character vector or string scalar.

Attributes:

NonCopyable

true

Data Types: char

Type — Output file type

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

Output file type, specified as one of these values:

Value	File Type
"docx"	Microsoft Word
"html"	HTML output as a zipped or unzipped folder containing the HTML document text, image, style sheet, and JavaScript files
"html-file"	HTML output consisting of a single file that contains the text, style sheets, JavaScript, and images for the report
"html-multipage" (since R2024a)	HTML output as a zipped or unzipped folder containing the HTML document text divided into multiple pages, image, style sheet, and JavaScript files
"pdf"	PDF

If you specify a template using the TemplatePath property, the template must be consistent with the Type property.

Attributes:

NonCopyable

true

Data Types: char | string

Parent — Parent of mlreportgen.dom.DocumentPart object

document element object

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

Attributes:

SetAccess	private
NonCopyable	true

Children — Children of mlreportgen.dom.DocumentPart object

array of document element objects

Children of mlreportgen.dom.DocumentPart object, specified as an array of document element objects. This property contains the document element objects appended using the append method.

Attributes:

SetAccess	private
NonCopyable	true

Tag — Tag for mlreportgen.dom.DocumentPart object

character vector | string scalar

Tag for the mlreportgen.dom.DocumentPart object, 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. Specify your own tag value to help you identify where to look when an issue occurs during document generation.

Attributes:

NonCopyable

true

Data Types: char | string

Id — Object identifier for mlreportgen.dom.DocumentPart object

character vector | string scalar

Object identifier for the mlreportgen.dom.DocumentPart object, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object. You can specify your own value for Id.

Attributes:

NonCopyable

true

Data Types: char | string

Methods

Public Methods

Use DocumentPart methods like you use the corresponding Document methods.

Method	Purpose
addHTML Use DocumentPart.addHTML in a similar way to how you use Document.addHTML.	Append HTML text to document part
addHTMLFile Use DocumentPart.addHTMLFile in a similar way to how you use Document.addHTMLFile.	Append HTML file contents to document part
append	Append document element to the document part.
close	Close this document part. You cannot close a document part if it has not been opened or was previously closed.
mlreportgen.dom.Document.createTemplate	Create document part template.
fill	Fill document part hole.
mlreportgen.dom.Document.getCoreProperties	Get core properties of document part.
mlreportgen.dom.Document.getOPCMainPart	Get full path of main part of output document.
moveToNextHole	Move to next template hole.
open	Open this document part. You cannot open a document part if it was previously opened or closed. You also cannot open a document part if its library source is closed.
mlreportgen.dom.Document.setCoreProperties	Set core properties of document part.

Examples

Document Part from Blank Document Part Template

This example creates a function createMagicSquareReport that defines a document part based on a blank document part template. The new document part has a heading whose text depends on the input. Each document part generated contains a magic square table whose appearance is also based on the input. The example also creates a local function createSquareSection that appends the document part to the report iteratively based on the input.

Create the function.

function createMagicSquareReport(square_sizes, report_type)
%createMagicSquareReport Report on magic squares
%    magic_square_report(square_sizes, report_type) 
%    creates a report of the specified output type 
%    (docx, pdf, or html) on the specified magic
%    squares. For example, to create a PDF report on 
%    squares of size 5, 10, and 15, enter the following 
%    line at the MATLAB command line:
%
%      createMagicSquareReport([5,10,15],"pdf");

import mlreportgen.dom.*;
rpt = Document("MagicSquareReport",report_type);
open(rpt);
for i = 1:length(square_sizes)
    sz = square_sizes(i);
    section = createSquareSection(rpt,sz);
    append(rpt,section);
end
close(rpt);
rptview(rpt.OutputPath);
 
function section = createSquareSection(rpt,square_size)
import mlreportgen.dom.*;
% Create document part to hold section
section = DocumentPart(rpt.Type);
% Create magic square heading
h1 = Heading1(sprintf("magic(%i)",square_size));
% Put each square on a separate page.
h1.Style = {PageBreakBefore(true)};
append(section,h1);
% Create table to hold square
table = append(section, Table(magic(square_size)));
% Format table
table.Border = "solid";
table.ColSep = "solid";
table.RowSep = "solid";

Call the function to generate the report. Change the input arguments to change the contents or output format. This example creates a Word document that contains three squares.

 createMagicSquareReport([5,8,12],"docx");

Version History

Introduced in R2014a