Developing Mobile Applications with Force.com and Sencha Touch – Part 3

try {
//Fetch all Leads for the user
LeadList = getAllLeads();
} catch (Exception e) {
resp.success = false;
resp.errorMessage = ‘Query failed: ‘ + e.getMessage();
return resp;
}

//Supply only the requested records
for (Integer recno = qr.start; recno < (qr.start + qr.recordCount) && recno < LeadList.size(); ++recno) { resp.records.add(LeadList[recno]); } resp.total = LeadList.size(); resp.success = true; return resp; }

The flaw in this pattern is that all Lead records available to the current user are fetched and iterated over with each request, even though only a small number are actually required to be returned; a most inefficient process. Salesforce has a few different patterns available for fetching sets of objects, and we will take advantage of the SOQL OFFSET feature which works well with the page size and record count properties that we have already built, and are available from our request object.

We need to change two methods in our Apex controller to implement the new version of the paging logic. First, we’re going to change the helper method that will return the page of records. The original method looks like this:

Replace that method with the new version below; it’s a bit more code, but actually very straightforward. It simply calculates the paging values using the parameters passed in the request, builds one query to get a count of all records, and another query to fetch the exact page of records based on the calculated paging values. Note the OFFSET and LIMIT portions of the SOQL query.

Also note the SOQL whereClause variable which constructs a filter using the qr.searchFilter property. We’ll use this property shortly to pass a search string from the Sencha application to filter the query, and we’ll initially default its value to a SOQL wildcard so that all records will be fetched for the SELECT. Our code also checks to determine if an empty string is passed, in which case the WHERE clause will simply be omitted from the query.

//Page size is set in the Sencha store as recordCount.
Integer pageSize = qr.recordCount;

//Page number will be calculated.
Integer pageNumber = 0;

//Start is the record number indicating the start of the page.
if (qr.start > 0) {
pageNumber = qr.start / pageSize;
}

//Calculate the offset for SOQL.
Integer offset = pageNumber * pageSize;

//Build the query in pieces.
String fieldList = ‘Id,FirstName,LastName,Company,Title,Phone,MobilePhone,Email,Status’;
String whereClause = (qr.searchFilter != ” ? ‘WHERE Name LIKE ” + qr.searchFilter + ”’ : ”);
String orderByClause = ‘LastName, FirstName’;

//Construct a base query to which the page offsets will be added.
String baseQuery = ‘SELECT ‘ + fieldList + ‘ FROM Lead ‘ + whereClause + ‘ ORDER BY ‘ + orderByClause;

//Construct a count query to pass back the total records matching a search criteria.
String baseCountQuery = ‘SELECT COUNT() FROM Lead ‘ + whereClause;

//Construct the fetch query with the offset.
String fetchQuery = baseQuery + ‘ LIMIT ‘ + pageSize + ‘ OFFSET ‘ + offset;

try {

//Set the count.
resp.total = Database.countQuery(baseCountQuery);

//Set the fetched recordset.
resp.records = Database.query(fetchQuery);

//Set the status flag.
resp.success = true;

} catch (Exception e) {

//Set the total count of records matching the query.
resp.total = 0;

//Set the recordset to return.
resp.records = new List < Lead > ();

//Set the status flag.
resp.success = false;

}
}

The SOQL OFFSET processing is very efficient, fetching only the exact set of records requested. Notice the method takes both the QueryRequest and Response objects as parameters, and sets the properties of the Response object to be sent back to the Sencha application. Before you can save the controller class, you must also modify the @RemoteAction Query() method to work with the new version of the helper method above, replacing the old method with the following code:

Response resp = new Response();

//Enforce a limit on the number of rows requested.
final integer QUERY_LIMIT = 500;
if( qr.start >= QUERY_LIMIT ){
resp.success = false;
resp.errorMessage = ‘Maximum number of records (‘ + String.valueOf(QUERY_LIMIT) + ‘) exceeded!’;
return resp;
}

try {
getAllLeads(qr, resp);
} catch (Exception e) {
resp.success = false;
resp.errorMessage = ‘Query failed: ‘ + e.getMessage();
}

return resp;
}

This new version of the method is much simpler. First, it ensures the request has not exceeded the maximum query limit established for the application, and then it sets up and calls the new helper method which does all the real work.

Save your changes to the Apex controller making sure it compiles correctly, and refresh your Sencha application in the browser; it should work exactly as before with the refactored Apex controller class.

Step 3: Clean Up the Proxy Error Listener

While I was running tests during development of the code for this part of the tutorial, I found some bugs in an error handling routine that we built out in the original posting of Part 2 of the series. If your code matches the original code below, please replace it now with the repaired version.

We had added a listener on the data proxy in the init() function of the PocketCRM.controller.Leads component to catch any errors passed back from the Apex controller. The original code below is flawed, and was not correctly displaying the error messages:

If your version is the flawed code, replace the original code with the repaired code as below that has corrected references to the response and operation objects, The improper references in the JavaScript were not actively breaking anything; the function was just failing silently, but will now properly report errors:

Save your changes to the JavaScript and refresh your Sencha application in the browser to ensure no new errors were introduced; it should work exactly as before. You will see this routine in action if you page through the list requesting more records, and finally exceed the maximum number allowed by the query method. If you don’t have enough leads to reach the ceiling, simply lower the limit from 500 to a smaller number to see the error handling behavior.

Step 4: Add a Search Field to Filter the Leads

Now that the new paging mechanism and query methods are in place, we can add a Search Field for a user to enter a partial Lead name to filter the query results. We have to add a few moving parts to get this working.

First, we need to modify the PocketCRM.view.LeadsList component, adding a Search Field on the toolbar docked at the bottom of the view. While we’re at it, we’ll also change the position of the refresh button and it’s display icon, which will be used to execute a search after a user has entered some search text.

The Search Field also has an embedded icon, (it appears as an x in a circle to the right of any entered text,) and when clicked or pressed, it clears the entered value. We will add a new listener and event handler on this icon so that when a user clears the search text, a refresh of the data is also fired off.

Since it’s useful to know how many records a user has accumulated in the list, we’ll also add a listener on the list itself, so that when it is refreshed or reactivated, we display the current record count as Badge Text on the refresh button. We could create a label somewhere on the toolbar to display this counter, but space is tight and this will give you an example of how you can set Badge Text on those components (such as buttons) that provide this feature.

Find the JavaScript for the PocketCRM.view.LeadsList component and modify the following code sections. First, find the code for the bottom toolbar in the Items configuration and replace it with the code below. This adds an itemId, a SearchField component, and adjusts the layout of these items with additional spacers. Notice also that we have changed the iconCls of the syncButton component to display a Search rather than a Refresh icon:

items: [
{
xtype: ‘spacer’
},
{
xtype: ‘searchfield’,
itemId:’leadSearchField’,
placeHolder: ‘Name Contains…’
},
{
xtype: “button”,
iconCls: “search”,
iconMask: true,
itemId: “syncButton”
},
{
xtype: ‘spacer’
}
] },
…

Next, find the listeners configuration, and add these additional listeners after the one for the #leadslist delegate:

Finally, add the new functions for each of the new listeners after the final function for the onLeadsListDisclose event, (be sure to precede the new set of functions with a comma delimiter:)

onLeadsListRefresh: function () {
console.log(“onLeadsListRefresh”);
this.updateListCounter();
},

onLeadsListViewActivate: function () {
console.log(“onLeadsListViewActivate”);
this.updateListCounter();
},

//Function to get count of records in the list and show on the search button’s badge.
updateListCounter: function () {
var listCount = Ext.getStore(“Leads”).getCount();
this.getComponent(“bottomToolBar”).getComponent(“syncButton”).setBadgeText(listCount);
}

We will add the event handler logic for the clearSearchLeadCommand in the controller shortly. The final function in the set (updateListCounter) is called from both the onLeadsListRefresh and onLeadsListViewActivate event handler functions, and contains logic to update the Badge Text of the syncButton with the current record count. Note how it gets the record count from the data store, and sets the value to the Badge Text of the syncButton in the bottomToolBar component. This is just one example of how to obtain references to components and get/set values within functions.

Save your changes and refresh your Sencha application in the browser to ensure no errors were introduced. You should now see the new Search Field and adjusted button and record count. You can enter a search value, but it won’t yet apply the filter when you reload the list.

Step 5: Refactor the Load to Include the Search Value

We have to modify our reload logic to include the new search value. As this logic is called from more than one place in our code, it will be best to isolate into its own function, and then call as needed from other functions. We’ll also have to make a few other supporting modifications to the PocketCRM.controller.Leads component.

First, we need to add a new controller reference for the new Search Field in the controller’s refs configuration section, it will look like this:

Next, we need to add a new control for the new event fired by List View’s event handler function on the Search Field’s clear icon. It will be added in the control configuration section, and will look like this, (make sure to add a comma delimiter after any configuration that precedes the new clearSearchLeadCommand):

Now we must add the logic to manage the reload of the data, and include any search values entered by the user. Once this function is available, we will call it from a number of other event handlers. Add the new function below all the other event handler functions, but above the launch function:

//Get a ref to the store and remove it.
var leadsStore = Ext.getStore(“Leads”);

//Get any search text.
var leadSearchField = this.getLeadsListSearchField();
var searchText = leadSearchField.getValue();

//Validate for at least 2 or more characters.
if (searchText.length > 0 && searchText.length < 2) { var msg = 'Search requires more text.'; Ext.Msg.alert('Please correct errors!', msg, Ext.emptyFn); return; } //Add wild cards to the search string. if (searchText != '') { //Surround the search value with wildcards for SOQL LIKE search. searchText = '%' + searchText + '%'; } else { //Set wildcard for wide open filter. searchText = '%'; } //Set the value of the searchFilter param to pass with the request for the query. var model = Ext.ModelMgr.getModel('PocketCRM.model.Lead'); model.getProxy().setExtraParam('searchFilter', searchText); //Clear all data in the store before reloading it. //This is necessary to make sure that the proxy doesn't get confused by //the loss of records removed but not reloaded with a new filter. //Without the clear(), the proxy assumes a deletion was processed and //calls a destroy to be executed on missing records with the next sync() operation. leadsStore.getData().clear(); leadsStore.loadPage(1); //Show the list. this.activateLeadsList(); },

Add the following new function to handle the search field clear event, place it after the onBackToHome event handler:

//Get a ref to the search field.
var leadSearchField = this.getLeadsListSearchField();
leadSearchField.setValue(”);
console.log(“Cleared Field Value: ” + leadSearchField.getValue());

this.loadList();
},

Modify the following event handler functions to also call the new load function:

…
launch: function () {
console.log(“launch”);
this.callParent(arguments);

//Load up the Store associated with the controller and its views.
console.log(“load Leads”);
this.loadList();
},

Remember to take care to include all commas and curly braces as needed or your JavaScript will break. This was a lot of code to change, hopefully we will not have introduced any errors. Save your changes and refresh your Sencha application in the browser to ensure all is well.

Now, enter a search value into the new Search Field and click the search button. If all your changes are working properly, the list should refresh showing only records matching your search criteria. If there are more records matching your search than the default page size, you should be able to load additional records by clicking the “Load More…” link. Continue to fetch more records until you see the “No More Records” message. If the number of records you have loaded into the list exceeds the maximum as configured in the Apex controller’s Query method, you should see an error message alert, (thanks to our repaired Apex error listener.)

Clicking the clear icon in the Search Field should remove the search value from the text box and refresh the list with the original record set displayed. In each case, you should see the record counter change in the search button’s Badge Text. To ensure that the counter refresh events are also working properly after CRUD operations, try to add and then delete a new lead. Each time the List is re-displayed following such an operation, you should see the record counter adjust correctly reflecting the newly added or removed record in the count.

Using the Web Inspector developer tool from Safari, you can trace the proxy request when the search and reload operations are executed. You can inspect the JSON request payload sent to the Salesforce remoting service which should look like this for a search, note the value of the searchFilter which includes the SOQL wildcards:

Each request for more data will increase the start property. Here’s what it looks like for a request of the third page with no filter value, (note the passed wildcard character for an empty search value:)

Summary

Let’s recap what we accomplished:

1. We added a Sencha ListPaging plugin to provide “scroll down” paging to automatically fetch more records when a user scrolls to the bottom of the list. There are other plugins available with similar but alternate behavior, some provide next and previous paging, others provide a “Pull Down” type fetch. If you want to get adventurous, you can even write your own.
2. We redesigned the querying capability of our Apex controller class to provide efficient data paging using SOQL OFFSET and a search filter, and we set an upper limit on the number of records that can be fetched by the client application.
3. We added a Search Field in the list view, allowing a user to filter records fetched from Salesforce by a search on any portion of a Lead’s first or last name. You can also rewrite the Apex controller to use SOSL for a fulltext search, or build out a more complex dynamic query capability.
4. We added the display of a record count reflecting the current list content that refreshes with each reload of data.
5. Finally, we fixed a bug in the data proxy listener to properly display errors returned from our Apex controller.

You can find the full code for the completed application for Part 3 here at GitHub.

Closure

In the next part or our series, we’ll expand our application to provide an appropriate user interface for a tablet device, in addition to a phone, by leveraging the Sencha Touch profile feature. This feature adds the capability to identify the device type loading the application, permitting a single code base to support multiple form factors. By isolating alternate sets of components to support different devices, applications can also share larger collections of components for common functionality in the remainder of the codebase.

In the meantime, I encourage you to continue your Force.com and Sencha Touch mobile ramp-up by watching videos, playing with and dissecting samples, and reading through the great online guidance documentation. You should now also have enough knowledge under your belt to build a simple application of your own using all the design patterns from the tutorial to date. Also, definitely check out the features and functions of the recently announced Salesforce Touch Platform; you can go here to download a free eBook and read all about it.