Automatically Number Document Content

You can automatically number document content, such as chapter, section, table, and figure headings. Append automatic numbering objects to the document where you want numbers to appear. Each automatic number is associated with a numbering stream that determines the value of each number in a sequence. Report generation replaces an automatic numbering object with a number based on its position in the document relative to other automatic numbers in the same stream. For example, the first automatic numbering object in a stream is replaced with 1, the second with 2, and so on. You can use automatic numbering to create hierarchical numbering schemes such as Section 1.1 and Section 1.2.

You can automatically number document content programmatically or by defining the autonumbers in a template.

Automatically Number Content Programmatically

To automatically number document content programmatically, do the following at each point in a document where you want an automatically generated number to appear.

1. Create an automatic numbering object, using the mlreportgen.dom.AutoNumber constructor. Specify the name of the associated automatic numbering stream in the constructor. For example, this line creates an automatic number belonging to the stream named chapter.

   chapterNumber = AutoNumber('chapter');

   Note

   If the specified automatic numbering stream does not exist, the AutoNumber constructor creates a numbering stream having the specified name. The implicitly constructed stream renders automatic numbers as Arabic numerals. To use a stream with different properties, create the stream explicitly, using a createAutoNumberStream function of a Document object.

2. Append the AutoNumber to a Text, Paragraph, or Heading object that contains the text that precedes the automatic number.

   append(chapHead,chapterNumber);

3. Append an mlreportgen.dom.CounterInc format object to the Style property of the content object that you want to automatically number. Appending a CounterInc object increments the stream associated with the automatic number when the paragraph or heading is output. The updated value replaces the AutoNumber object.

   chapHead.Style = {CounterInc('chapter'), WhiteSpace('preserve')};

This code automatically numbers the chapter headings in a document.

import mlreportgen.dom.*;
d = Document('MyReport','html');
 
for rank = 3:5
    chapHead = Heading1('Chapter ','Heading 1');
    append(chapHead,AutoNumber('chapter'));
    append(chapHead,sprintf('. Rank %i Magic Square',rank));
    chapHead.Style = {CounterInc('chapter'), ...
                      WhiteSpace('preserve')};
    append(d,chapHead);
    table = append(d,magic(rank));
    table.Width = '2in';
end
 
close(d);
rptview(d.OutputPath);

Create Hierarchical Automatic Numbering

You can create hierarchical numbering schemes, such as 1.1, 1.2, 1.3, 2.1, and 2.2. Use an mlreportgen.dom.CounterReset format object to reset a child automatic number to its initial value when its parent number changes. For example, this code uses a CounterReset format object to reset the chapter table number stream at the beginning of each chapter.

import mlreportgen.dom.*;
d = Document('MyReport','html');
 
for rank = 3:2:9
    chapHead = Heading(1,'Chapter ');
    append(chapHead, AutoNumber('chapter'));
    chapHead.Style = {CounterInc('chapter'), ...
                      CounterReset('table'), ...
                      WhiteSpace('preserve')};
    append(d,chapHead);
    
    for i = 0:1;
        tableHead = Paragraph('Table ');
        append(tableHead,AutoNumber('chapter'))
        append(tableHead,'.');
        append(tableHead, AutoNumber('table'));
        append(tableHead, ...
           sprintf('. Rank %i Magic Square',rank+i));
        tableHead.Style = {CounterInc('table'), ...
                           Bold, ...
                           FontSize('11pt'), ...
                           WhiteSpace('preserve')};
        append(d,tableHead);
        table = append(d,magic(rank+i));
        table.Width = '2in';
    end
end
 
close(d);
rptview(d.OutputPath);

Automatically Number Content Using Part Templates

You can automatically number a document by creating a document part object based on templates containing Microsoft^® Word, HTML, or PDF automatic numbering and repeatedly appending the parts to a document.

Automatic Numbering in Word Reports

Suppose that you add a chapter part template Chapter to the part template library of the Word MyReportTemplate.dotx report template. This template uses a Word sequence (SEQ) field to number the chapter heading. The template also contains holes for the chapter title and the chapter content.

This code uses the chapter part template to create numbered chapters. The last statement in this code opens the report in Word and updates it. Updating the report causes Word to replace the SEQ fields with the chapter numbers.

import mlreportgen.dom.*
doctype = 'docx';
d = Document('MyReport',doctype,'MyReportTemplate');

for rank = 3:5
    chapterPart = DocumentPart(d,'Chapter');
    while ~strcmp(chapterPart.CurrentHoleId,'#end#')
       switch chapterPart.CurrentHoleId
           case 'ChapterTitle'
              append(chapterPart, ...
                 sprintf('Rank %i Magic Square',rank));
           case 'ChapterContent'
              table = append(chapterPart,magic(rank));
              table.Width = '2in';
       end
       moveToNextHole(chapterPart);
    end
    append(d, chapterPart);
end

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

Automatic Numbering in HTML Reports

To create automatic numbering in HTML reports, create a document part that uses the counter-increment property, and define the counter in the style sheet. For example, to create a document part to work with the same program used in Automatic Numbering in Word Reports, create a document part template in your HTML document library similar to this code. The code defines the chapter counter and specifies a class an_chapter to hold the autonumber. It also defines holes for the title and for the content to work with the program.

<dptemplate name="Chapter">
      <p style="counter-increment:chapter;"><span>Chapter </span>
           <span class="an_chapter"></span> 
      <hole id="ChapterTitle" /></p>
      <hole id="ChapterContent" />
 </dptemplate>

In the style sheet, define the an_chapter class. Use the content property to specify the chapter counter as the content.

span.an_chapter:before {
content: counter(chapter);
}

Use the same program as you used for Word, changing the value for doctype to 'html'.

Automatic Number in PDF Reports

Creating automatic numbers for PDF is similar to HTML, except the DOM API provides an HTML element <autonumber> for PDF templates that simplifies automatic numbering. Specify the stream-name attribute for the autonumber element. For the stream name, use the value of a counter-increment property, in this case chapter.

<dptemplate name="Chapter">
    <p style="counter-increment:chapter;"><span>Chapter </span>
          <autonumber stream-name="chapter"/> 
       <hole id="ChapterTitle" /></p>
       <hole id="ChapterContent" />
 </dptemplate>

You do not need to add properties in the style sheet to use the autonumber.

Use the same program you used for Word, changing the value for doctype to 'pdf'.