mlreportgen.dom.XRef Class

Namespace: mlreportgen.dom

Cross-reference element for DOCX or PDF report

Since R2022a

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.

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

Properties

Target — Link ID of target object

[] (default) | character vector | string scalar

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

StyleName — Name of style to apply from style sheet

[] (default) | character vector | string scalar

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

Style — Format objects

cell array

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

CustomAttributes — Custom attributes of document element

[] (default) | array of mlreportgen.dom.CustomAttribute objects

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

Parent — Object to which cross-reference object is appended

[] (default) | mlreportgen.dom.Paragraph object

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:

SetAccess	private
NonCopyable	true

Children — Objects appended to cross-reference object

[] (default) | mlreportgen.dom.CustomElement array

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:

SetAccess	private
NonCopyable	true

Tag — Tag

character vector | string scalar

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

Id — Object identifier

character vector | string scalar

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

Public Methods

clone

xRefCopy = clone(xRefObj) creates a copy of xRefObj.

Examples

Use Cross-Reference Elements in a PDF Report

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