mlreportgen.dom.XRef Class

R2026b

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.

To see what DOM objects you can append an mlreportgen.dom.XRef object to, see Append mlreportgen.dom.XRef object to DOM class object.

This class is only compatible with these MATLAB® Report Generator™ output types:

  • "docx"

  • "pdf"

  • "pdfa" (since R2025a)

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.

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

example

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:

GetAccess
public
SetAccess
public
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
NonCopyable
true

Data Types: char | string

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

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: cell

Custom attributes of the 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:

GetAccess
public
SetAccess
public
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.

Attributes:

GetAccess
public
SetAccess
private
NonCopyable
true

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
private
NonCopyable
true

Tag, 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. Use this value to help identify where an issue occurs during document generation.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: char | string

Object identifier, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: char | string

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.

More About

expand all

Version History

Introduced in R2022a

See Also

| | | | |

Topics