ImportPackage Command

---

ImportPackage requires APL 2024.3 or later. Provide an alternate experience for devices running older versions of APL.

Imports an Alexa Presentation Language (APL) package and its dependencies into the current document and then run commands after the package has been imported.

Properties

The ImportPackage command has the following properties in addition to the standard command properties:

Property	Type	Default	Description
accept	String	version	Package accept property.
name	String	REQUIRED	Package name property.
onFail	Array of Commands	[]	Commands to run if the package fails to load.
onLoad	Array of Commands	[]	Commands to run if the package loads.
source	String	""	Optional package source property.
version	String	REQUIRED	Package version property.

The accept, name, version, and source properties use the definitions provided in Package reference.

The following example shows a command to import a package called FishFeeder.

{
  "type": "ImportPackage",
  "name": "FishFeeder",
  "version": "1.2.0",
  "accept": ">=1.2 <2",
  "onLoad": [ <COMMANDS_TO_RUN> ],
  "onFail": [ <COMMANDS_TO_RUN> ]
}

The ImportPackage command is ignored in fast mode.

onFail

An array of commands to run if the package or any dependent packages fail to load. Packages are never reloaded. If a package failed to load in the past the onFail event handler is immediately invoked.

The event generated has the following form.

"event" {
  "source": {
    "type": COMPONENT_TYPE,  // The type of the component (e.g., "TouchWrapper")
    "handler": "Fail",
    ...                      // Component source properties
  },
  "value": STRING,           // The name, version, and URL of the package that faiiled to load
  "error": STRING,           // The reason of the failure
  "errorCode": NUMBER        // Error identifier
}

The value, error, and errorCode reported in the event are provided for debugging. Don't show these values to the customer.

Refer to Event source for a description of event.source properties.

The onFail event handler runs in fast mode.

onLoad

An array of commands to run when the package and all dependent packages have loaded. If the packages have already been loaded into the document this command runs immediately.

The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE,  // The type of the component (e.g., "TouchWrapper")
    "handler": "Load",
    ...                      // Component source properties
  },
  "version": STRING,         // The version of the loaded package
}

The version property is the version of the package that was loaded.

Refer to Event source for a description of event.source properties.

The onLoad event handler runs in fast mode.

ImportPackage command and the document import property

The imported package can contain the document import property, which identifies additional packages to load. Alexa doesn't load packages more than one time. If a package has already been loaded, that package is ignored. A package is defined by its name and version tuple. Therefore, the following two packages are not the same:

• {"name": "A", "version": "1.1.0"}
• {"name": "A", "version": "1.1.1"} (The version number is different).

If you request the 1.1.1 version of A after the 1.1.0 version has loaded, the 1.1.1 version does load and overrides the 1.1.0 version.

After the package has been loaded and all internally referenced packages have been loaded, the commands, graphics, layouts, resources, and styles are processed and added to the core document context. The onLoad commands run after processing. If any package fails to load, the onFail commands run.

The following properties are read from the imported package:

• type: Must be APL
• version: Must be a supported APL version
• commands
• graphics
• import
• layouts
• resources
• styles

The Reinflate command doesn't save imported packages. The document reloads without the packages that were previously loaded with the ImportPackage command.

Examples

You can use the ImportPackage command to delay loading lower-priority packages, but still minimize the time to display elements that rely on those packages.

The following example uses the document onMount event handler to start a background load of the "FishGraphics" package. Later in the document, when the user presses a button, the document uses ImportPackage to import the FishGraphics package. The onLoad event handler then displays the graphic from the package. If the FishGraphics package has already been loaded, the onLoad handler runs immediately and therefore the SetValue command immediately displays the graphic. If FishGraphics hasn't finished loading, the onLoad handler runs after the package has loaded. This ensures that the package is available before attempting to display the graphic.

Another common use is a list of items where the items in the list should be displayed immediately as a placeholder until the actual item loads. The following example places a blank Frame component in the list. The actual item to display inflates into the Frame after the package has loaded.

The following example shows a generic package loader that inspects the object to be inserted and determines if it depends on a package.

In this example the PackageWrapper layout checks to see if the PACKAGE_NAME property has been defined. If it has, it treats that as the package name and creates a Frame with an onMount event handler that loads the requested package and then inserts the item as a component. If the PACKAGE_NAME property isn't defined, the wrapper includes the item.

Related topics

• APL Package
• InsertItem Command

---

---

Last updated: ...