mlreportgen.dom.CustomElement Class

Namespace: mlreportgen.dom

Custom element of document

expand all in page

Description

Use an object of the mlreportgen.dom.CustomElement class to extend the DOM API. You can create a custom HTML or Microsoft® Word element that provides functionality not yet included in the DOM API. MATLAB® Report Generator™ does not check the validity of your custom element.

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

This class is only compatible with these MATLAB Report Generator output types:

  • "docx"

  • "html"

  • "html-file"

  • "html-multipage" (since R2024a)

Construction

customElementObj = CustomElement creates an empty element.

customElementObj = CustomElement(name) creates a custom element having the specified name.

Input Arguments

expand all

Name of an element supported by the type of document to which this custom element is appended. For example, specify "div" for a custom HTML div element or "w:p" for a custom Word paragraph element.

Output Arguments

expand all

Custom element, represented by an mlreportgen.dom.CustomElement object.

Properties

expand all

Custom element name, specified as a character vector or string scalar.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: char

The class ignores this property.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

The class ignores this property.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Custom attributes of the document element, specified as an array of mlreportgen.dom.CustomAttribute objects. The custom attributes must be supported by the output format of the document element to which this object is appended.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

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

Object identifier, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: char | string

Methods

Method

Purpose

append

appendedContent = append(classObj,contentToAppend) appends a valid DOM object, contentToAppend, to the mlreportgen.dom.CustomElement object.

Input Arguments

  • classObj — Class object to append content to, specified as an mlreportgen.dom.CustomElement object.

  • contentToAppend — Content to append, specified as a valid DOM object.

Return Values

  • appendedContent — Appended content, returned as a DOM object.

To see a list of the DOM class objects you can use as the classObj argument, see the More About section.

For more information, see the equivalent append method from the mlreportgen.dom.Document class.

clone

copiedObj = clone(soureceObj) returns a copy of the mlreportgen.dom.CustomElement 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.CustomElement object

Return Values

  • copiedObj— Object copy, returned as an mlreportgen.dom.CustomElement object

For more information, see the equivalent method for the mlreportgen.dom.Paragraph class, clone.

Examples

collapse all

Open Live Script

This example shows how to add a custom element that provides a check box in an HTML report.

Create and a custom element and append text to it. 

import mlreportgen.dom.*;
d = Document('test');

input1 = CustomElement('input');
input1.CustomAttributes = { 
         CustomAttribute('type','checkbox'), ...
         CustomAttribute('name','vehicle'), ...
         CustomAttribute('value','Bike'), ...
         };
append(input1, Text('I have a bike'));

Append the custom element to an ordered list and display the report. 

ol = OrderedList({input1});
append(d,ol);

close(d);
rptview(d.OutputPath);
Open Live Script

This example uses mlreportgen.dom.CustomElement and mlreportgen.dom.CustomAttribute objects to generate Open Office XML (OOXML) markup that displays a check box control in a Word document. For more information, see the OOXML documentation on the Office Open XML website.

Import the DOM API namespace.

import mlreportgen.dom.*;

Use objects of the mlreportgen.dom.CustomElement class to create Structured Document Tag (SDT) block-level containers for the check box control and an SDT properties element.

cbBlock = CustomElement("w:sdt");
cbBlockProps = CustomElement("w:stdPr");

The initState and initStateChar variables set the initial state of the check box. In this example we set the initial state of the check box to "unchecked" by setting initState="0" and initStateChar="☐". If you want the initial state of the check box to be "checked", set initState="1" and initStateChar="☒".

initState = "0";
initStateChar = "☐";

Create a check box control element and a check box state element, then append the check box state element to the check box control element.

cbControl = CustomElement("w14:checkbox"); 
cbState = CustomElement("w14:checked");
cbState.CustomAttributes = {CustomAttribute("w14:val",initState)};
append(cbControl,cbState);

Specify the font family and character to render a checked check box.

cbCheckedState = CustomElement("w14:checkedState");
cbCheckedState.CustomAttributes = { ...
            CustomAttribute("w14:val","2612"),... 
            CustomAttribute("w14:font","MS Gothic")};
append(cbControl,cbCheckedState);

Specify the font family and character to render an unchecked check box.

cbUncheckedState = CustomElement("w14:uncheckedState");
cbUncheckedState.CustomAttributes = { ...
            CustomAttribute("w14:val","2610"),...
            CustomAttribute("w14:font","MS Gothic")};
append(cbControl,cbUncheckedState);

Append the check box control to the SDT properties element.

append(cbBlockProps,cbControl);

Append the check box control property to the SDT element.

append(cbBlock,cbBlockProps);

Append an element to indicate the end of the properties section of the SDT element.

append(cbBlock,CustomElement("w:stdEndPr"));

Create a block-level container to specify the initial state and character of the check box, then append the check box element to the container.

cbBlockContent = CustomElement("w:stdContent");
textRange = CustomElement("w:r"); % text-block element
append(textRange,Text(initStateChar));
append(cbBlockContent,textRange);
append(cbBlock,cbBlockContent);

Create an mlreportgen.dom.Document object, then append a title to the document object.

wordDoc = Document("worddoc-w-checkbox","docx");
docTitle = Text(...
  "Using CustomElement objects to create a check box" + ...
  "in a Microsoft® Word Document",...
  "Title");
docTitle.FontSize = "12pt";
append(wordDoc,docTitle);

Create an mlreportgen.dom.Paragraph object, then append the check box element to the paragraph object.

para = Paragraph();
append(para,cbBlock);

Append text to the paragraph object, then add the paragraph object to the document object.

checkBoxStr = Text(" This is my check box");
checkBoxStr.WhiteSpace = "pre"; % Preserve the white spaces
append(para,checkBoxStr);
append(wordDoc,para);

Close the document object to generate the report, then open the report.

close(wordDoc);
rptview(wordDoc);

This example shows how to add a custom element that provides a check box in an HTML report.

Create and a custom element and append text to it.

import mlreportgen.dom.*;
d = Document("test");

input1 = CustomElement("input");
input1.CustomAttributes = { 
         CustomAttribute("type", "checkbox"), ...
         CustomAttribute("name", "vehicle"), ...
         CustomAttribute("value", "Bike"), ...
         };
append(input1, Text("I have a bike"));

Append the custom element to an ordered list and display the report.

ol = OrderedList({input1});
append(d,ol);

close(d);
rptview("test","html");

More About

expand all

Version History

Introduced in R2014b

See Also

|