JSAPI Tutorial: Presenting a User's Connections

Level: Beginning

Prerequisite: JSAPI User Authentication

Example: Connections Example

Summary:This tutorial covers the basic JSAPI connections call, options for configuration, how to work with the returned object and present it in the browser. When you've completed the tutorial, you will have all the information you need to present connections information in your web application.

Note that all code samples in this document use jQuery, so that's the syntax being used.

Setup

First, authentication needs to be set up as explained in JSAPI User Authentication.

Setup Details

The framework is loaded with the instruction to let the user stay logged in:

And the authentication handler goes on the login button:

A <div> should be created where the output can be injected when it returns.


Basic Connections Call

The profile call can be used to gather information about the logged in user. A very basic profile call gathers the default information about the user and returns it for you to process.

Output

You'll get a large number of person objects back, one for each connection.

Details about the Basic Call

The IN.API.Connections() method can only be called for the current user ("me").

Additional behaviors are chained on as additional methods using the "." format. So in the example above, the method is called with a ".result" function to tell the framework what to do when the result is returned. The .result method can be used with an anonymous function as it is above, or can be given a reference to a different function to call when the results are returned.

Methods which can be chained on general JSAPI methods:


Selecting Fields

The call given above returns the default fields for a Connections call, which are "headline","id","lastName","pictureUrl","firstName".
You can request any valid field in a connections call, however.

Output


Details about Fields

The fields available for a connections request are documented on the Profile Fields page in the general REST API documentation. Note that that page presents the field names in a dashed manner ("first-name") while the JavaScript API expects them in a studly caps manner ("firstName") so you'll need to translate the fields you want to make them work. Also pay attention to the restrictions of the fields that can only be used for the logged in user versus connections or people outside their network.


Adding Parameters

Using the .params() method, you can send additional parameters to the backend REST API call. In this case, we will use the parameter "count" to restrict the returned list to a set of 30 objects.

Output


Details about Parameters

Documentation on what parameters are meaningful for this call are on the Connections API page.


Processing the Return Object

If you check the output for the calls above, you'll see what the returned objects look like. All we have done up until now is print the string version of the object in the browser, but processing those objects is relatively simple.

We'll use as an example the basic connection call.

Connections Call

Results


Details about Processing Results

The results are returned as JavaScript objects, which can be operated on using standard JavaScript notation. Whether a single ID or multiple IDs are requested, the results are returned as a list, so you need to access the value you need by looping through the results or directly referencing the index: profile = result.values[0];

You can access each of the fields you requested (or the default fields) to build the HTML you want to inject into your page, and then inject it like any other AJAX content.



Example Code