Create and Format Paragraphs

Create Paragraphs

You can create a paragraph by using an mlreportgen.dom.Paragraph constructor with a character vector. For example:

p = Paragraph('Text for a paragraph');

You can also specify these DOM objects in a Paragraph object constructor.

• mlreportgen.dom.Text

• mlreportgen.dom.ExternalLink

• mlreportgen.dom.InternalLink

• mlreportgen.dom.LinkTarget

• mlreportgen.dom.Image

Create Headings

A heading is a type of paragraph. You can use mlreportgen.dom.Heading1, Heading2 , and so on, to create headings. Alternatively, you can use an mlreportgen.dom.Heading object if you want to use programmatically derived values for the heading level.

This example creates a first-level heading with the text Chapter 1: System Overview. If you create a table of contents, this heading appears at the top level.

h1 = Heading1('Chapter 1: System Overview');

Format Paragraphs

You can format a paragraph using DOM format objects or format properties. You can also use template styles. For information about these formatting techniques and format inheritance, see Report Formatting Approaches.

Note

You can use the same format objects and properties for heading objects (Heading and Heading1, Heading2, and so on) as you do for Paragraph objects.

Format a Paragraph Programmatically

You can use DOM API format objects to format Paragraph objects or format properties to specify commonly used paragraph formats. This example uses:

• An OuterMargin format object to specify the margins for the paragraph

• The HAlign format property to center the paragraph

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

p = Paragraph('Indent a half inch and space after 12 points.');
p.Style = {OuterMargin('0.5in','0in','0in','12pt')};
append(d,p);

p = Paragraph('Centered paragraph');
p.HAlign = 'center';
append(d,p);

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

Use these objects and properties to format a paragraph.

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	Underline	Underline
Underline color	Underline	n/a
Create border around paragraph	Border	n/a
Preserve white space	WhiteSpace	WhiteSpace
Indent a paragraph	OuterMargin	OuterLeftMargin
Indent first line of paragraph	FirstLineIndent	FirstLineIndent
Hanging indent	FirstLineIndent	n/a
Space before and after paragraph	OuterMargin	n/a
Space to right of paragraph	OuterMargin	n/a
Space between paragraph and its bounding box	InnerMargin	n/a
Space between paragraph lines	LineSpacing	n/a
Align paragraph left, center, right	HAlign	HAlign
Start paragraph on next page	PageBreakBefore	n/a
Keep with next paragraph	KeepWithNext	n/a
Keep paragraph on same page	KeepLinesTogether	n/a
Eliminate widows and orphans	WidowOrphanControl	n/a
Table of contents level of paragraph	OutlineLevel	OutlineLevel
Display as specified	Display	n/a

Format Paragraphs for Microsoft Word Using Template Styles

You can format a paragraph using a style in a Word template. You can add styles to the template or modify existing ones.

To add a paragraph style:

1. Open the Word template used with the report.

2. Open the Styles pane.

3. Click the Manage Styles button .

4. Click New Style.

5. In the Create New Style from Formatting dialog box, set Style type to Character or Linked (paragraph and character).

6. Format the style as needed.

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

Format Paragraphs Using PDF or HTML Template Styles

You can format a paragraph using a style in an HTML or PDF style sheet in your template. You can add styles to the template or modify existing ones.

Define the style using a selector on a p element. This example defines a BodyPara paragraph style.

p.BodyPara {
  font-family: "Times New Roman", Times, serif;
  font-style: normal;
  font-size: 11pt;
  color: black;
  margin-left: 0.5in;
}

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.

For more information about using HTML styles with DOM objects, see Modify Styles in HTML Templates.

Apply Styles to Paragraph Objects

Apply a template style to a Paragraph object either as the second argument in a Paragraph object constructor or by setting the StyleName property on the paragraph to a template style.

Suppose that you have defined styles named BodyPara and MyTitle in a template. This example first specifies a style name in a Paragraph constructor. It then specifies the style in a Paragraph object StyleName format property. This example assumes both styles are defined in MyTemplate.

import mlreportgen.dom.*;
rpt = Document('MyReport','html','MyTemplate');

% Specify style name using an argument when you create the Paragraph
p = Paragraph('Format this paragraph using a body style.','BodyPara');
append(rpt,p);

p = Paragraph('This paragraph is formatted using a title style.');

% Specify  style name using a property on the paragraph
p.StyleName = 'MyTitle';
append(rpt,p);

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

Override Template Formats

You can use programmatic formats to override the paragraph formats defined in a template-based paragraph style. Suppose that you define a paragraph style named BodyPara in your Word template and set the KeepWithNext property to off. You can override the style in your report program to keep a particular paragraph on the same page with the next paragraph:

import mlreportgen.dom.*;
rpt = Document('MyReport','docx','MyTemplate');

p = Paragraph('Keep this body paragraph with next.','BodyPara');
p.Style = {'KeepWithNext'};
append(rpt,p);

p = Paragraph('Next paragraph.');
append(rpt, p);

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