Create and Format Text

Create Text

You can create text by appending a character vector to a document, paragraph, table entry, or list item. The DOM append function converts the character vector to a Text object, appends it, and returns the Text object. Use the Text object to format the text. You can also create a text object directly and append it to a document. This example:

Creates the Text object t1 by appending 'Hello' the document
Uses a Text constructor to create a Text object and append the text 'World' to the document

import mlreportgen.dom.*
d = Document('mydoc','html');

t1 = append(d,'Hello'); 

append(d,Text('World'));

close(d);
rptview(d.OutputPath);

Create Special Characters

You can define special characters, such as the British pound symbol, to include in a report by creating an mlreportgen.dom.CharEntity object. Specify a name of a character entity listed at https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references. For example:

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

p = Paragraph(CharEntity('pound'));
append(d,p);
append(p,'3');

close(d);
rptview(d.OutputPath);

Append HTML or XML Markup

To append HTML markup to an HTML document or Microsoft^® Word XML markup to a Word document, use an mlreportgen.dom.RawText object. This technique is useful for creating HTML or Word elements that the DOM API does not support directly. This example shows how to create a RawText object to append HTML markup.

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

append(d,RawText('<em>Emphasized Text</em>'));

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

Format Text

You can format text programmatically, using either DOM format objects or Text object format properties. You can also use template styles. For information about these formatting techniques and format inheritance, see Report Formatting Approaches.

Format Text Programmatically

You can use format objects to format Text objects or format properties to specify commonly used text formats. This example uses:

A FontFamily format object to specify the primary and backup font
The Bold format property to specify text weight

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

t = append(d,'Bold Arial text');

fontFamily = FontFamily('Arial');
fontFamily.BackupFamilyNames = {'Helvetica'};
t.Style = {fontFamily};

t.Bold = true;         

close(d);
rptview(d.OutputPath);

Use these format objects and format properties to format text.

Formatting	Format Object	Format Property
Font	`FontFamily`	`FontFamilyName`
Backup font (HTML only)	`FontFamily`	n/a
Complex script font (for example, Arabic)	`FontFamily`	n/a
East Asian font	`FontFamily`	n/a
Font size	`FontSize`	`FontSize`
Foreground color	`Color`	`Color`
Background color	`BackgroundColor`	`BackgroundColor`
Bold	`Bold`	`Bold`
Italic	`Italic`	`Italic`
Subscript or superscript	`VerticalAlign`	n/a
Strike through	`Strike`	`Strike`
Underline type (single, double, etc.)	`Underline`	`Underline`
Underline color	`Underline`	n/a
Preserve white space	`WhiteSpace`	`WhiteSpace`
Display as specified	`Display`	n/a

Format Text Using Microsoft Word Style Sheets

You can format a paragraph using a style defined in the Word template used to generate the report.

To define a text style in a Word template, start by using these steps:

Open the Word template used with the report.
Open the Styles pane.
Click the Manage Styles button .
Click New Style.
In the Create New Style from Formatting dialog box, set Style type to Character or Linked (paragraph and character).

For more information about working with Word styles, see Modify Styles in a Microsoft Word Template.

Format Text for HTML and PDF Using Style Sheets

You can format text using a style defined in the template used to generate the report. Apply a template style to a Text object either as the second argument in a Text object constructor or by setting the StyleName property to a template style.

To define the style, use cascading style sheet (CSS) syntax. Use a selector on the span element to specify the style name. This CSS defines a style named Pass.

span.Pass {
  font-family: "Times New Roman", Times, serif;
  color: green;
}

You can use any CSS properties and selectors in HTML templates. For PDF templates, you can use a subset of CSS properties and selectors. See Modify Styles in PDF Templates.

Apply a Style to a Text Object

Apply a template style to a Text object either as the second argument in a Text object constructor or by setting the StyleName property to a template style. Suppose you have defined styles named Body, Pass, and Fail in the template for your report. You can then apply the styles.

import mlreportgen.dom.*;
passed = rand(1) >= 0.5;
rpt = Document('MyReport','html','MyTemplate');

t1 = Text('Test status: ');
t1.StyleName = 'Body';
t1.WhiteSpace = 'preserve';

if passed
  status = 'Passed';
  statusStyle = 'Pass';
else
  status = 'Failed';
  statusStyle = 'Fail';
end

t2 = Text(status,statusStyle);
statusPara = Paragraph(t1);
append(statusPara,t2);
append(rpt, statusPara);

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

Override Template Formats

You can use programmatic formats to override the formats defined in a template-based style. Suppose that you define a style named AlertLevel in your template that sets the color to green. You can override the style in your report program to set a color based on the current alert level:

t = Text('Danger!','AlertLevel');
t.Color = 'red';

Documentation