Main Content

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 TypeExternal File TypeBehavior
Wordxlsx, 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.

WordAny type except xlsx, pptx, or docx

Does not embed the file in the document. Inserts a hyperlink to the external file.

PDFAny

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.

HTMLAny

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 HTMLAny

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.

example

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.

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 of the file to embed, specified as a character vector or 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.

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

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

Properties

expand all

Path of the file to embed in the document, specified as a character vector or 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.

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.

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 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 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 for 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

Object identifier for 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

Examples

collapse all

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.

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.

The link text is "Author Biography". The link and text are green.

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