Create and Format Lists

You can add two kinds of lists to a report:

  • Unordered (bulleted)

  • Ordered (numbered)

  • Multilevel (lists that contain ordered or unordered lists in any combination)

Create an Ordered or Unordered List

You can create lists from a numeric or cell array or one item at a time.

  • Creating a list from a cell array allows you to include items of different types in the list.

  • Creating a list one item at a time is useful for including multiple objects in a list item.

Create an Unordered List from an Array

You can create an unordered list by appending a one-dimensional numeric or cell array to a document (or document part). The append function converts the array to an mlreportgen.dom.UnorderedList object, appends the object to the document, and returns the object, which you can then format. In the cell array, you can include character vectors, numbers, and some DOM objects, such as a Text object. For a list of DOM objects you can include, see mlreportgen.dom.ListItem.

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

t = Text('third item');
append(d,{'first item',6,t,'fourth item'});

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

Create a List Using an Array

You can create an unordered or ordered list from an array by including the array in an UnorderedList or OrderedList object constructor. In the cell array, you can include character vectors, numbers, and some DOM objects, such as a Text object. For a list of DOM objects you can include, see mlreportgen.dom.ListItem.

This example creates an unordered list. Change the UnorderedList class to OrderedList to number the items.

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

ul = UnorderedList({Text('item1'),'item 2',3});
append(d,ul);

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

Create a List Item by Item

You can create a list one item at a time by creating mlreportgen.dom.ListItem objects and appending them to an UnorderedList or OrderedList object.

This example creates an ordered list. Change the OrderedList class to UnorderedList to use bullet items.

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

li1 = ListItem('Rank 3 magic square:');
table = append(li1,Table(magic(3)));
table.Border = 'inset';
table.Width = '1in';
li2 = ListItem('Second item');
li3 = ListItem('Third item');

ul = OrderedList();
append(ul,li1);
append(ul,li2);
append(ul,li3);

append(d,ul);

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

Create a Multilevel List

A multilevel list is an ordered or unordered list whose list items contain ordered or unordered lists. You can create lists that have as many as nine levels.

You can create multilevel lists either from cell arrays or one list at a time. Creating a multilevel list one item at a time is useful for creating list items that contain multiple paragraphs, paragraphs and tables, and other combinations of document elements.

Create a Multilevel List from a Cell Array

You can use any of these approaches to create a multilevel list from a cell array.

  • Nest one-dimensional cell arrays representing sublists in a one-dimension cell array representing the parent list.

    import mlreportgen.dom.*;
    d = Document('orderedListReport','html');
    
    ol = OrderedList({'step 1','step 2',...
         {'option 1','option 2'},...
         'step 3'});
    append(d,ol);
    
    close(d);
    rptview(d.OutputPath);
    
  • Include list objects as members of a one-dimensional cell array representing the parent list. Use this approach to create ordered sublists from cell arrays.

    d = Document('myListReport','html');
    
    append(d,{'1st item',OrderedList({'step 1','step 2'}),'2nd item'});
    
    close(d);
    rptview(d.OutputPath);
    
  • Combine the nested cell array and nested list object approaches.

Create a Multilevel List One List at a Time

You can create a multilevel list from scratch by appending child lists to parent lists.

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

ol = OrderedList({'Start MATLAB', ...
     'Create a rank 3 or 4 magic square:'});
optionList = UnorderedList;
li = ListItem('>> magic(3)');
table = append(li,Table(magic(3)));
table.Width = '1in';
append(optionList, li);
li = ListItem('>> magic(4)');
table = append(li,Table(magic(4)));
table.Width = '1in';
append(optionList,li);
append(ol, optionList);
append(ol, ListItem('Close MATLAB'));, 
append(d,ol);
close(d);
rptview('orderedListReport','html');

Format Lists

You can use list styles defined in a report style sheet to specify the indentation of each level of a list and the type of bullet or the number format used to render list items. For PDF and HTML, you can specify the bullet type or numbering type in the style sheet or using the mlreportgen.dom.ListStyleType format property on a ListItem object.

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:

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

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

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

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 UnorderedList object that numbers top-level items, the top-level items are numbered, even though the object type is unordered (bulleted).

Create a Word List Style

To define a list style in a Word template, select List as the style type in the Create New Style from Formatting dialog box. See Add Styles to a Word Template.

Create an HTML or PDF List Style

To define a list style in an HTML or PDF template cascading style sheet (CSS), 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.

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.

See Also

Classes

Functions

Related Topics