addOnUISdk.app.document

Provides access to the methods needed for retrieving document metadata, importing content such as images, audio and video into the document, and for exporting content from the current document.

General Methods

id()

Retrieves the id of the document.

Signature

id(): Promise<string | undefined>

Return Value

A resolved Promise containing the id of the document.

Example

Copy
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setId(id) { /* ... */ } 
  
addOnUISdk.ready.then(() => setId(await addOnUISdk.app.document.id()));
  
addOnUISdk.app.on("documentAvailable", data => {
  setId(data.documentId);
});
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setId(id) { /* ... */ } 
  
addOnUISdk.ready.then(() => setId(await addOnUISdk.app.document.id()));
  
addOnUISdk.app.on("documentAvailable", data => {
  setId(data.documentId);
});

title()

Retrieves the title/name of the document.

Signature

title(): Promise<string>

Return Value

A resolved Promise containing the title (ie: name) of the document.

Example

Copy
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setTitle(title) { /* ... */ } 
  
addOnUISdk.ready.then(() => setTitle(await addOnUISdk.app.document.title()));
  
addOnUISdk.app.on("documentTitleChange", data => {
  setTitle(data.documentTitle);
});
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

function setTitle(title) { /* ... */ } 
  
addOnUISdk.ready.then(() => setTitle(await addOnUISdk.app.document.title()));
  
addOnUISdk.app.on("documentTitleChange", data => {
  setTitle(data.documentTitle);
});

getPagesMetadata()

Retrieve the metadata for all of the pages in the document.

Signature

getPagesMetadata(options: PageMetadataOptions): Promise<PageMetadata[]>

Parameters

Return Value

A resolved Promise containing a PageMetadata array containing all of the pages in the document.

Copy
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;
 
// Get metadata of all the pages
async function logMetadata() {
  try {
    const pages = (await addOnUISdk.app.document.getPagesMetadata({
                            range: addOnUISdk.constants.Range.specificPages,
                            pageIds: [
                                "7477a5e7-02b2-4b8d-9bf9-f09ef6f8b9fc",
                                "d45ba3fc-a3df-4a87-80a5-655e5f8f0f96"
                            ]
                        })) as PageMetadata[];
    for (const page of pages) {
      console.log("Page id: ", page.id);
      console.log("Page title: ", page.title);
      console.log("Page size: ", page.size);
      console.log("Page has premium content: ", page.hasPremiumContent);
      console.log("Page has timelines: ", page.hasTemporalContent);
      console.log("Pixels per inch: ", page.pixelsPerInch);
      console.log("Is page print ready: ", page.isPrintReady);
    }
  }
  catch(error) {
    console.log("Failed to get metadata:", error);
  }
}
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;
 
// Get metadata of all the pages
async function logMetadata() {
  try {
    const pages = (await addOnUISdk.app.document.getPagesMetadata({
                            range: addOnUISdk.constants.Range.specificPages,
                            pageIds: [
                                "7477a5e7-02b2-4b8d-9bf9-f09ef6f8b9fc",
                                "d45ba3fc-a3df-4a87-80a5-655e5f8f0f96"
                            ]
                        })) as PageMetadata[];
    for (const page of pages) {
      console.log("Page id: ", page.id);
      console.log("Page title: ", page.title);
      console.log("Page size: ", page.size);
      console.log("Page has premium content: ", page.hasPremiumContent);
      console.log("Page has timelines: ", page.hasTemporalContent);
      console.log("Pixels per inch: ", page.pixelsPerInch);
      console.log("Is page print ready: ", page.isPrintReady);
    }
  }
  catch(error) {
    console.log("Failed to get metadata:", error);
  }
}

PageMetadata

The metadata of a page.

PageMetadataOptions

This object is passed as a parameter to the getPagesMetadata method and includes the range and optional pageIds for which you want to retrieve metadata for.

Import Content Methods

addImage()

Adds an image (including gif/Ps/Ai files) to the current page.

Signature

addImage(imageBlob: Blob, attributes?: MediaAttributes): Promise<void>

Parameters

MediaAttributes

Return Value

A resolved promise if the image was successfully added to the canvas; otherwise, it will throw an error with the rejected promise.

Example Usage

Copy
// Add image(blob) to the current page
async function addImageFromBlob(blob) {
  try {
      await document.addImage(blob);
  }
  catch(error) {
      console.log("Failed to add the image to the page.");
  }
}

// Add image(url) to the current page
async function addImageFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addImage(blob);
  }
  catch(error) {
      console.log("Failed to add the image to the page.");
  }
}
Copied to your clipboard
// Add image(blob) to the current page
async function addImageFromBlob(blob) {
  try {
      await document.addImage(blob);
  }
  catch(error) {
      console.log("Failed to add the image to the page.");
  }
}

// Add image(url) to the current page
async function addImageFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addImage(blob);
  }
  catch(error) {
      console.log("Failed to add the image to the page.");
  }
}

addVideo()

Adds a video to the current page.

Signature

addVideo(videoBlob: Blob): Promise<void>

Parameters

Example Usage

Copy
async function addVideoFromBlob(blob) {
  try {
      await document.addVideo(blob);
  }
  catch(error) {
      console.log("Failed to add the video to the page.");
  }
}

async function addVideoFromURL(url) {
  try {
     const blob = await fetch(url).then(response => response.blob());
     await document.addVideo(blob);
  }
  catch(error) {
    console.log("Failed to add the video to the page.");
  }
}
Copied to your clipboard
async function addVideoFromBlob(blob) {
  try {
      await document.addVideo(blob);
  }
  catch(error) {
      console.log("Failed to add the video to the page.");
  }
}

async function addVideoFromURL(url) {
  try {
     const blob = await fetch(url).then(response => response.blob());
     await document.addVideo(blob);
  }
  catch(error) {
    console.log("Failed to add the video to the page.");
  }
}

addAudio()

Adds audio to the current page.

Signature

addAudio(audioBlob: Blob, attributes: MediaAttributes): Promise<void>

Parameters

MediaAttributes

Return Value

A resolved promise if the audio was successfully added to the canvas; otherwise will throw an error with the rejected promise.

Example Usage

Copy
async function addAudioFromBlob(blob) {
  try {
      await document.addAudio(blob, {title: "Jazzy beats"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
}

async function addAudioFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addAudio(blob, {title: "Jazzy beats"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
Copied to your clipboard
async function addAudioFromBlob(blob) {
  try {
      await document.addAudio(blob, {title: "Jazzy beats"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
}

async function addAudioFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addAudio(blob, {title: "Jazzy beats"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }

Errors

The table below describes the possible error messages that may occur when using the import methods, with a description of the scenario that would cause them to be returned.

Export Content Methods

createRenditions()

Generate renditions of the current page, specific pages or the entire document in a specified format for export.

Signature

createRenditions(renditionOptions: RenditionOptions, renditionIntent?: RenditionIntent): Promise<Rendition[]>

Parameters

NOTE: The default value for renditionIntent is export. If it's set to preview, it also requires the renditionPreview flag to be set to true in the manifest requirements section. Additionally, when implementing the premium content flows where you present a dialog or option to allow the user to upgrade, you must be sure to also include the following permissions in the sandbox attribute of your manifest.json to allow the Adobe Express pricing page to load properly:

Copy
"permissions": {
    "sandbox": ["allow-popups-to-escape-sandbox", "allow-popups", "allow-downloads"]
}
Copied to your clipboard
"permissions": {
    "sandbox": ["allow-popups-to-escape-sandbox", "allow-popups", "allow-downloads"]
}

Refer to the exporting content use case example for more specific details on options for handling the export of premium content.

RenditionOptions

JpgRenditionOptions

Extends the RenditionOptions object and adds the following additional options for jpg renditions:

PngRenditionOptions

Extends the RenditionOptions object and adds the following additional options for png renditions:

Requested Size Notes

• The supported size is from 1 x 1 to width x height.
• Aspect ratio is maintained while scaling the rendition based on the requested size.
• Up-scaling is currently not supported.
• If the requested size is invalid, it will be ignored and the original size rendition will be created.
• Some examples of what the actual exported sizes will be, depending on the page size and requested size are in the table below for reference.

PdfRenditionOptions

Extends the RenditionOptions object and adds the following additional options for pdf renditions:

Bleed

Represents a bleed for a page. In printing, bleed is printing that goes beyond the edge of where the sheet will be trimmed. In other words, the bleed is the area to be trimmed off. If the value is left undefined, then no bleed will be assumed.

PdfPageBoxes

Represents all of the PDF page boxes (MediaBox, BleedBox, CropBox, TrimBox).

PdfPageBox

Represents a PDF page box.

PdfPageBoxMargins

Represents margins for a PDF page box.

Mp4RenditionOptions

Extends the RenditionOptions object and adds the following additional options for mp4 renditions:

Return Value

A Promise with an array of page Rendition objects (see PageRendition). The array will contain one item if the currentPage range is requested, an array of specific pages when the specificPages range is requested, or all pages when the entireDocument range is specified. Each rendition returned will contain the type, title,metadata for the page and a blob of the rendition itself. Note: If you requested PDF for the format with a larger range than currentPage, a single file will be generated which includes the entire range. When the format is JPG/PNG/MP4, an array of files will be generated that represents each page.

Copy
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7FAA77FF
    };
    const renditions = await addOnUISdk.app.document.createRenditions(renditionOptions, addOnUISdk.constants.RenditionIntent.preview);
    renditions.forEach(rendition => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  }
  catch(error) {
    console.log("Failed to create renditions:", error);
  }
}
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7FAA77FF
    };
    const renditions = await addOnUISdk.app.document.createRenditions(renditionOptions, addOnUISdk.constants.RenditionIntent.preview);
    renditions.forEach(rendition => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  }
  catch(error) {
    console.log("Failed to create renditions:", error);
  }
}

Copy
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;
  
// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions: PngRenditionOptions = {
      range: Range.entireDocument,
      format: RenditionFormat.png,
      backgroundColor: 0x7FAA77FF
    };
    const renditions = await addOnUISdk.app.document.createRenditions(renditionOptions, RenditionIntent.preview);
    renditions.forEach(rendition => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  }
  catch(error) {
    console.log("Failed to create renditions:", error);
  }
}
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;
  
// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions: PngRenditionOptions = {
      range: Range.entireDocument,
      format: RenditionFormat.png,
      backgroundColor: 0x7FAA77FF
    };
    const renditions = await addOnUISdk.app.document.createRenditions(renditionOptions, RenditionIntent.preview);
    renditions.forEach(rendition => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  }
  catch(error) {
    console.log("Failed to create renditions:", error);
  }
}

Rendition

A rendition object representing a page in the document, returned from createRenditions. See

PageRendition

An extension of Rendition, returned in the response to createRenditions. This object includes everything in Rendition, as well as:

Errors

The table below describes the possible error messages that may occur when using the export methods, with a description of the scenario that will return them.

Last updated 3/20/2024

Was this helpful?

Yes

No