mlreportgen.dom.EmbeddedObject class

Package: mlreportgen.dom
Superclasses: mlreportgen.dom.ExternalLink

Embed a file in a document

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 a link, specified as a cell array of mlreportgen.dom.CustomAttribute objects. The output format must support the custom attributes. The CustomAttributes property applies only when the reference to a file is a hyperlink.

Parent of this document element, specified as a DOM object. This property is read-only.

Children of this document element, specified as an array of DOM objects. This property is read-only.

Tag for this document element, specified as a character vector or string scalar.

The DOM 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. Specifying your own tag value can help you to identify where an issue occurred during document generation.

ID for this document element, specified as a character vector or string scalar. The DOM generates a session-unique ID when it creates the document element. You can specify your own ID.

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.

Compatibility Considerations

expand all

Behavior changed in R2020b

Introduced in R2020a