Working with OLE Objects and Online Video

OLE (Object Linking and Embedding) is a technology by which users can work with documents containing “objects” created or edited by third-party applications. That is, OLE allows an editing application to export these “objects” to another editing application and then import them with additional content.

In this article, we will talk about inserting an OLE object and setting its properties, as well as inserting an online video into a document.

Insert OLE Object

If you want OLE Object, call the insert_ole_object method and pass it the ProgId explicitly with other parameters.

The following code example shows how to insert OLE Object into a document:

Set File Name and Extension when Inserting OLE Object

OLE package is a legacy and “undocumented” way to store embedded objects if an OLE handler is unknown.

Early Windows versions such as Windows 3.1, 95, and 98 had a Packager.exe application that could be used to embed any type of data into the document. This application is now excluded from Windows, but Microsoft Word and other applications still use it to embed data if the OLE handler is missing or unknown. The OlePackage class allows users to access the OLE Package properties.

The following code example shows how to set the file name, extension, and display name for OLE Package:

Get Access to OLE Object Raw Data

Users can access OLE object data using various properties and methods of the OleFormat class. For example, it is possible to get the OLE object raw data or the path and name of a source file for the linked OLE object.

The following code example shows how to get OLE Object raw data using the get_raw_data method:

Insert OLE Object as an Icon

OLE objects can also be inserted into documents as images.

The following code example shows how to insert OLE Object as an icon. For this purpose, the DocumentBuilder class exposes the insert_ole_object_as_icon method:

The following code example shows how to inserts an embedded OLE object as an icon from a stream into the document:

Insert Online Video

Online video can be inserted into Word document from the “Insert” > “Online Video” tab. You can insert an online video into a document at the current location by calling the insert_online_video method.

The DocumentBuilder class introduces four overloads of this method. The first one works with the most popular video resources and takes the URL of the video as a parameter. For example, the first overload supports simple insertion of online videos from YouTube and Vimeo resources.

The following code example shows how to insert an online video from Vimeo into a document:

doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# Pass direct url from youtu.be.
url = "https://www.youtube.com/watch?v=t_1LYZ102RA"

width = 360
height = 270

shape = builder.insert_online_video(url, width, height)

doc.save(docs_base.artifacts_dir + "WorkingWithOleObjectsAndActiveX.insert_online_video.docx")

The second overload works with all other video resources and takes embedded HTML code as a parameter. The HTML code for embedding a video may vary depending on the provider, so contact the respective provider for details.

Please note that the document will be automatically optimized for MS Word 2013 to show video.

The following code example shows how to insert an online video into a document using such HTML code:

doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# Shape width/height.
width = 360
height = 270

# Poster frame image.
f = open(docs_base.images_dir + "Logo.jpg", "rb")
imageBytes = f.read()
f.close()

# Visible url
vimeoVideoUrl = "https://vimeo.com/52477838"

# Embed Html code.
vimeoEmbedCode = ""

builder.insert_online_video(vimeoVideoUrl, vimeoEmbedCode, imageBytes, width, height)

doc.save(docs_base.artifacts_dir + "WorkingWithOleObjectsAndActiveX.insert_online_video_with_embed_html.docx")

FAQ

Q: How can I insert an OLE object as an icon instead of displaying its full content?
A: Use DocumentBuilder.insert_ole_object_as_icon. Provide the OLE object’s ProgId (or stream), the icon image (optional), and set the display_as_icon flag to True. The method creates an Shape that represents the icon in the document.
Q: I need to set a custom file name and extension for an OLE package that has no native handler. How is this done?
A: Create an OlePackage instance, set its file_name, file_extension, and display_name properties, then pass the package to DocumentBuilder.insert_ole_object. This embeds the data with the specified metadata, allowing Word to recognize the file type.
Q: How can I retrieve the raw binary data of an embedded OLE object?
A: Access the OleFormat of the shape that contains the OLE object and call OleFormat.get_raw_data(). The method returns a bytes array containing the original embedded file data.
Q: Which video platforms are supported by the simple insert_online_video(url, width, height) overload?
A: The overload works directly with YouTube and Vimeo URLs. For other platforms you must use the overload that accepts embedded HTML code, providing the HTML snippet and an optional poster image.
Q: My inserted online video does not display in Word 2013. What should I check?
A: Ensure the document is saved after insertion; Word 2013 automatically optimizes the document for online video. Also verify that the video URL is reachable and that the width/height parameters are set to reasonable values (e.g., 360 × 270).

Working with Watermark in Python Working with Fields in Python