Dojo Data Grid – Part 2: Providing the Data with a REST Service

Data grids need a data store to obtain the information to display in the grid.

An easy way to set one up with XPages by using a REST Service control, which, like the Dojo Data Grid control, is available in the Extension Library and with 8.5.3 Upgrade Pack 1. You can find it in the Data Access section of the Controls view in Domino Designer:

Grid2_1

When you add one to the page, you see this little icon on the Design tab:

Grid2_2

Configuring the REST service

Follow these steps to set up the REST service to provide the data from a view:

1. Select the REST service control and All Properties subtab of the Properties panel, go to basics > service and click the plus (+) icon and select xe:viewJsonService
Grid2_3

2. Set the contentType (basics > service > contentType) to application/json

3. Set the defaultColumns property (basics > service > defaultColumns) to true. This provides the data from all columns in the underlying view, without you having to define them individually. (You can select individual columns or define your own via the columns property, if you choose, but this is the easiest way to get all columns from the view.)

4. Select the target view in the viewName property (basics > service > viewName)

Verifying the REST service

If you set the pathInfo property of the rest service (All Properties > basics > pathInfo), you will have a way to verify the data being returned by the service. This is a very helpful tool not only for troubleshooting, but for gaining an understanding of the data structure that you’re working with.

Grid2_5

To verify the data, load the XPage that contains the REST service and include the pathInfo name in the URL, like this:

server.com/dbname.nsf/xPageName.xsp/pathInfoName

Here is an example of what you will see:

Grid2_6

The pathInfo is not required when working with the Dojo Data Grid, but it is required when consuming the REST service from another library, like ExtJS.

Creating a Custom Column

In addition to (or in lieu of) the default columns, you can define your own custom columns for the REST service. You can use this to compute values that combine information in the underlying view or even look up information from another database altogether, because you use server-side JavaScript.

In order to read data from the view entry, you will need to set the ‘var’ property of the REST service.

For example, if I wanted to add a column that combines the firstname and lastname columns from underlying view, I would need to take these steps:

  1. Set the var property of the REST service (All Properties > basics > service > var)
  2. Add a new column, but clicking the ‘+’ icon in the columns property (All Properties > basics > service > columns)
  3. Click the diamond to compute the value of the column (All Properties > basics > service > columns > restViewColumn[0] > value)
  4. Set the name of the column (this will be the way to reference the column in the grid) under All Properties > basics > service > columns > restViewColumn[0] > name
  5. Enter a script like this:
return restEntry.getColumnValue("firstname") + ' ' + restEntry.getColumnValue("lastname");

Grid2_7

Now, if you verify the REST service data, you’ll see the additional column.
Grid2_8

There does not appear to be a built-in way to get a handle to the underlying document, but you should be able to reference the unid from the view entry and use that to look up the document, should you need more information.

System Columns

The REST service also has a systemColumns property, which allows you to select system values to include with each entry. Clicking the button in the property row will bring up a dialog box with checkboxes for the options to select.

Grid2_4

Here are the options:

  • NoteID
  • UNID
  • Position
  • Read
  • Siblings
  • Descendents
  • Children
  • Indent
  • Form
  • Category
  • Response

As you can see in the screen shots earlier in this post (with the REST service data), several of these system columns are included by default: unid, noteid, position, siblings, form.

If you select one or more system columns specifically, then only the selected system columns will be included. It appears that @entryid will always be included.

Ready for the grid!

How that you have a REST service providing data, you are ready to surface the grid! Tune in next time to see how to surface your first grid.

Advertisements

18 responses to “Dojo Data Grid – Part 2: Providing the Data with a REST Service”

  1. Karsten Lehmann (@Klehmann79) says :

    It’s important to note here that if “form” is selected as system column, the REST service needs to load the document for each view entry, which heavily influences the performance of the HTTP request. It’s a lot better to create a view column with that value and let the REST service read that one. BTW, that REST service control is not a black box. Source code for the Extlib is available on OpenNTF. Everyone can create his own REST service (e.g. via an XAgent) and get the same performance with more flexibility if required. IBM is using the normal Notes Java API, no hidden features or C code.

    • Brad Balassaitis says :

      Great feedback — thank you!

    • MarkyRoden says :

      Using an xAgent to create REST data in XPiNC has performance issues when connecting to the server. The getNextEntry goes back and forth from the client to the server for every single row in the service – rather than having it all computed on the server.

      I believe this is fixed in R9 with “run on server” but prior to that it is not pretty for a large view.

  2. Luis says :

    Hello Mr. Balassaitis, I am reading your Dojo data grid series and it’s a great great series!! thanks you for that!!

    I am begginer to dojo and rest services and I would like to know how can I populate a dojo data grid from a Java List?

    I hava a Java bean property list object, let say List that has a list of employees of a company and I want to populate de dojo data grid with this list property.
    I know that I can write a javascript to get that list and convert to json object, but how I can populate a dojo data grid with a json object?

    do I need to create a rest service? if so, what kind of rest service I must to create?

    Thanks you very much in advance, sincerely.

    Luis

  3. Tony Frazier says :

    Brad, once again, thanks for this series, very helpful. Question: how did you know about the getColumnValue function? Is this part of some documentation on the Rest Service control somewhere? I suspect there are other row entry functions, and probably other functions/apis on the Rest Service control itself, but I don’t know where to look.

  4. bryanschmiedeler says :

    This was very very helpful to me. One quick question.

    Can I pass a parm to a the rest service? I want to only get a subset of the data that I currently have.

    Bryan

    • Brad Balassaitis says :

      Absolutely. Assuming you’re using one of the built-in REST services to provide view contents, there are several properties you can compute to either context.getUrlParameter(‘paramName’) or sessionScope.myParameter to read a url parameter or session scope variable, respectively.

      If you compute the “search” property, it will perform a full-text search on the view. Or, you can compute the “category” property to use that parameter to filter to a single category. (“startKeys” is another option, but, in my opinion, category filtering is a good way filter the data)

  5. Andrew says :

    Hello Brad and thanks for all of your hard work here!

    I’ve got a question for you. I want to use a Dojo Grid to display my json data.
    My json data is onhand and I’m ready to use it, but as far as I can tell the grid is setup to make the long way around (view->rest->grid) more accessible. How would I go about using my json data to populate my grid? Is this possible?

    Thanks in advance for any help!

    • Brad Balassaitis says :

      I haven’t tried it, but I’m pretty sure it’s doable (although I don’t know how simple it will be).

      I found this snippet in an example online from a programmatic grid creation function:

      var dataStore = new dojo.data.ItemFileReadStore({
      data : myJSONData,
      id : “dataStoreId”
      });
      var grid = dijit.byId(“gridId”);
      grid.setStore(dataStore);

      I think you could use the first 4 lines to create a dojo data store based on the JSON data that you have. Then you may be able to use the storeComponentId property of the grid to reference it.

      However, there may a challenge with the timing if the grid is rendering before the data is available, but I can’t say for sure without testing it.

      • Andrew says :

        Awesome, thanks! Unfortunately, that opens up another problem. Is there a “best way” to transmit information from SSJS to CSJS?

      • Brad Balassaitis says :

        There are several ways you could go about it. The simplest may be the following:

        1) Use the SSJS to put JSON into a viewScope variable (say viewScope.gridData, for example)

        2) Put an Output Script tag (xp:script) on the page to read it into a global client-side JavaScript variable with the pass-thru SSJS syntax, like this:

        var myGridData = “#{javascript:viewScope.gridData}”;

        3) I would expect that you’d need to parse the data in order for it to be truly interpretted as JSON, like this:

        var parsedGridData = JSON.parse(myGridData);

        Then you could try using parsedGridData as the source for the grid, because it’s a client-side JS variable with the JSON data.

        However, I haven’t tried this. I wouldn’t be surprised if you needed to create some kind of Dojo data store, but I’m not sure if that’s necessary or if it can take the JSON data directly.

        (For the record, I’d personally probably use a JSON RPC component to get the data back, but that’s a bit more complicated of an explanation and this should get you the same desired result.)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: