目次の作成

mlreportgen.report.TableOfContents クラスを使用して、レポートに目次を追加できます。この事前定義されたクラスによって、レポートの見出しを含む書式設定済みの目次がレポートに自動的に追加されます。DOM オブジェクトを使用して目次を作成するよりも、このクラスを使用する方がはるかに簡単で効率的です。詳細と例については、mlreportgen.report.TableOfContents を参照してください。

あるいは、DOM オブジェクトを使用することで、目次をレポートプログラムで作成したり、テンプレートを使用して目次を定義できます。プログラムによって目次を作成するには、mlreportgen.dom.TOC オブジェクトをレポートドキュメントに追加します。

テンプレートを使用すると、そのテンプレートを使用するすべてのレポートプログラムで必ず同じ種類の目次が作成されるようになります。また、テンプレートでは、書式変更の場合に目次の更新が 1 か所のみで済みます。

テンプレートを使用している場合は、以下のいずれかを行います。

Word テンプレートまたは HTML/PDF テンプレートパッケージ (root.html) に目次参照を含める。
目次のドキュメントパーツテンプレートを作成し、そのドキュメントパーツをプログラムによって挿入する。

レポートプログラムではどちらかの方法を使用して、アウトラインレベルを指定する数値レベルオブジェクトまたは段落オブジェクトを指定する、見出しオブジェクトを作成しなければなりません。目次ジェネレーターは、レベル情報をもつコンテンツを使用して構造を定義します。

レポートプログラムでの目次の作成

DOM API は、ドキュメントの目次の自動生成をサポートしています。目次の自動生成を可能にするには、以下のようにします。

ドキュメント内で Paragraph オブジェクトまたは見出しオブジェクト (Heading、Heading1 など) を使用して節見出しを指定する。見出しに Paragraph オブジェクトを使用する場合、段落の OutlineLevel プロパティを適切な値に設定しなければなりません。たとえば、章などの最上位の見出しには 1 を設定します。
ドキュメントで目次を生成する位置に、目次プレースホルダーを挿入する。目次プレースホルダーは、プログラムによって挿入するか、またはドキュメントのテンプレート内に挿入することができます。

プログラムによる目次の作成

プログラムによって目次プレースホルダーを作成するには、目次を生成する位置に mlreportgen.dom.TOC オブジェクトを追加します。目次に含めるレベルの数およびリーダーのタイプを指定できます。既定値は 3 つのレベルおよび点線リーダーです。この例では、2 つのレベルと点線リーダーを使用します。

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

title = append(d,Paragraph('My TOC Document'));
title.Bold = true;
title.FontSize = '28pt';

toc = append(d,TOC(2));
toc.Style = {PageBreakBefore(true)};

h1 = append(d,Heading1('Chapter 1'));
h1.Style = {PageBreakBefore(true)};
p1 = append(d,Paragraph('Hello World'));

h2 = append(d,Heading2('Section 1.1'));
h2.Style = {PageBreakBefore(true)};
p2 = append(d,Paragraph('Another page'));

h3 = append(d,Heading3('My Subsection 1.1.a'));
p3 = append(d, Paragraph('My Level 3 Heading Text'));

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

テンプレートを使用した Microsoft Word の目次の作成

Word を使用して、Word ドキュメントやドキュメントパーツテンプレートに Word の目次参照オブジェクトを挿入できます。Word はドキュメントを更新する際、目次参照を自動的に生成される目次に置き換えます。

目次参照を含むテンプレートを使用して DOM Word レポートに目次を生成するには、以下のようにします。

レポート内で目次を生成する位置を指定するには、Word テンプレートに目次参照を作成します。Word の目次参照の作成を参照してください。
目次に表示する節見出しのアウトラインレベルを設定します。節見出しのアウトラインレベルの設定を参照してください。
生成されたドキュメントを更新します。Word レポートの目次の更新を参照してください。

Word の目次参照の作成

Word でテンプレートを開きます。
目次を作成する位置をクリックします。
[参考資料] タブで [目次] をクリックします。
目次の書式オプションを選択して、目次を生成します。たとえば、[組み込み] 書式オプションを選択します。目次が表示されます。
テンプレートを保存します。

メモ

ドキュメントパーツを使用して目次を挿入する場合、ドキュメントパーツのテンプレートに目次参照を挿入します。テンプレートからインスタンスを削除してから保存します。Microsoft Word のドキュメントパーツテンプレートライブラリの作成とプログラムでのドキュメントパーツの使用による目次のプレースホルダーの挿入を参照してください。

Word レポートの目次の更新

目次を生成するには、目次参照を含む Word ドキュメントを更新しなければなりません。Windows^® システムでは、DOM API rptview コマンドは Word を使用して、Word ドキュメントを表示して更新します。Windows 以外のシステムの DOM API によって生成されたドキュメントなど、Word ドキュメントを直接開く場合、目次を更新しなければなりません。

Word テンプレートで、目次参照を選択します。
[参考資料] タブで [目次の更新] をクリックします。
[目次の更新] ダイアログボックスで [目次をすべて更新する] を選択し、[OK] をクリックします。

HTML または PDF テンプレートでの目次の作成

PDF または HTML テンプレートを使用して目次を追加するときに、以下を行うことができます。

テンプレートパッケージのメインテンプレート (root.html) に目次プレースホルダーを含める。
ドキュメントパーツテンプレートに目次プレースホルダーを含める。

ドキュメントパーツテンプレートを使用して HTML または PDF レポートに目次を生成するには、以下のようにします。

目次プレースホルダーを含むドキュメントパーツテンプレートを定義する。
プログラムによってレポートにドキュメントパーツを挿入する。
Paragraph オブジェクトまたは見出しオブジェクト (Heading、Heading1 など) を使用してレポートの見出しを指定する。見出しに Paragraph オブジェクトを使用する場合、その OutlineLevel プロパティを適切な値に設定しなければなりません。

目次のドキュメントパーツテンプレートの定義

目次のドキュメントパーツテンプレートを作成または変更するには、コードを以下の形式で使用します。

<dptemplate name="ReportTOC">
     <TOC number-of-levels ="3" leader-pattern="dots" />
</dptemplate>

次が可能です。

ReportTOC を任意の名前に置き換える。
number-of-levels を、目次に含める見出しレベルの数に設定する。
leader-pattern を dots または spaces に設定する。

例については、PDF と HTML のドキュメントパーツおよびホールを参照してください。

プログラムでのドキュメントパーツの使用による目次のプレースホルダーの挿入

目次プレースホルダーを含むドキュメントパーツのインスタンスを挿入するには、DocumentPart クラスを使用します。テンプレートでドキュメントパーツテンプレートを定義する場合、ドキュメントオブジェクトを定義する際にテンプレートパッケージ名を含めます。例:

d = Document('MyReport','html','MyTemplate');

このコードは、既定のテンプレート内に用意されているドキュメントパーツ ReportTOC を使用して目次を生成します。

import mlreportgen.dom.*;
d = Document('MyReport','pdf');
append(d,'My Report');

append(d,DocumentPart(d,'ReportTOC'));
append(d,Heading1('Chapter 1'));
append(d,Heading2('Section 1'));

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

ヒント

ドキュメントオブジェクトに関連付けられたドキュメントパーツテンプレートを使用するには、DocumentPart 構文の Document オブジェクトに割り当てられた変数を使用します。

append(d,DocumentPart(d,'ReportTOC'));

この構文を使用する場合、ドキュメントパーツを参照する際にテンプレートを呼び出してドキュメントタイプを指定する必要はありません。この方法によってコードが単純化され、より効率的にレポートが生成されます。

節見出しのアウトラインレベルの設定

レポートに目次を生成するには、プログラムは目次に表示する節見出しのアウトラインレベルを設定しなければなりません。アウトラインレベルは、目次で段落のコンテンツが表示されるかどうか、および段落のコンテンツがどのレベルで表示されるかを指定する、段落の書式プロパティです。たとえば、段落のアウトラインレベルが 1 の場合、コンテンツは生成された目次の最上位に表示されます。アウトラインレベルは最大で 9 まで指定できます。

段落のアウトラインレベルを設定するには、以下のいずれかの方法を使用します。

テンプレート定義スタイルを使用したアウトラインレベルの設定

レポートのテンプレートで定義したスタイルを使用して、段落のアウトラインレベルを設定できます。Word ドキュメントには、見出し 1 や見出し 2 など、アウトラインレベルを定義する一連のスタイルが既定で含まれています。プログラムは、これらの組み込みスタイルを使用して、これらの見出しが目次に表示されるように指定できます。この例では、テンプレート定義スタイルを使用して節見出しのアウトラインレベルを設定し、テンプレート MyTemplate が目次参照を含むと仮定します。

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

append(d,Paragraph('Chapter 1','Heading 1'));
append(d,Paragraph('Section 1','Heading 2'));

close(d);
rptview(d.OutputPath); % Updates the TOC

Word または HTML エディターを使用して独自の見出しスタイルを定義した後、それらを使用してレポートを生成することもできます。

書式オブジェクトを使用したアウトラインレベルの設定

書式オブジェクトを使用して、アウトラインレベルを設定できます。この例では、テンプレート MyTemplate が目次参照を含んでいるとします。

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

h1 = {FontFamily('Arial'),FontSize('16pt'),OutlineLevel(1)};
h2 = {FontFamily('Arial'),FontSize('14pt'),OutlineLevel(2)};
p = append(d,Paragraph('Chapter 1'));
p.Style = h1;
p = append(d,Paragraph('Section 1'));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

見出しオブジェクトを使用したアウトラインレベルの設定

mlreportgen.dom.Heading1 オブジェクト (および Heading2、Heading3 など) を使用して、アウトラインレベルを指定できます。Heading1 オブジェクトは、コンストラクターによってアウトラインレベルを指定する段落です。Heading1 オブジェクトは、単体またはテンプレートベース/書式オブジェクトベースのスタイルと共に使用できます。この例では、テンプレート MyTemplate が目次参照を含んでいるとします。

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

h1 = {FontFamily('Arial'),FontSize('16pt')};
h2 = {FontFamily('Arial'),FontSize('14pt')};
h = append(d,Heading1('Chapter 1'));
h.Style = h1;
h = append(d,Heading2('Section 1'));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

HTML および PDF レポートにおいて、Heading1 オブジェクトと Heading2 オブジェクトは HTML 要素 h1 と h2 を生成します。オブジェクト Heading1 や Heading2 などを使用することにより、レポートが既定の見出しのスタイルを確実に使用するようにできます。