Created

Jul 06, 2014

AEM Forms: Using Custom Widget in Adaptive Form

Posted by deepakk

Sometimes, customers want to use more sophisticated widgets while capturing data from the end user in order to improve their overall data entry experience. For example, instead of making user type the digits for numeric fields, customer might want to show a slider to capture data. Similarly, they might want to present data in more intuitive way to end user like when showing the address to end user, they might like to show him the address on map instead of just as text. 

Adaptive Forms allows developers to build custom widgets which can integrate with rest of the Forms eco system and still support all the business rules (aka expressions) that Form Author might write for that field. Once a developer deploys these custom widgets, AEM Form author can easily enable that for any particular form field using Adaptive Form Field properties Dialog in Form Authoring mode. The widget framework has been taken from AEM XFA HTML5 Forms (aka AEM Mobile Forms), the approach to use the custom widgets is same as in Adobe XFA HTML5 Forms. The XFA HTML5 Form Widget Specification provides good details about Widget Framework. One can use reuse existing jquery or other ui widgets by creating a wrapper around those widgets that adheres to the Form Widget specification. This specification provides a basic widget(abstractWidget) and defines certain function that custom widget may override and certain events that it should dispatch, more details here.

In this article we would be building an address look up widget in which, when user start typing city name, it would start showing him suggestions from which he can select the appropriate address. We would be using jQuery autocomplete widget for this. Code for sample is shared at github repository. I’ll highlight couple from things from that:

Creating Custom Widget

We have created custom widget called addressLookupWidget which extends from existing textField widget. We have mainly overrided render function of textField widget and plugged jquery ui autocomplete widget on that field which makes REST call to geonames server and return address. Below snippet hightlights the call to REST endpoint:

Note: In order for Adaptive Form to be able to use the widget, the widget   javascript code must be registered as AEM Client Library with category named af.customwidgets.

        render : function() {
            var $control = $.xfaWidget.defaultWidget.prototype.render.apply(this, arguments);
            if($control){
                $control.autocomplete({
                    source: function( request, response ) {
                        $.ajax({
                            url: "http://ws.geonames.org/searchJSON?username=demo", //one can have their own username registered with geonames.org
                            dataType: "jsonp",
                            data: {
                                featureClass: "P",
                                style: "MEDIUM",
                                maxRows: 12,
                                name_startsWith: request.term
                            },
                            success: function( data ) {
                                response( $.map( data.geonames, function( item ) {
                                    return {
                                        label: [item.name, item.adminName1, item.countryName],
                                        value: [item.name, item.adminName1, item.countryName]
                                    }
                                }));
                            }
                        });
                    },
                    minLength: 2,
                    open: function() {
                        $( this ).removeClass( "ui-corner-all" ).addClass( "ui-corner-top" );
                    },
                    close: function() {
                        $( this ).removeClass( "ui-corner-top" ).addClass( "ui-corner-all" );
                    }
                });
            }
            return $control;
        }

 

Enable widget for a particular Form Field

Form Author can enable the widget by adding a specific CSS class name in the field dialog. The class name should be of the following format: widget_<widgetname>. In above case, we would add the widget_addressLookupWidget.  If this widget is deployed on the server as mentioned in previous step, Adaptive Form Runtime would automatically enable that for this particular field where this css class is applied.

Writing Expression to Prefill other Form Fields from selected Field

Package created from github repository also contains an Sample Adaptive Form. This Adaptive Form has Find City button in Address Panel. On clicking that, it shows Address Lookup Panel. End user can type city name in that widget and it would start making suggestions. When user selects one of the suggestions and click ok, City, State and Country field in Form Address Panel are populated from selected suggestion. This population of city, state and country is done by writing click expression on ok button in form authoring mode. There are two part to writing expression:

  • Writing Custom Function: The widget library also registers a custom Function Function called AdressLookupUtil.addressFill  which populates city, state and country field from given field value.
  • Calling Custom Function From Expression: The ok button of Find City Panel, has click expression which calls above expression to set value for city, state,coundtry field from selected address: AdressLookupUtil.addressFill(addlookup, city, state, country); Besides that, Ok click expression also toggles Find City Panel to back to Address Panel.

 

Deploying and Running the Sample

The address-lookup-widget folder in aem-forms-samples github repository contains the source code for the sample along with instructions about how to build and deploy the sample. When you deploy the built package using package manager, it would also deploy a sample Adaptive Form which would be accessibe at http://<host>:<port>/content/forms/af/widget-sample/addreslookupsample.html . This Sample would have Find City button in Address Panel which would show City Look Up field where above widget has been enabled. When you type more than 2 characters, it would start showing suggestions. Below is the screen shot from final end user experience.

file

Note: We have used demo account for accessing geonames REST endpoint which may hit daily limit of demo account request counts. You can register and use your own user account for accessing geonames services. Few details here.