User Guide Cancel

Creating custom Components: Examples

Last updated on May 24, 2023

Use this article to understand a sample HTML5 custom component.

This article describes how to create custom components. The first example describes the image component (which is also supplied with Animate) and the process to understand the framework and the steps involved in development. The second example describes how to wrap any existing UI component (like jQueryUI) and import it within Animate.

Creating a DOM image component

Create a category called My Components.

a. Create a folder called mycomponents under <HTML5Components> folder in first run

b. Download the attached myimage.zip file and extract the contents under the

mycomponents folder.

Download

Get file
Click here to download myimage.zip file.

c. Restart Animate.

Directory structure within mycomponents folder

You should now see a new category called “My Components” in components folder and a new component called My Image under it. You can drag-and-drop this on stage, set the image source property and publish the movie to see the custom component in action.

Component Metadata - components.js

Please note that the category is set to CATEGORY_MY_COMPONENTS. The names for each of the properties are also using similar keys. This is the key for the localized string for the category name. If you open strings.json from the locale folder, you will see the following entries.

The most common error while editing this file is having an unnecessary trailing comma for the last element in the array.

The value of the icon field is set to Sp_Image_Sm. If you go to the assets folder you will notice the following two pngs under it with the prefix Sp_Image_Sm.

These are the icons for dark and light UI.

The value of the ‘source’ field in components.json, its set to ‘src/myimage.js’.

(function($) {    

// Register a component with the className: my.Image,
 // and prototype with the following overrides 
 // getCreateOptions
 // getCreateString
 // getProperties
 // getAttributes
    $.anwidget("my.Image", {
         options: {
   'visible': true,
   'position': 'absolute'
         },
  _props: ["left", "top", "width", "height", "position", "transform-origin", "transform"],
  
_attrs: ["id", "src", "alt", "class", "border"],
  
// Return a unique ID with the prefix image
  // _widgetID is a global declared in anwidget
  // This id is used only if the user has not set any instance ID for the component in Animate
  // Otherwise the user configured name is used
  getCreateOptions: function() {
   return $.extend(this.options, { 'id': "image" + _widgetID++ });
  },
  
// Return the string for creating the DOM element
  // For image we just need to create the <img> tag
  getCreateString: function() {
   return "<img>";
  },
  
// Set of configurable properties
  getProperties: function() {
   return this._props;
  },
  
// Set of configurable attributes
  getAttributes: function() {
   return this._attrs;
  }    
 });   
})(jQuery);

You can follow the comments in the code to understand it easily.

Please feel free to take a look at the source for the other components which are supplied with Animate. In most of the cases you can use one of these as the starting point and then configure it for your own requirements.

Wrapping a jQuery-UI component

This section describes how to wrap a jQuery-UI widget and use it in Animate. The same concepts can be used to wrap any other existing component from any other UI framework.

Let us understand the packaged DatePicker component with Animate which is a jQuery-UI widget. Download and extract the contents of the following archive and use it for your reference.

Download

Get file

Click here to download datepicker.zip file.

The folder named jquery-ui-1.12.0 is the source for the jQuery UI framework which contains the original DatePicker widget and its resources like images and css to wrap and use in Animate like any other HTML5 Component. This is required only for local preview, when you use “hosted libraries” in Publish settings, you have the option to use the cdn to download the dependent sources.

There are two default dependencies, jQuery and anwidget.js. Since anwidget.js is not on the CDN, we do not have any CDN entry for the same.

The next set of entries are for the other resources required for loading the datepicker widget from jquery ui. If you are wrapping any widget from any other library, you can similarly specify the set of dependencies for the same. These dependencies are downloaded before the component is initialized.

In the properties section, we have only exposed one property called label, which is bound to the label property for the date-picker component. Similarly, we can expose the other properties too, whichever we want the user to be able to configure in Animate’s authoring environment. At runtime, each of these will be available as a key-value pair in the options array for the instance. We can extract the configured value and apply that at runtime.

Sections that differ from the example

getCreateString:

The datepicker widget from jQuery-UI takes such an input text element and converts it to a date-picker element at runtime. Therefore, we initialize the DOM accordingly.
attach:

We need to override this function for this widget. This API is called whenever the element is being attached to the DOM. However, because of the way the underlying runtime (in this case createjs) works, this API may be called multiple times during a frame span.

We remember the attached state of the underlying element and then call the base class’s attach API (using this._superApply(arguments)). If this is the first time we are attaching the element to the parent DOM then we use the underlying jQuery-UI widget’s call to convert our component’s DOM to a datepicker. See - https://jqueryui.com/datepicker/

Most of the javascript widgets work in a similar fashion. You can use the same technique to wrap any component of your choice and bring it into Animate in the same manner.
Update: We override update and apply the css properties to the container div and attributes to the real DOM element.

When you override APIs like attach, detach or update, evaluate the base class’s default implementation and call the base implementation at appropriate time otherwise the component initialization may fail.

Get help faster and easier

New user?

Creating custom Components: Examples

Component Metadata - components.js

Wrapping a jQuery-UI component

Sections that differ from the example

More like this

Get help faster and easier

Ask the Community

Contact Us