Main Content

mlreportgen.dom.XRef Class

Namespace: mlreportgen.dom

Cross-reference element for DOCX or PDF report

Since R2022a

expand all in page

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 vector 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:

NonCopyable
true

Data Types: char | string

Name of the style to use to render the cross-reference, specified as a character vector or string scalar. 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

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:

NonCopyable
true

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.

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.

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 of the document element to which this object is appended.

Attributes:

NonCopyable
true

Tag for mlreportgen.dom.XRef object, specified as a character vector or string scalar. The DOM API 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. Specify your own tag value to help you identify where to look when an issue occurs during document generation.

Attributes:

NonCopyable
true

Data Types: char | string

Object identifier for mlreportgen.dom.XRef object, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object. You can specify your own value for Id.

Attributes:

NonCopyable
true

Data Types: char | string

Methods

expand all

Examples

collapse all

Open Live Script

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

See Also

| | | | |

Topics