Main Content

mlreportgen.dom.XRef class

Package: mlreportgen.dom

Cross-reference element for DOCX or PDF report

Description

Use an object of the mlreportgen.dom.XRef class to cross-reference a target in a DOCX or PDF report.

The mlreportgen.dom.XRef class is a handle class.

Class Attributes

HandleCompatible
true

For information on class attributes, see Class Attributes.

Creation

Description

xRefObj = mlreportgen.dom.XRef() creates an mlreportgen.dom.XRef object with an empty Target property. Set the Target property before you add the XRef object to a report.

example

xRefObj = mlreportgen.dom.XRef(target) creates an XRef object with the link ID, target.

Properties

expand all

Link ID of the target object to cross-reference, specified as a character array or string scalar. Set the Target property to the link ID of the mlreportgen.dom.LinkTarget object you want to cross-reference.

Note

Use the mlreportgen.utils.normalizeLinkID function to generate a valid link target ID that conforms to the limitations of PDF and Microsoft® Word documents.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

Format objects, specified as a cell array of mlreportgen.dom format objects. Add one or more format objects to customize the appearance of the cross-reference.

Attributes:

GetAccess
public
SetAccess
public

Name of the style to use to render the cross-reference, specified as a string scalar or character vector. The style must be defined in the style sheet of the template associated with the document that contains the cross-reference. To learn more about using style sheets, see Use Style Sheet Styles.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

Object to which the cross-reference object is appended, specified as an mlreportgen.dom.Paragraph object.

Note

You can append an XRef object only to an object of the class mlreportgen.dom.Paragraph.

Attributes:

GetAccess
public
SetAccess
public

Data Types: mlreportgen.dom.Paragraph

Objects appended to the XRef object, specified as an mlreportgen.dom.CustomElement array.

Note

You can append only objects of the class mlreportgen.dom.CustomElement to an XRef object.

Attributes:

GetAccess
public
SetAccess
public

Data Types: mlreportgen.dom.CustomElement

Tag for this document element, specified as a character vector or string scalar.

The DOM generates a session-unique tag as part of the creation of this object. The generated tag has the form CLASS:ID, where CLASS is the object class and ID is the value of the Id property of the object. Specifying your own tag value can help you to identify where an issue occurred during document generation.

Custom attributes of this document element, specified as an array of mlreportgen.dom.CustomAttribute objects. The custom attributes must be supported by the output format.

ID for this document element, specified as a character vector or string scalar. The DOM generates a session-unique ID when it creates the document element. You can specify your own ID.

Methods

expand all

Examples

collapse all

This example shows how to use cross-reference elements in a generated PDF report.

Import these packages so that you do not have to use long, fully qualified class names.

import mlreportgen.dom.*
import mlreportgen.report.*

Create an mlreportgen.report.Report object of type PDF.

rpt = Report("Cross-ref_in_PDF_example","pdf");

Create an mlreportgen.report.Chapter object for the introduction chapter, and an mlreportgen.dom.Paragraph object for the content of the introduction chapter.

chapter1 = Chapter("Introduction");
para = Paragraph();
para.WhiteSpace = "preserve";

Use the function normalizeLinkID to generate a valid unique link ID, then use this link ID to create an mlreportgen.dom.LinkTarget object.

linkID = mlreportgen.utils.normalizeLinkID("myLinkID");
linkTarget = LinkTarget(linkID);

Create two reference objects, an mlreportgen.dom.XRef and an mlreportgen.dom.PageRef, with the same link ID you used to create the LinkTarget object. You must use the same link ID for all three objects to link the reference objects to the link target object.

xRefObj = XRef(linkID);
pageRefObj = PageRef(linkID);

Customize the appearance of the cross-reference object by adding an mlreportgen.dom.Italic object to the Style property.

xRefObj.Style{end+1} = Italic;

Set the IsXRefTarget property of the LinkTarget object to true. This is necessary only in PDF reports.

linkTarget.IsXRefTarget = true;

Fill the paragraph with content that includes the cross-reference and the page reference objects.

append(para,"For more information see ");
append(para,xRefObj);
append(para," on page ");
append(para,pageRefObj);
append(para," for more information.");

Append the paragraph object to the chapter object, then append the chapter object to the report.

append(chapter1,para)
append(rpt,chapter1);

Create another Chapter object for the information chapter.

chapter2 = Chapter();

Append the text "Information" to the link target object and set the title of the chapter object to the link target object.

linkTarget.append("Information");
chapter2.Title = linkTarget;

Append the second chapter object to the report. Then close and view the report.

append(rpt,chapter2);
close(rpt);
rptview(rpt);

When the report opens, test the cross-reference and page reference elements.

Version History

Introduced in R2022a