Lightning Component Autocomplete

The Salesforce1 Lightning technologies were introduced at Dreamforce ’14 as a major upgrade to the Salesforce1 platform.  Lightning Components are built with the open source Aura UI framework which is the same framework on which the Salesforce1 app is built.  Salesforce has included some standard components (e.g., ui components, aura components, etc.), but also has given developers the ability to extend the functionality by creating their own custom components.

Last month I wrote an article that detailed how to code an autocomplete input using Remote Objects and jQuery UI.  I’ve refactored that Remote Object autocomplete to be a Lightning Component autocomplete.  This article covers the details of the implementation.  All code is available on GitHub.

Using the Component

Lightning components are analogous to class definitions in that they provide the definition of what the component will be if used.  They are used by including them in another component or app which is analogous to creating an instance of a class. The autocomplete component is designed to be able to be used by other components or apps.  They can include the component markup where they want it to show up and specify attribute values to control its behavior.

The component allows the user to specify an sObject type, fields to be retrieved, and a maximum number of results to return.  The below code shows how the component can be used.  It is a simple app that contains two autocomplete components and a div to display the selected option.

The Component

The component code defines the attributes it can take, includes the HTML markup to display, and uses another component to load in the JavaScript and CSS files on which it depends.  As can be seen by the above usage, the component allows the sObject type and fields that will be used in the autocompletion to be specified.  It also allows an event handler to be specified to handle an event it fires when a selection of an option is made.

The component consists of a JavaScript controller, helper, renderer, and an Apex controller.  The JavaScript controller delegates to the helper and the helper calls the Apex controller to perform the search and return the results.  In general, Lightning controllers should handle simple control and delegate most work to the helper.

The body of the component defines its attributes, registers a component event, specifies which libraries it needs, and contains markup for the autocomplete jQuery UI widget.

JavaScript Initialization

One of the trickier parts of writing a Lightning Component is using a third party library such as jQuery or jQuery UI.  Due to the asynchronous loading of the JavaScript files, it is possible that the component will be rendered prior to the library being loaded which means that if you try to use a library function (e.g., jQuery/$) it will still be undefined.  Skip Sauls has written an unmanaged package that uses requireJS to abstract away the details of loading and this well done article by Enreeco Murru goes in to more detail about how the files are loaded.

The autocomplete component depends on jQuery and jQueryUI, so that is what is specified.   The action that should be called by the requires component when the files it specified are finished loading is specified as the init function of the controller.

That function sets a Boolean to indicate that the requires has finished and then calls to a helper to set up the autocomplete component.  The autocomplete component also calls that same helper function from its afterRender function in case the component isn’t in the DOM when the requires event is handled.  The afterRender is fired by the framework after the component has been added to the DOM.

The component.get(“v.<attributeName>”) gives access to an attribute of the component by name and component.get(“c.<functionName>”) gives access to a controller action which could be the client side controller or Apex controller.

Action Execution

The source function of the jQuery UI Autocomplete is where the code to retrieve the suggestions from the server is specified.

The component gets a reference to the Apex controller’s @AuraEnabled method, sets the parameters on it, specifies a callback function, and then calls the action.  Parameters representing the sObject type, search term, fields to retrieve in the query and maximum number of results are specified.  When the action completes the callback executes and sets the label and value properties of the ui item, and the jQuery UI Autocomplete’s response function is called.

Apex Controller

The Apex controller builds dynamic SOQL to be executed based on its arguments, executes the query and returns the result as a list of sObjects. Note that the method is static and must be marked with the @AuraEnabled annotation.  If it is not @AuraEnabled, it will not be available from the component JavaScript.  Also worth noting, is that if you create a custom class to return you need to mark its properties as @AuraEnabled to be able to use them and not all standard classes are currently @AuraEnabled.  If you are observing unexpected behavior such as blank/empty results, that may be the cause.

Event Firing

When an item is selected from the list of suggestions the component creates a component level event, sets the parameter to be the selected sObject, and then fires the event.

The container that instantiated the component subscribes to the event and handles it by displaying some basic information about the object.

More

This article described how the Lightning Framework can be used to create a simple, generic, autocomplete component that can be used in other components or apps.  More information about Lightning can be found on, or is linked to from, the Lightning Components Developer page.  Additionally, you can read the API documentation in Aura, including your own custom component, by going https://<your-instantce>.lightning.force.com/auradocs/reference.app, e.g., https://na15.lightning.force.com/auradocs/reference.app.

Side Note: My coworker, Tom Crouse, informed me that Topcoder was just about to finish a challenge involving the creation of an autocomplete widget right around the same time that I had finished my refactoring/recoding of my autocomplete Remote Object post.  I know that he has enjoyed taking part in their challenges and taught himself a lot about Lightning while participating in their $20,000 Lightning Challenges, so I highly recommend participating to anyone interested.

All code for this post is available on GitHub.

11 thoughts on “Lightning Component Autocomplete

  1. Great solution thanks.
    For some reason Salesforce did not let me install the unmanaged package so I did a workaround to load the jquery libraries.
    I can’t seem to apply my css classes to the autocomplete elements. Is anybody else experiencing this? What is the css class syntax if I want to apply it on the result list?

    simple code like this:
    .THIS li.ui-menu-item {
    color: red;
    background-color: white;
    }
    doesn’t work for me.

  2. Hi Dear,
    I am getting this error when searching second time :
    “”Something has gone wrong. Cannot read property ‘childNodes’ of null. Please try again.””
    Do you have any clue ???
    Thanks for helping me out … 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *