Main Content

mlreportgen.dom.CustomElement class

Package: mlreportgen.dom

Custom element of document


Use a custom element 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.


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.


expand all

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

ID for this document element, 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.

Element name, specified as a character vector.

This property is ignored.

This property is ignored.

Tag for this document element, 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.





Append a custom element to the document element


Use CustomElement.clone similar to how you use Paragraph.clone.

Copy custom element.


collapse all

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});


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

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)};

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

cbCheckedState = CustomElement('w14:checkedState');
cbCheckedState.CustomAttributes = { ...
            CustomAttribute('w14:font','MS Gothic')};

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

cbUncheckedState = CustomElement('w14:uncheckedState');
cbUncheckedState.CustomAttributes = { ...
            CustomAttribute('w14:font','MS Gothic')};

Append the check box control to the SDT properties element.


Append the check box control property to the SDT element.


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


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

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',...
docTitle.FontSize = '12pt';

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

para = Paragraph();

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

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