Editor’s note: This blog post is a basic tutorial. The most up-to-date version is available in the wiki.
Between RESTful and SOAP based web services, there’s an endless supply of data out there just waiting for you to pick it up. Wouldn’t it be great to query this data directly from your Appcelerator app? Of course it would, and fortunately Appcelerator has a simple and familiar interface for doing so.
Titanium.Network.HTTPClient, as its name implies, allows you to make client calls to HTTP web services. It is a specialized implementation of the XmlHttpRequest specification that works with your native Appcelerator code. Let’s take a look at how we can use this interface to query data from a remote source and use it in your app.
So let’s breakdown what’s happening here in this snippet. After we create a variable to hold our target URL, we create the
HTTPClient. When we do so, we set up 2 important event handlers:
- onload – This is the function that will be called upon successful response from the target URL. The response data can be processed using 3 different properties of the
- this.responseText – Contains the raw text response from the target URL. This is the property that would be used when processing JSON or other plain text data.
- this.responseXML – Contains any XML formatted data from the response. As you might expect, this property is most appropriate for processing SOAP and other XML based web services.
- this.responseData – Contains your response data in binary format.
- onerror – This is the function that will be called in the event of an error in your response. To help troubleshoot errors, there are again 3 properties you can check, though this time one belongs to the event object:
- this.responseText – Like with
onload, this contains any text data that was returned with your error response.
- this.status – Contains the returned status code of the error.
- e.error – Contains additional error information included in the event object
- this.responseText – Like with
As you can see, these 2 event handlers are the heavy lifters when it comes to
HTTPClient. They determine how the data will be handled once it is returned asynchronously from your
One final property we’ll set is
timeout which will abort our asynchronous call after the specified number of milliseconds. This prevents a flaky web service from stealing control from your app’s flow for too long.
To actually send the prepared
HTPPClient call, we simply
HTTPClient connection with a connection type (either GET or POST) and our target URL. Once the connection is opened, we then send our asynchronous request via
send(). And that’s it. From here on out, all of the
HTTPClient flow is handled by our previously defined event handlers.
Sample App: ‘Fighters’
So now that you understand the nuts and bolts of a basic
HTTPClient request, let’s get to a full sample app. We’re going to retrieve a static JSON file that includes a list of fighters names and nicknames, then display that data in a Titanium.UI.TableView.
json.txt (from our target URL)
As you can see, we basically filled out the
HTTPClient skeleton from above with the specific functionality of our app. With a successful response in
onload we are going to parse the
fighters JSON array via the
Each JSON object we find in the
fighters JSON array represents a fighter with a name and nickname. We will create a custom Titanium.UI.TableViewRow that displays both of these values. In the end, we will have an app that looks like this:
- Titanium.Network.HTTPClient API docs.
- Github repository for sample app