User Guide Cancel

Creating custom HTML5 Components

Search
Animate

Animate

Open app
  1. Adobe Animate User Guide
  2. Introduction to Animate
    1. What's New in Animate
    2. Visual Glossary
    3. Animate system requirements
    4. Animate keyboard shortcuts
    5. Work with Multiple File Types in Animate
  3. Animation
    1. Animation basics in Animate
    2. How to use frames and keyframes in Animate
    3. Frame-by-frame animation in Animate
    4. How to work with classic tween animation in Animate
    5. Brush Tool
    6. Motion Guide
    7. Motion tween and ActionScript 3.0
    8. About Motion Tween Animation
    9. Motion tween animations
    10. Creating a Motion tween animation
    11. Using property keyframes
    12. Animate position with a tween
    13. How to edit motion tweens using Motion Editor
    14. Editing the motion path of a tween animation
    15. Manipulating motion tweens
    16. Adding custom eases
    17. Creating and applying Motion presets
    18. Setting up animation tween spans
    19. Working with Motion tweens saved as XML files
    20. Motion tweens vs Classic tweens
    21. Shape tweening
    22. Using Bone tool animation in Animate
    23. Work with character rigging in Animate
    24. How to use mask layers in Adobe Animate
    25. How to work with scenes in Animate
  4. Interactivity
    1. How to create buttons with Animate
    2. Convert Animate projects to other document type formats
    3. Create and publish HTML5 Canvas documents in Animate
    4. Add interactivity with code snippets in Animate
    5. Creating custom HTML5 Components
    6. Using Components in HTML5 Canvas
    7. Creating custom Components: Examples
    8. Code Snippets for custom Components
    9. Best practices - Advertising with Animate
    10. Virtual Reality authoring and publishing
  5. Workspace and workflow
    1. Creating and managing Paint brushes
    2. Using Google fonts in HTML5 Canvas documents
    3. Using Creative Cloud Libraries and Adobe Animate
    4. Use the Stage and Tools panel for Animate
    5. Animate workflow and workspace
    6. Using web fonts in HTML5 Canvas documents
    7. Timelines and ActionScript
    8. Working with multiple timelines
    9. Set preferences
    10. Using Animate authoring panels
    11. Create timeline layers with Animate
    12. Export animations for mobile apps and game engines
    13. Moving and copying objects
    14. Templates
    15. Find and Replace in Animate
    16. Undo, redo, and the History panel
    17. Keyboard shortcuts
    18. How to use the timeline in Animate
    19. Creating HTML extensions
    20. Optimization options for Images and Animated GIFs
    21. Export settings for Images and GIFs
    22. Assets Panel in Animate
  6. Multimedia and Video
    1. Transforming and combining graphic objects in Animate
    2. Creating and working with symbol instances in Animate
    3. Image Trace
    4. How to use sound in Adobe Animate
    5. Exporting SVG files
    6. Create video files for use in Animate
    7. How to add a video in Animate
    8. Draw and create objects with Animate
    9. Reshape lines and shapes
    10. Strokes, fills, and gradients with Animate CC
    11. Working with Adobe Premiere Pro and After Effects
    12. Color Panels in Animate CC
    13. Opening Flash CS6 files with Animate
    14. Work with classic text in Animate
    15. Placing artwork into Animate
    16. Imported bitmaps in Animate
    17. 3D graphics
    18. Working with symbols in Animate
    19. Draw lines & shapes with Adobe Animate
    20. Work with the libraries in Animate
    21. Exporting Sounds
    22. Selecting objects in Animate CC
    23. Working with Illustrator AI files in Animate
    24. Applying blend modes
    25. Arranging objects
    26. Automating tasks with the Commands menu
    27. Multilanguage text
    28. Using camera in Animate
    29. Graphic filters
    30. Sound and ActionScript
    31. Drawing preferences
    32. Drawing with the Pen tool
  7. Platforms
    1. Convert Animate projects to other document type formats
    2. Custom Platform Support
    3. Create and publish HTML5 Canvas documents in Animate
    4. Creating and publishing a WebGL document
    5. How to package applications for AIR for iOS
    6. Publishing AIR for Android applications
    7. Publishing for Adobe AIR for desktop
    8. ActionScript publish settings
    9. Best practices - Organizing ActionScript in an application
    10. How to use ActionScript with Animate
    11. Accessibility in the Animate workspace
    12. Writing and managing scripts
    13. Enabling Support for Custom Platforms
    14. Custom Platform Support Overview
    15. Working with Custom Platform Support Plug-in
    16. Debugging ActionScript 3.0
    17. Enabling Support for Custom Platforms
  8. Exporting and Publishing
    1. How to export files from Animate CC
    2. OAM publishing
    3. Exporting SVG files
    4. Export graphics and videos with Animate
    5. Publishing AS3 documents
    6. Export animations for mobile apps and game engines
    7. Exporting Sounds
    8. Best practices - Tips for creating content for mobile devices
    9. Best practices - Video conventions
    10. Best practices - SWF application authoring guidelines
    11. Best practices - Structuring FLA files
    12. Best Practices to optimize FLA files for Animate
    13. ActionScript publish settings
    14. Specify publish settings for Animate
    15. Exporting projector files
    16. Export Images and Animated GIFs
    17. HTML publishing templates
    18. Working with Adobe Premiere Pro and After Effects
    19. Quick share and publish your animations
  9. Troubleshooting
    1. Fixed issues
    2. Known issues

 

Use this article to learn how to create custom components for HTML5 canvas.

Animate ships with a set of default components. However, these are insufficient for your project. This topic helps you understand how to create custom HTML5 Components for Animate.

A component definition consists of three major parts:

  • Metadata: Provides information about the component such as display name, version, set of configurable properties, icon, and so on. This is captured in a file called components.js. You can group the components as a category and  this file allows you to provide the meta-data for all components in a category.
  • Source: Provides information about the actual component source. This is embedded at runtime when you preview or publish a movie using components.
  • Assets: Provides information about any runtime dependency such as like JavaScript library or CSS or runtime assets and icons. The assets can be used in the Animate authoring environment.

 A component definition also has localization-related resources.

Sample folder configuration for a custom component category

Animate checks the following folders for any custom HTML5 Components and loads them on launch:

• Windows:

<AppData>/Local/Adobe/Adobe Animate 2017/en_US/Configuration/HTML5Components

 

• MAC:

~/Library/Application Support/Adobe/Animate 2017/en_US/Configuration/HTML5Components/

 The above folder path is applicable for US English. If you are using Animate in any other language, look for your language specific folder name replacing en_US.

For each folder within the location that contains the file ‘components.js’, Animate creates a category, and loads all the components within.

Component Metadata

The metadata of the Component is captured in a file called components.js which is placed inside a separate folder within HTML5Components directory. 

Sample metadata for a video component.

Components.js

Components.js

is a JSON file that contains the following sections:

  • Category: Name in the Components Panel for this set of components and can be localized.
  • Components: Array where each entry contains the metadata about a component. The above sample has only one element in the array. The metadata has following sections:

Name

Required

Description

ClassName

Yes

Class name of the component specified in the source file. The class name supports one level of namespaces. For example, Video.

 

Version

No

Version number of the component. This is used for future component upgrades. However, the flow is not defined at this point of time.

Source

Yes

Relative path of the component’s main source file. More details are provided on what does the source contain in the next section.

Icon

No

Relative path for the icon for the component. This icon is used in the components panel and on stage when any instance is created for the component along with its name. If none is provided a default icon will be used.

You can specify the png name of the icon to be loaded (typically 32x32). Or else, if you want to support different icons for light UI and dark UI then provide two .pngs with the following naming convention:

custom_icon_N.png – Icon for dark UI

custom_icon_D.png – Icon for light UI

and just specify the name ‘custom_icon’ as the value for this field. The suffixes are automatically appended based on the current user setting.

Dimensions

No

Default size for the component instances. Whenever user drags and drops a component from Component panel to stage, a new instance is created. This field specifies the default initial size for the component instance. The value should be an array [width, height]. If there is no value specified, then Animate picks up a default size. Also Animate restricts the size to be within [2,2] to [1000, 1000] range.

Dependencies

No

The set of dependencies for the component. This is an array where each entry provides the relative path for a local source (with key = “src”) and CDN path (with key=’cdn’). The CDN path is not mandatory. This path is used when you use hosted libraries in the publish settings. Otherwise the local source will be used when you preview or publish.

Do note the relative path used in the example above (video). Its loading the dependencies from one level above, which allows us to share some dependencies across multiple component sets.

Properties

Yes

This is an array of properties. When you create any instance of this component on stage, the set of properties configured here will be automatically shown in the PI. Users of this component can configure those properties in Animate and the configured properties are made available during instantiation of the component at runtime.

Each property entry contains the following keys:

  1. name: The name shown in the PI for this property. This should be a user-friendly name. This can be localized.
  2. variable: The internal name used for this property. The configured values will be available with this variable name at runtime. More details on this will be covered in later sections.
  3. Type: This specified the type of the property. Animate allows the following types:
    1. Boolean  - Checkbox in PI
    2. Number  - Numeric box in PI
    3. String    - Text box in PI
    4. List        - Allows user to configure an array of values.
    5. Collection- Allows the users to configure a list of <key, value> pairs. (See combo box)
    6. File Path  - Allows the user to browse and select any local file. The string value is supplied at runtime. The file is automatically copied in the published output in ‘assets’ folder and the relative path is made available at runtime.
    7. Image Path - Allows the user to browse and select any image. The file is automatically copied in the published output in the configured images folder and the relative path is made available at runtime.
    8. Video Content Path – Allows the user to browse and select any web format video source (mp4, ogg , ogv , webm ). The configured asset is copied to ‘videos’ folder in the published output.
    9. Color - Color Picker in PI
  4. Default: Default value of the property. The default should be of same type as the type of the property.

Component Source

Each component should have a source file associated which provides code to handle the following:

  • Creation of component instance at runtime with configured set of property values
  • Attaching and Detaching to the DOM.
  • Property updates in every frame

A base class is provided and a utility function in the file anwidget.js for easier development of custom components. This interface will be enhanced in future but will be backward compatible. Currently only DOM- based components are supported; however support for canvas based components will be extended. Currently only widgets are supported; however, the framework will be enhanced to support attaching behaviors (non-ui components).

The file anwidget.js  is present under HTML5Components/sdk folder in your first run folder. It provides a base class AnWidget for custom components and a utility method $.anwidget(<className>, {Object Prototype}) for registering a custom component. The current implementation uses jQuery, so jQuery is always added as a dependency whenever you use the services provided by a widget. However, if you do not want to add an implicit dependency on jQuery, then you may need to implement a Component class without jQuery which provides the same interface as a Widget.

 

HTML template

The html contains these sections (excluding the preloader div) by default:

Default HTML sections (excluding the preloader div)

Do note that the previous figure illustrates the order in which the elements are added in the DOM. Thus the dom_overlay_container div is shown above the canvas.

 Do not change the ID of the dom_overlay_container div as in our first release, there are a couple of features which depend on this ID like code snippets.

As shown in the previous illustration, the dom_overlay_container div is shown on top of the canvas as an overlay. To make sure that the mouse events are propagated properly to the underlying canvas too, we use the CSS property {pointer-events: none} for this div so that mouse events are propagated to the underlying canvas. All the component instances which are configured in Animate in your project are instantiated and attached as a child of this dom_overlay_container div. The relative ordering of the component instances are maintained at runtime, but currently all the component instances are always shown as an overlay. We set {pointer-events: all} for all the component instances at runtime so that they also receive the mouse events.

Component lifecycle

Component lifecycle

  1. The component instance is created when the DOM is being constructed for the container.

  2. The instance is then attached to the DOM when the playhead reaches the frame where the component instance is used. It then attaches an update handler which is called on every tick at runtime. The component also fires an event ‘attached’ at this time with the following event data {id: id_of_the_instance} on the parent element.

  3. The Properties are updated in every update callback. All the property updates are cached and applied once during a tick handler. Currently custom property tweens are not supported. Only the basic properties such as transform and visibility are updated.

  4. When the playhead reaches a frame where component instance is removed, we detach it from the DOM. A ‘detached’ event is fired this time on the parent element.

The base class is called $.AnWidget and provides the following overrides:

Name

Mandatory

Description

getCreateOptions()

No

Returns any options which the component wants to be applied during component instantiation. A typical override generally uses this to assign a unique ID to every instance by making use of the global variable _widgetID. The example in the next section will make its usage clear.

getCreateString()

Yes

Return the string for your DOM instance creation. This string is passed to jQuery to create the actual DOM element which is attached later to the base DOM.

 

For example, for an image component this should return “<image>”.

 

At runtime the element is created and the reference to the jQuery wrapper is stored as follows in the component instance:

 

this._element =  $(this.getCreateElement())

 

// this._element – jQuery wrapper for the underlying DOM element created.

 

We can also create composite elements; the details will be covered in an examples section.

getProperties()

No

Returns an array of configurable CSS property names. Typically, this matches with all the properties you configured in components.json

 

For example, for the video component this array contains the following entries:

 

["left", "top", "width", "height", "position", "transform-origin", "transform"]

getAttributes()

No

Returns an array of configurable attributes. Typically, this matches with all the attributes that you are permitted to configure in components.json

 

For example, for the video component this array contains the following entries:

 

["id", "src", "controls", "autoplay", "loop", "class"]

attach(parent)

No

This function is called whenever the component instance is about to be attached to the ‘parent’ DOM element.

 

The default implementation does the following (and some more stuff):

 

// Appends the element to the parent DOM

$(parent).append(this._element);

 

//Stores the ref in this._$this

this._$this = $(this._element);

 

//Calls force update to apply all properties

this.update(true);

this._attached = true;

 

//Triggers the attached event on parent

$(parent).trigger("attached", this.getEventData("attached"))

 

You do not need to override this function. However, for composite elements we may need to override it. More details will be covered in the examples section.

 

Note: You can use this._superApply(arguments) to call any base class method from any override.

detach()

No

This function is called whenever the component instance is about to be removed from the DOM. The default implementation does the following:

 

//Removes the element from the DOM

this._$this.remove();

//Triggers the detached event on parent

$(parent).trigger("detached", this.getEventData("detached"));

setProperty(k,v)

No

This function is used to set any property for the instance. These changes are cached and are applied at once during the call to update() every frame for every property which is dirty.

update(force)

No

This function is called every frame when the component is part of DOM and is visible. The default implementation applies all the CSS properties and attributes which have changed or if force parameter is true.

show()

No

Shows the element instance. You typically don’t need to override this, but for composite elements you may need to.

hide()

No

Hides the element instance. You typically don’t need to override this, but for composite elements you may need to.

getEventData(e)

No

Returns any custom data for the event with name ‘e’. The default implementation passes the data {id: instance_id} for attached and detached events.

destroy()

No

Frees the memory when the component instance is detached from DOM. You typically don’t need to override this.

applyProperties(e)

No

Helper API for applying the CSS properties to the jQuery wrapper e.

applyAttributes(e)

No

Helper API for applying the attributes to the jQuery wrapper e.

Localization

The category string, component display name and property name can be localized. Create a file called strings.json in a folder with the name locale under the components folder. Provide the key-value pairs for all the strings to be localized and use the key in the components.js. For other locales, you need to provide the strings in the corresponding folders under the locale folder.

.json string

Package and distribute custom HTML5 components

Animate developers or designers can enable animators to install and use components without coding, by providing ready-to-use packaged components. Previously, animators had to learn file structures, do programming, and manually move the files to specific folders to activate the HTML5 extensions.

Prerequisites

  • Any component created by a developer. Click here for instructions on creating components.
  • CC Extensions signing toolkit.

Before packaging your component, create an MXI file with the metadata of source and destination path of components. For example,

<file source="jquery-ui-1.12.0" destination="$FLASH\HTML5Components\jQueryUI\" file-type="ordinary" />

This source and destination file information is required to enable extensions utility for accurate installation of your component.

Packaging components

To package the HTML5 custom components, perform the following steps: 

  1. To create an MXI file, enter the content similar to the sample  abc.mxi  file using a text editor and save it with an MXI extension.

    Download

    Get file
    Download a sample abc.mxi file.

  2. Add your MXI component file and other associated files in a folder.

  3. Create a ZXP extension zip file by using the CC Extensions signing tool (ZXPSignCmd.exe). Use the following commands in ZXP Sign Command tool to create a ZXP file:

    1. Create a self-signed certificate by using the -selfSignedCert option.

    You can skip this step if you already have a certificate.

    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12

    FileName.p12 file is generated in the current folder.

    2. Sign the extension using the following command: 

    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    projectName is the name of the Extension Project. In the current folder, a file with the name projectName.zxp is generated.

Distribute components

You can distribute this projectName.zxp packaged component file to any of the Animate users.

 Adobe recommends that you distribute your products through the Adobe Add-ons website. You can distribute add-ons publicly (free or paid) or privately (free to named users).

Install distributed components

Animate designers or developers can install the distributed ZXP file component by using the Manage Extensions utility.

More like this

 Adobe

Get help faster and easier

New user?

Quick links

View all your plans Manage your plans
View quick links
Hide quick links
Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Register Now

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Register Now
Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Register Now

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Register Now

Legal Notices    |    Online Privacy Policy