Aikau Mini Examples – Wrapping a JQuery Widget

[ddraper]

Introduction

This is one post in a series of short examples of things that can be done using the Aikau framework. The series is not intended to provide complete documentation but simply to show how to solve frequently encountered problems, implement repeating UI patterns, show case how to use existing widgets or how to create new ones.



PLEASE NOTE: This requires at least Alfresco 5.0.b Community (or Alfresco 5.0 Enterprise when it is released).

Real World Use Case

Aikau heavy use of Dojo for its AMD module loading and many of the Aikau widgets use the Dojo widget templating and utility functions. That doesn’t mean that you have to use Dojo for your own widgets if you’d prefer to use other JavaScript libraries.

Simple Example

In this example we’re going to define an extension module that includes some JQuery libraries and then create a new Aikau widget that wraps an existing JQuery widget.

Build an Extension

First we need to download the JQuery and JQueryUI resources we want to make use of. In this example I have downloaded JQuery 1.11.1 and JQuery UI 1.11.1 and will wrap the Accordion widget. We’re going to need to define 3 new AMD packages for:

• JQuery



• JQuery UI



• Our blog widgets

The extension looks like this and is included in the downloadable example JAR:

<extension>

  <modules>

    <module>

      <id>Add JQuery</id>

      <auto-deploy>true</auto-deploy>

      <evaluator type='default.extensibility.evaluator'/>

      <configurations>

        <config evaluator='string-compare' condition='WebFramework' replace='false'>

          <web-framework>

            <dojo-pages>

              <packages>

                <package name='blog' location='js/lib/blog'/>

                <package name='jquery' location='js/lib/jquery-1.11.1' main='jquery-1.11.1.min'/>

                <package name='jqueryui' location='js/lib/jquery-ui-1.11.1' main='jquery-ui'/>

              </packages>

            </dojo-pages>

          </web-framework>

        </config>

      </configurations>

    </module>

  </modules>

</extension>

I won’t go into any depth on what this configuration does as it has been discussed in this previous blog post.

Create Our Custom Widget

The JQuery UI website provides excellent examples of how to use the Accordion widget, but to make this a more realistic example we want to be able to include other Aikau widgets in each Accordion section.



Our widget comprises a JavaScript file and an HTML template file (although we could also include CSS and i18n files as well - see this previous post for details). The HTML template is just about as simple as possible containing nothing more than a single DIV element with a class that we could anchor specific selectors to.



The JavaScript file first declares our dependencies:

define(['dojo/_base/declare',

        'dijit/_WidgetBase',

        'dijit/_TemplatedMixin',

        'dojo/text!./templates/JQueryAccordion.html',

        'alfresco/core/Core',

        'alfresco/core/CoreWidgetProcessing',

        'jquery',

        'jqueryui'],

       function(declare, _WidgetBase, _TemplatedMixin, template, AlfCore, CoreWidgetProcessing, $) {

We’re going to construct the widget using the base Dojo templating capabilities provided by “dijit/_WidgetBase” and “dijit/_TemplatedMixin” and will then mixin in the Aikau modules “alfresco/core/Core” (which provides i18n handling, pub/sub, logging and data binding capabilites) and “alfresco/core/CoreWidgetProcessing” which provides capabilities for processing child widgets. Lastly we declare our JQuery dependencies, mapping the return value of the jquery module to $.

Dojo Widget Lifecycle

We then need to override two Dojo widget lifecycle attributes/functions.

templateString: template,



postCreate: function blog_JQueryAccordion__postCreate() {

  this.processWidgets(this.widgets, this.domNode);

  $(this.domNode).accordion();

},

“templateString” is set to be the template mapped from our HTML file (see the Dojo documentation for more information on this, but its essentially boilerplate code).



“postCreate” is the main function we need to override to actually do some work. This function is called once the widget DOM is available. We first call the “processWidgets” function (inherited from “alfresco/core/CoreWidgetProcessing”) to process any child widgets in the JSON model and then we use JQuery to create the Accordion against the root widget DOM node.

Aikau Override

In between those two lines executing the “createWidgetDomNode” function from “alfresco/core/CoreWidgetProcessing” will be called for each widget being processed. All Aikau widget functions are designed to be overridden for simple customizations and in this case we need to change the DOM that is constructed for each child widget to match the expectations of the JQuery widget. This is achieved by overriding the inherited function:

createWidgetDomNode: function(widget, rootNode, rootClassName) {

  $(rootNode).append($('<h3>' + widget.title + '</h3>'));

  return $('<div>').appendTo($('<div>').appendTo(rootNode))[0];

}

The normal behaviour of the function would just be to create a single DIV element, but our overridden function creates an H3 and and a DIV within a DIV. This last DIV element is returned to the next stage of wiget processing and will be the element that the child widget is added to.

WebScript Time

Now we just need to define an Aikau page that includes our new widget:

model.jsonModel = {

  widgets: [

    {

      name: 'blog/JQueryAccordion',

      config: {

        widgets: [

          {

            name: 'alfresco/logo/Logo',

            title: 'Alfresco Logo',

            config: {

              logoClasses: 'alfresco-logo-large'

            }

          },

          {

            name: 'alfresco/logo/Logo',

            title: 'Surf Logo',

            config: {

              logoClasses: 'surf-logo-large'

            }

          }

        ]

      }

    }

  ]

};

In this page adding two “alfresco/logo/Logo” widgets as children of an instance of our new “blog/JQueryAccordion” widget.

Example In Action

This is defined in a JavaScript controller for a WebScript mapped to the /jqueryWidget URL. When deployed to a Share (or any Surf based Aikau application) this can be accessed by the URL: http://localhost:8081/share/page/dp/ws/jqueryWidget



Here is a screenshot of the resulting page:







Download the entire example here.



Download a PDF version of this blog here.