mlreportgen.dom.EmbeddedObject Class

Namespace: mlreportgen.dom
Superclasses: mlreportgen.dom.ExternalLink

Embed a file in a document

Since R2020a

Description

Use an object of the mlreportgen.dom.EmbeddedObject class to embed a file in a document. The advantage of embedding a file in a document, instead of linking to it, is that you can move the document without moving the target file.

You can append an mlreportgen.dom.EmbeddedObject object to objects of these DOM classes:

mlreportgen.dom.Document
mlreportgen.dom.DocumentPart
mlreportgen.dom.Paragraph
mlreportgen.dom.TableEntry
mlreportgen.dom.TableHeaderEntry
mlreportgen.dom.ListItem

The effect of appending an EmbeddedObject object to a DOM object depends on the document output type and the external file type, as described in this table.

Document Output Type	External File Type	Behavior
Word	`xlsx`, `pptx`, `docx`	Embeds the external file in the document and inserts an Object Linking and Embedding (OLE) link to the embedded file. If you open the document without first opening it with `rptview`, the OLE link displays a placeholder image. After you open the document with `rptview`, the OLE link displays an image of the embedded file content. To see and edit the embedded file content, double-click the image.
Word	Any type except `xlsx`, `pptx`, or `docx`	Does not embed the file in the document. Inserts a hyperlink to the external file.
PDF	Any	Embeds the external file in the document and inserts an annotation that has a paper clip icon. To open the embedded file, double-click the icon. To see the paper clip icon, you must open the PDF outside of MATLAB^®. If you still do not see the paper clip icon, try opening the PDF using a different PDF viewer, such as Adobe^® Acrobat^®. If you need to open the PDF using a viewer that does not display the paper clip icon, instead of embedding the document, consider linking to the document by using an `mlreportgen.dom.ExternalLink` object.
HTML	Any	Embeds the external file in the document and inserts a hyperlink to the embedded file. In an HTML document, the hyperlink works only if you open the document outside of MATLAB.
Single-file HTML	Any	Does not embed the file in the document. Inserts a hyperlink to the external file. The hyperlink works only if you open the document outside of MATLAB.

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

Class Attributes

`ConstructOnLoad`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Creation

Description

embObj = mlreportgen.dom.EmbeddedObject() creates an empty EmbeddedObject object. To specify the file to embed, use the Target property.

embObj = mlreportgen.dom.EmbeddedObject(path) sets the Target property to the path of the file to embed.

example

embObj = mlreportgen.dom.EmbeddedObject(path,linkText) also specifies the link text. The link text applies only when the reference to a file is a hyperlink. This constructor creates an mlreportgen.dom.Text object to hold the link text.

example

embObj = mlreportgen.dom.EmbeddedObject(path,linkText,styleName) specifies the name of the template-defined style to use for the link text. This constructor creates an mlreportgen.dom.Text object to hold the link text and sets the StyleName property of the Text object to styleName.

embObj = mlreportgen.dom.EmbeddedObject(path,linkTextObj) uses an mlreportgen.dom.Text object to specify the link text.

Input Arguments

expand all

`path` — Path of file to embed
character vector | string scalar

Path of the file to embed, specified as a character vector or string scalar.

`linkText` — Link text
character vector | string scalar

Link text, specified as a character vector or string scalar. The link text applies only when the reference to a file is a hyperlink.

`linkTextObj` — Link text
`mlreportgen.dom.Text` object

Link text, specified as an mlreportgen.dom.Text object. The link text applies only when the reference to a file is a hyperlink.

`styleName` — Name of style for link text
character vector | string scalar

Name of the template-defined style to use for the link text, specified as a character vector or string scalar.

Properties

expand all

`Target` — Path of file to embed in document
`''` (default) | character vector | string scalar

Path of the file to embed in the document, specified as a character vector or string scalar.

Attributes:

NonCopyable true

Data Types: char | string

`TargetSite` — Specifies the window in which the target will be opened
`"samewindow"` (default) | `"newwindow"`

The window in which the target will be opened, specified as a character vector or string scalar.

Possible values are:

"samewindow" - (default) opens a target in the same window
"newwindow" - opens a target in a new window

Note

This property applies only to HTML output-type reports.

Attributes:

NonCopyable true

Data Types: char | string

`StyleName` — Name of style to use for link
`[]` (default) | character vector | string scalar

Name of the style to use for the link, specified as a character vector or string scalar. The style specified by the StyleName property must be defined in the template that is used to create the document to which the EmbeddedObject is appended. The StyleName property applies only when the reference to a file is a hyperlink.

Attributes:

NonCopyable true

Data Types: char | string

`Style` — Formats that define link style
`{}` (default) | cell array of DOM format objects

Formats that define the style of a link, specified as a cell array of DOM format objects. Formats specified in the Style property override formats specified by a template-defined style. The Style property applies only when the reference to a file is a hyperlink.

Attributes:

NonCopyable true

`CustomAttributes` — Custom attributes of document element
`[]` (default) | array of `mlreportgen.dom.CustomAttribute` objects

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

`Parent` — Parent of `mlreportgen.dom.EmbeddedObject` object
document element object

Parent of mlreportgen.dom.EmbeddedObject object, specified as a document element object. A document element must have only one parent.

Attributes:

`SetAccess`	`private`
`NonCopyable`	`true`

`Children` — Children of `mlreportgen.dom.EmbeddedObject` object
array of document element objects

Children of mlreportgen.dom.EmbeddedObject object, specified as an array of document element objects. This property contains the document element objects appended using the append method.

Attributes:

`SetAccess`	`private`
`NonCopyable`	`true`

`Tag` — Tag for `mlreportgen.dom.EmbeddedObject` object
character vector | string scalar

Tag for the mlreportgen.dom.EmbeddedObject 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

`Id` — Object identifier for `mlreportgen.dom.EmbeddedObject` object
character vector | string scalar

Object identifier for the mlreportgen.dom.EmbeddedObject 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

Public Methods

append

Append text, an image, or a custom element to the reference to the file in a document. Use append with an mlreportgen.dom.EmbeddedObject object the same way as you use append with an mlreportgen.dom.ExternalLink object.

The append method applies only when the reference to a file is a hyperlink.

clone

clone = clone(embeddedObj) creates a copy of this mlreportgen.dom.EmbeddedObject object.

To repeat the content in a document, use clone. Do not append the same object to a document more than one time.

Examples

collapse all

Embed a Word Document in a Different Word Document

Create a Word document, CompanyInfo.docx, and embed it in a second Word document, CompanyReport.docx.

import mlreportgen.dom.*

doc1 = Document('CompanyInfo','docx');
append(doc1, 'XYZ, Inc., makes widgets.');
close(doc1);

doc1Path = doc1.OutputPath;

doc2 = Document('CompanyReport','docx');
open(doc2);

para = append(doc2,Paragraph('About XYZ, Inc.'));
append(doc2, EmbeddedObject(doc1Path));
close(doc2);
rptview(doc2);

The document, CompanyReport.docx, displays an image of the embedded file.

Document text, "About XYZ, Inc.", followed by a clickable image that reads XYZ, Inc., makes widgets.

To open the embedded document, double-click the image.

Embed a PDF in an HTML Document

Create a PDF, bio.pdf, and embed it in an HTML document, author.html. Specify the link text in the mlreportgen.dom.EmbeddedObject constructor. Make the link green.

import mlreportgen.dom.*
doc1 = Document('bio','pdf');
para = 'The author was born in New York, NY in 1970.';
append(doc1,para);
close(doc1);

doc2 = Document('author','html');
doc2.PackageType = 'unzipped';

embedObj = EmbeddedObject('bio.pdf','Author Biography');
embedObj.Style={Color('green')};
p = Paragraph();
append(p,embedObj);
append(doc2,p);

close(doc2);
rptview(doc2);

The document author displays a link to the embedded document.

To open the embedded document, open author/root.html outside of MATLAB.

Alternative Functionality

`mlreportgen.dom.DOCXSubDoc`

To insert Word documents into another document, you can use objects of the DOCXSubDoc or EmbeddedObject class. To decide which class to use, consider these guidelines:

Use DOCXSubDoc objects if you want the parent document to display links to subdocuments initially. You might want to display links initially when the parent document links to a set of subdocuments in an outline view. Use EmbeddedObject objects if you want the parent document to display the subdocument contents regardless of whether you open the parent document in Word or by using rptview.
Use EmbeddedObject objects if you want to move the parent document without moving the subdocuments.

Version History

Introduced in R2020a

expand all

R2020b: Appearance of link to embedded file in a PDF report

Starting in R2020b, if you use mlreportgen.dom.EmbeddedObject to embed a file in a PDF report, the link to the embedded file is inserted into the PDF as an annotation that has a paper clip icon. For example:

To open the embedded file, double-click the paper clip icon. In previous releases, a hyperlink to the embedded file was inserted into the PDF. For example:

mlreportgen.dom.EmbeddedObject Class