mlreportgen.dom.CustomElement Class

Namespace: mlreportgen.dom

Custom element of document

Description

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.

Construction

customElementObj = CustomElement creates an empty element.

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

Input Arguments

name — Custom element name

character vector

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

customElementObj — Custom element

mlreportgen.dom.CustomElement object

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

Properties

Name — Element name

character vector

Element name, specified as a character vector or string scalar.

Data Types: char

StyleName — This property is ignored

not applicable

The class ignores this property.

Attributes:

NonCopyable

true

Style — Format specification

{} (default)

The class ignores this property.

CustomAttributes — Custom attributes of document element

[] (default) | array of mlreportgen.dom.CustomAttribute objects

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 of the document element to which this object is appended.

Attributes:

NonCopyable

true

Tag — Tag for mlreportgen.dom.CustomElement object

character vector | string scalar

Tag for the mlreportgen.dom.CustomElement 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.CustomElement object

character vector | string scalar

Object identifier for the mlreportgen.dom.CustomElement 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

Method	Purpose
append	Append a custom element to the document element
clone Use CustomElement.clone similar to how you use Paragraph.clone.	Copy custom element.

Examples

Create a Check Box Custom Element

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

Create a Check Box in a Microsoft® Word Document

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