Create and Format Lists

You can use the DOM API to create and format unordered, ordered, and multilevel lists in a report generation program.

Lists are represented as mlreportgen.dom.UnorderedList or mlreportgen.dom.OrderedList objects. List items are represented as mlreportgen.dom.ListItem objects.

You can create a list from a MATLAB^® array that specifies the list items or create a list one item at a time. Creating a list from an array is the simplest approach. Creating a list one item at a time is useful when the items contain multiple elements, such as a paragraph and a table.

Format lists and list items by using template-defined styles or programmatically by using format objects.

Create Lists from MATLAB Arrays

You can create a list from a one-dimensional numeric array, string array, array of character vectors, cell array, or categorical array. Specify list items in a cell array when the items have different types.

Create Unordered Lists from Arrays

To create an unordered list from an array, append the array directly to a document or document part. The append method:

• Creates an mlreportgen.dom.UnorderedList object.

• Creates an mlreportgen.dom.ListItem object for each element of the array.

• Appends the ListItem objects to the UnorderedList object and the UnorderedList object to the document or document part.

For example, this code creates an unordered list from a string array:

import mlreportgen.dom.*
d = Document("fruit","html");

ul = append(d,["apples","oranges","bananas"]);

close(d);
rptview(d);

Here is the list in the generated report:

Note

To create a list by appending an array to a document or document part, the array must be 1-by-n. Appending an n-by-1 array to a document or document part creates a table, not a list.

Alternatively, create an unordered list by providing an array as an input to the mlreportegen.dom.UnorderedList constructor. For example:

import mlreportgen.dom.*
d = Document("fruit","html");

ul = UnorderedList(["apples","oranges","bananas"]);
ul = append(d,ul);

close(d);
rptview(d);

The constructor creates an mlreportgen.dom.ListItem object for each array element and appends the ListItem objects to the UnorderedList object.

Create Ordered Lists from Arrays

To create an ordered list from an array, provide the array as input to the mlreportegen.dom.OrderedList constructor. The constructor creates an mlreportgen.dom.ListItem object for each element of the array and appends the ListItem objects to the OrderedList object. For example, this code creates an ordered list from a string array.

import mlreportgen.dom.*
d = Document("weekdays","html");

ol = OrderedList(["Monday","Tuesday","Wednesday","Thursday","Friday"]);
append(d,ol);

close(d);
rptview(d);

Here is the list in the generated report:

Create Lists from Cell Arrays

Specify list items in a cell array when the items have different types. In a cell array, you can include character vectors, strings, numbers, and some DOM objects, such as an mlreportgen.dom.Text object. For a list of DOM objects that you can include, see mlreportgen.dom.ListItem.

For example, this code creates an ordered list from a cell array that contains character vectors and an mlreportgen.dom.ExternalLink object.

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

ol = UnorderedList({...
    'apples',...
    'oranges',...
    ExternalLink('https://en.wikipedia.org/wiki/Mango',...
    'mango')});
append(d,ol);

close(d);
rptview(d);

Here is the list in the generated report:

Create Lists from Single Items

Instead of specifying an entire list as an array, you can specify each list item as an mlreportgen.dom.ListItem object and append the ListItem objects to an mlreportgen.UnorderedList or mlreportgen.OrderedList object. This approach is useful when the list items contain multiple paragraphs, a mix of paragraphs and tables, or other combinations of document elements.

For example, this code creates a list in which the list items consist of a paragraph and a table.

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

ol = UnorderedList();
item1 = ListItem(Paragraph('magic(2)'));
append(item1,Table(magic(2)));
append(ol,item1);
item2 = ListItem(Paragraph('magic(3)'));
append(item2,Table(magic(3)));
append(ol,item2);
append(d,ol);

close(d);
rptview(d);

Here is the list in the generated report:

Create Multilevel Lists

A multilevel list is a list that contains nested lists. You can nest any combination of ordered and unordered lists up to nine levels of nesting.

You can use the following approaches to create multilevel lists. The generated list looks the same with each approach, but the DOM API representations differ.

• Create a multilevel list from cell arrays that model the list hierarchy. With this approach, the DOM API represents a sublist as a child of the list that contains it.

• Create a multilevel list one list at a time using mlreportgen.dom.UnorderedList, mlreportgen.dom.OrderedList, and mlreportgen.dom.ListItem objects. Append a sublist to a list or list item. If you append the sublist to a list, the DOM API represents the sublist as a child of the list. If you append the sublist to a list item, the DOM API represents the sublist as a child of the list item.

Create Multilevel Lists from Cell Arrays

To create a multilevel list from cell arrays, use one of these approaches:

• If the sublist is an unordered list, you can represent it as a 1-by-n cell array that is an element of a 1-by-n cell array that represents the list that is one level up. For example, this code represents a sublist as a cell array that is the third element of a cell array that represents the top-level list.

  import mlreportgen.dom.*;
  d = Document('nestedListReport','html');
  
  topList = OrderedList({...
      'Start MATLAB',...
      'Create a rank 3 or 4 magic square',...
          {'magic(3)',...  % sublist is third element
          'magic(4)'},...
      'Close MATLAB'});
  append(d,topList);
  
  close(d);
  rptview(d);

  Here is the list in the generated report:

  

• If the sublist is an ordered list, create an mlreportgen.dom.OrderedList object from a 1-by-n cell array that represents the sublist. Include the OrderedList object as an element of a cell array that represents the list that is one level up. For example, this code creates an OrderedList object from a cell array that represents the sublist and includes the object as the third element of the cell array that is used to create the top-level list.

  import mlreportgen.dom.*;
  d = Document('orderedListReport','html');
  
  topList = OrderedList({'Start MATLAB', ...
      'Create a rank 3 or 4 magic square',...
      OrderedList({...  % sublist is third element
          'magic(3)',...
          'magic(4)'}),...
      'Close MATLAB'});
  
  append(d,topList);
  
  close(d);
  rptview(d);

  Here is the list in the generated report:

  

In the two previous examples, the DOM API represents the sublist as the third child of the top-level list. To access the sublist, use the Children property of the top-level list.

topList.Children(3)

Create Multilevel Lists from Multiple Lists

When sublist items contain multiple paragraphs, a mix of paragraphs and tables, or other combinations of document elements, create mlreportgen.dom.ListItem objects and append them to an mlreportgen.dom.UnorderedList or an mlreportgen.dom.OrderedList object. Then, append the sublist to a list or to a list item.

This example appends a sublist to the top-level list as the third list item. The items in the sublist consist of text and a table.

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

subList = UnorderedList;
subListItem1 = ListItem('>> magic(3)');
table = append(subListItem1,Table(magic(3)));
table.Width = '1in';
append(subList,subListItem1);
subListItem2 = ListItem('>> magic(4)');
table = append(subListItem2,Table(magic(4)));
table.Width = '1in';
append(subList,subListItem2);

topList = OrderedList();
append(topList,ListItem('Start MATLAB'));
append(topList,ListItem('Create a rank 3 or 4 magic square'));
append(topList,subList); % sublist is item 3 of topList
append(topList,ListItem('Close MATLAB'));
    
append(d,topList);

close(d);
rptview(d);

Here is the list in the generated report:

The DOM API represents the sublist as the third child of the top-level list. To access the sublist, use the Children property of the top-level list.

topList.Children(3)

Instead of appending a sublist to a list, you can append the sublist to a list item. The following example appends a sublist to the second list item of the top-level list. The generated list looks the same as in the previous example.

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

topList = OrderedList({ ...
    'Start MATLAB', ...
    'Create a rank 3 or 4 magic square:', ...
    'Close MATLAB'});

subList = UnorderedList;
subListItem1 = ListItem('>> magic(3)');
table = append(subListItem1,Table(magic(3)));
table.Width = '1in';
append(subList,subListItem1);
subListItem2 = ListItem('>> magic(4)');
table = append(subListItem2,Table(magic(4)));
table.Width = '1in';
append(subList,subListItem2);

% Append the sublist to the second list item
topListItem2 = topList.Children(2);
append(topListItem2, subList);

append(d, topList);

close(d);
rptview(d);

The DOM API represents the sublist as the second child of the second item of the top-level list. To access the sublist, use this code:

topList.Children(2).Children(2)

Format Lists Using Template-Defined Styles

You can use list styles defined in a template to specify the indentation of each level of a list and the type of bullet or the number format used to render list items.

To use a template-defined list style to format a list, set the StyleName property of the list to the name of the style. For example, this code specifies that the list style name is MyListStyle.

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

list = append(d,{'first item',...
    OrderedList({'step 1','step 2'}),'second item'});
list.StyleName = 'MyListStyle';

close(d);
rptview(d);

For Microsoft^® Word documents, the list style that you specify must be defined in the template that is assigned to the document.

Note

A list style determines how list items are rendered regardless of the list type. If you do not specify a list style, the DOM API uses a default list style that renders the list according to type. For example, the default list style for unordered lists uses bullets to render list items. If you specify a list style for an mlreportegen.dom.UnorderedList object that numbers items, the items are numbered, even though the object type is unordered.

Create Word List Styles

For information about creating a Word template, see Create Microsoft Word Templates.

To define a list style in a Word template:

1. Open the Word template file by using one of these methods:

   • In MATLAB, in the Current Folder pane, right-click the template file and click Open Outside MATLAB.

   • Outside of MATLAB, right-click the file and click Open.

     Note

     Do not double-click a Word template file to open it. Double-clicking the file opens a Word document file that uses the template.

2. In Word,on the Home tab, in the Paragraph group, click the Multilevel List icon and then click Define New List Style.

3. Set Name to your style name.

4. Specify the formatting, such as the bullet style and color for each list level.

5. Select New documents based on this template.

6. Click OK to save the template.

For an example that defines a Word list style, see Custom Styled Word List.

Create HTML or PDF List Styles

To define a list style in a cascading style sheet (CSS) for an HTML or PDF template , use the ul element for unordered list styles and the ol element for ordered list styles. You can use the child selector (>) to define multilevel list styles. See Modify Styles in HTML Templates and Modify Styles in PDF Templates.

For example, this CSS code defines the appearance of a two-level unordered list that can contain ordered or unordered sublists.

ul.MyUnorderedList {
	list-style-type:disc;
}

ul.MyUnorderedList > ul {
	list-style-type:circle;
}

ul.MyUnorderedList > ol {
	list-style-type:decimal;
}

For information about editing CSS, see documentation such as the W3Schools.com CSS tutorial.

Format Lists Programmatically

Format lists programmatically by adding format objects, such as an mlreportgen.dom.Color object, to the Style property of an mlreportgen.dom.UnorderedList, mlreportgen.dom.OrderedList, or mlreportgen.dom.ListItem object. Formatting that you specify in the Style property overrides a template-defined style.

For lists in PDF and HTML reports, you can specify the bullet type or numbering type by using an mlreportgen.dom.ListStyleType format object.

For example, this code creates a green, ordered list with lowercase alphabetic bullets. The third list item is blue and italic.

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

ol = OrderedList(["one", "two", "three"]);
ol.Style = {Color('Green'),ListStyleType('lower-alpha')};
ol.Children(3).Style = {Color('blue'),Italic(true)};
append(d,ol);

close(d);
rptview(d);

Here is the list in the generated report:

You can also format the DOM objects that you use to create list items by using the format properties or format objects associated with the object. For example, this code formats mlreportgen.dom.Text objects before they are used to create a list.

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

li1 = Text('red');
li1.Color = 'Red';
li2 = Text('blue');
li2.Color = 'Blue';

append(d,{li1, li2});

close(d);
rptview(d);

Here is the list in the generated report:

Format List Items in Multilevel Lists

Depending on how you create a multilevel list, a sublist can be a child of the parent list or a child of the preceding list item in the parent list. See Create Multilevel Lists.

If the sublist is a child of a list item of the parent list, the sublist inherits the formatting from the list item. For example, this code makes a sublist the child of the second list item in the parent list.

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

parentlist = OrderedList();
li1 = ListItem('List Item 1');
li2 = ListItem('List Item 2');
li2.Style = [li2.Style {Color('red')}];

sublist = UnorderedList({'Sublist Item 1' 'Sublist Item 2'});
append(li2,sublist);

append(parentlist,li1);
append(parentlist,li2);
append(d,parentlist);

close(d);
rptview(d);

The sublist inherits the red color from the list item that contains it.

If you do not want a sublist to inherit formatting from the previous list item, format the paragraph or text in the previous list item instead of formatting the list item. For example:

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

parentlist = OrderedList();
li1 = ListItem('List Item 1');
txt = Text('List Item 2');
txt.Color = 'red';
li2 = ListItem(txt);

sublist = UnorderedList({'Sublist Item 1' 'Sublist Item 2'});

append(parentlist,li1);
append(parentlist,li2);
append(parentlist,sublist);

append(d,parentlist);

close(d);
rptview(d);

Alternatively, you can create the sublist as a child of the parent list rather than a child of the previous list item in the parent list. If the sublist is a child of the parent list, the sublist does not inherit the formatting of the previous list item in the parent list. For example, this code makes a sublist a child of the parent list:

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

parentlist = OrderedList();
li1 = ListItem('List Item 1');
li2 = ListItem('List Item 2');
li2.Style = [li2.Style {Color('red')}];

sublist = UnorderedList({'Sublist Item 1' 'Sublist Item 2'});

append(parentlist,li1);
append(parentlist,li2);
append(parentlist,sublist);

append(d,parentlist);

close(d);
rptview(d);

The second list item of the parent list is red, but the sublist is black.