Archive | March 2013

Dojo Data Grid – Part 3: Creating Your First Grid

In the series overview, I mentioned that there are 3 high-level steps to creating a Dojo Data Grid. In the last post, I showed how to create the REST service to provide data for the grid. In this post, I’ll show how to create the grid and add columns to it.

Dojo Data Grid Series

Creating the Grid

With the Extension Library or Domino Designer 8.5.3 Upgrade Pack 1, you will find the Dojo Data Grid control in the Dojo Layout section of the Controls view in DDE.

Grid_4_1

Just drag it onto an XPage or Custom Control and you’ll see it on the page with a single facet. This is where you add columns to display data in the grid.

Grid_4_2

At this point, if you view the page, there will be nothing displayed, because there is no data for the grid.

Connecting the Grid to the REST Service

To provide data for the grid, you can connect the grid to the REST service that will provide its data.

To do so, set the storeComponentId property of the grid properties (All Properties > data > storeComponentId) to the ID of the REST service. (This is the ID of the REST service and not the pathInfo value.)

Grid_4_3

Adding Columns to the Grid

All that’s left now is to tell the grid what to display.

To add a column to the grid, just drag and drop a Dojo Data Grid Column control (from the Dojo Layout section of the Controls view) into the Dojo Data Grid facet and set its field property to the name of a field in the REST service.

If you are using default columns in the REST service, then the field name will match the programmatic name of the column from the underlying view. If you have created your own columns for the REST service, then the field name will match the name property of the column that you defined. See my last post on Part 2: creating a REST service to learn how to verify the REST service data and see the field names.

Grid_4_4

Hello, Grid

Now you can view the page and see that you’ve successfully surfaced your first grid!

Grid_4_5

You can change the column width and scroll infinitely through the data.

To fill out the grid, just add more Dojo Data Grid Column controls and set their field properties.

Up Next

In the next post, I’ll dig in to more features of the grid control that are readily available.

Advertisements

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.

Dojo Data Grid – Part 1: Default Features (including infinite scrolling!)

The Dojo Data Grid control is pretty easy to use, once you have the basic concepts down.

Within an hour of beginning to learn about it, I was able to surface this basic grid, based on David Leedy’s FakeNames database, which can be found at xpagescheatsheet.com:

Grid1_1

General Concepts

At a high level, here are the steps that are involved in creating a grid:

  • Create a REST service to provide the grid data
  • Add a Dojo Data Grid control and link it to the REST service
  • Add columns to the grid

This may sound intimidating if you haven’t used REST services or grids, but it really is pretty easy to pick up once you go through it the first time.

Infinite Scrolling!

The grid provides an amazing feature right out of the box — infinite scrolling! There is no paging through the grid; just keep dragging the scroll bar down and it will keep fetching additional rows.

More Default Features

Here are some more of the features that are provided based on the default settings for the grid:

  • Column widths are adjustable. Just click on the right edge of the column header and drag to change the width.
  • The current row is highlighted as you move the mouse over it.
  • Extended selection mode is enabled by default, which allows you to select a single row, control + click to select multiple non-consecutive rows, or shift+click to select consecutive rows; however, we will need to add functionality in order to take action.
  • The grid automatically takes up 100% of the available width, based on its container.
  • Column headers are clickable and they show arrows to indicate that they are sorting, but they don’t seem to actually sort the data by default, even though the grid does refresh.

Much more to come

Stay tuned, there are several enhanced features that can be easily incorporated, so we’ll cover them soon.

In the next two posts, I’ll discuss how to set up a REST service to provide the data for the grid and the steps to surface your first grid.

Dojo Data Grid – Series Overview

The Dojo Data Grid control is another option we have for displaying data in XPages. It provides a more modern look and the potential for much more functionality than a view panel, yet it functions in a way that’s a little more familiar to Notes client users in that it uses a scroll bar, rather than paging.

If you’re reading this post, it’s likely that you’ve also seen Mark Roden’s recent posts on using the ExtJS grid in XPages. I’ve been enjoying that series and learning along with it, but it made me realize that I haven’t yet used the Dojo Data Grid control that’s already available.

Since it’s an XPages control, I’m assuming that it will be much easier to get up and running quickly. I’m also assuming that ExtJS has more functionality. However, I also know that ExtJS has a cost in money (starting at $595 for a single developer license) and overhead (loading the extra libraries into the application), so I want to learn what the differences are so that I can make the best possible decision for each application.

So, here I go. I’m going to dig in and learn the functionality of the grid and document my findings along the way.

In this series, I’ll cover how to use the control and how to implement great features like column sorting and reordering, filtering, and even editing in place.

About the Dojo Data Grid Control

The Dojo Data Grid control makes use of the dojox.grid.DataGrid, which has been a part of dojo since version 1.0. The control is available in the extension library and also in 8.5.3 Upgrade Pack 1 (which I’ll be using for my testing).

One great thing about the Dojo grid is that you can use it even without the Dojo Data Grid control, because it’s already part of dojo on the Domino server! I’m going to be focused on the control in this series, but, if you need to use it without the extension library or upgrade pack 1, check out Paul Calhoun’s NotesIn9 video to see how to do it.

Your Feedback Requested

If you have any questions along the way, please ask and I’ll do my best to answer. If you have tips from experience using the control, please share so that we can all benefit!

I have a lot of posts already planned for this topic, but I’ll adjust as I go if there’s a lot of feedback heading in a specific direction.

Up Next

In the next post, I’ll show a Dojo Data Grid and discuss the features it provides out of the box.

Runtime optimized JavaScript and CSS resources – some results

In Notes/Domino 8.5.3, there is a new setting on the XPages tab of the Application Properties called Use runtime optimized JavaScript and CSS resources.

Runtime Optimized JS

Methodology

I put it to the test on two applications and loaded several pages 5 times each and, using firebug (on the Net tab), noted the amount of data loaded and the load time.

Firebug_Net

Results

In the first database, I opened a page with a view panel and a page with a similar view panel, but a full-text search executed against it. I also opened a page with a document in edit mode and a page with a document in read mode.

This database uses several dojo components (in edit mode of the form), a dojo tabbed table on the form, and some dojo logic around the page with the view panel. It has a few small stylesheets, but uses the OneUI application layout, so there are plenty of stylesheets involved.

Database 1

Without Optimization With Optimization
Page Size Load Time Size Load Time
View 21k 1.78s 7k 0.96s
View-Search 7.5k 1.38s 7.3k 1.12s
Document-Edit 13.7k 2.33s 6.7k 1.47s
Document-Read 11.4k 1.18s 4.5k 0.99s

There are significant improvements in the size of the files loaded and the loading performance.

In the second database, I tested with a page loading an ExtJS grid, so it uses grid libraries and stylesheets, along with jQuery. The database also uses the OneUIv2.1 theme.

Database 2

Without Optimization With Optimization
Page Size Load Time Size Load Time
ExtJS Grid 3.2m 3.02s 3.2m 3.15s

It changed the total number of GET requests on the page from 38 to 33.

A Better Understanding

Initially, I was surprised that it didn’t make a noticeable difference in the second database, so I looked into it further and found that it is intended to improve the loading of dojo modules. It is not going to help with any external javascript libraries that you include in your application. (Quite frankly, they should already be optimized for you.)

Here’s how the What’s new in Domino Designer 8.5.3 page in the DDE help file describes it:

For performance reasons, the XPages runtime now features a new option that dynamically aggregates multiple Dojo modules, or multiple CSSs into a single file. This results in the following performance improvements:

  • a decrease in requests sent from the browser to the server
  • an increase in user performance, particularly in the context of networks with high latency
  • an increase in the speed of JS/CSS parsing from the browser
  • the freeing up of server connections to fulfill other requests

As an extreme example of the saving, let’s say the XPages Extension Library is using the page DWA_ListView.xsp. Without the aggregator enabled, 82 requests are made to the server. With the aggregator enabled, the count decreases to 6 requests, including the Ajax request that gets the data. Also, a test run on processing time might see changes from ~4 sec to ~800 ms.

Your results?

Of course, your mileage may vary. I see that Julian Buss had impressive results with a test, but I haven’t seen a lot documented.

If you’ve tested this out, what kind of results have you seen?

Data Table (HUH) – What is it good for?

With apologies to Edwin Starr*, this is a question that I’m pondering.

I haven’t heard much about the Data Table control (aside from the coverage in the Mastering XPages book), but I’m in the process of working through several display controls in XPages to make sure I know them well enough to make the best decision for each application that I develop. (Foreshadowing alert — look for information on additional controls in the near future.)

Creating a Data Table

If you drag a data table control onto an XPage or custom control, this is what you get by default:

<xp:dataTable id="dataTable1" rows="30">
  <xp:column id="column1"></xp:column>
  <xp:column id="column2"></xp:column>
</xp:dataTable>

There are three rows displayed in the XSP editor for the header, body, and footer, respectively.

It’s essentially the shell of a table that you need to manually configure by adding your own controls and binding them. This makes it much more like a repeat control. Compare that to a view panel, where you are prompted for a data source and all of the selected columns are set up and bound automatically.

On the Data Table subtab of the Properties panel, you can select a data source (view, document, or object data source, if you have the extension library or UP1), set the number of rows to display (Repeat limit), set the variable to programmatically access each row (Collection name), and set the variable to access the row number (Index name).

DataTable_2

The Collection name is necessary because there would be no other way to access each row to bind data. You can use expression language or SSJS to bind the values to underlying view columns, but, according to the Mastering XPages book, view columns with dollar signs ($) in the name are problematic with EL, so watch out for that. For cases when you can use EL, it’s easy enough to just pick the column name based on the Collection name variable.

DataTable_5

On the Display subtab of the Properties panel, you only have two options: Show pager in header and Show pager in footer. Once you select one or both of those options, you will get a pager control for the control, which you can modify.

DataTable_3

On the All Properties subtab of the Properties panel, under ‘data’, you can see that there are very few options for working with the data. No way to search or filter or set a start key.

DataTable_4

 

The Default Result

Here’s what it looks like when I add two labels and two controls bound to view columns, along with a pager in the header:

DataTable_6

My Perspective

So, it looks to me like this is a lightweight repeat control-ish way to display some view data.

You have more flexibility with the UI because you’re not locked into view columns, but it will be a manual undertaking. Repeat controls also have that flexibility and there’s a lot you can do to customize view panel columns (see this blog post or this episode of NotesIn9 for more information), so I’m not sure where this control would come into play.

The lack of options for working with the data makes it hard for me to see how this could be useful other than with a very small set of information.

Use Cases?

If you’ve ever used a data table, let me know. I’m curious to hear the use case.

* (This reference is in no way an endorsement of the song or its message — the hook just popped into my head. If you recognize it, it’s probably stuck in yours now, too!)

Return to the Last View Opened in XPages

There are many ways of handling navigation between pages in an XPages application. This post describes a technique that I’ve used to provide a way for users to return to the last (page containing a) view after closing a document. This isn’t specific to any type of data display; the concept is the same regardless of whether you use a data view, repeat control, view panel, data grid, etc.

Considerations

There are a few things to consider when deciding how to handle the page flow:

  • You often don’t want to hard-code the return destination (e.g. always force users to return to the home page of an application). Especially if coming from the Notes client, the user is accustomed to returning to the view in which they clicked a link to open a document.
  • If you’re not using a ‘back’ button, you need to know where to return.
  • ‘Back’ buttons can be problematic because, when you go back, the page isn’t refreshed the same is if it were reloaded.
  • If the user adds or modifies a document, they may wonder if the update was successful if they don’t see the update when they return to the view.
  • This isn’t a concern if your application happens to open documents in separate browser tabs, because they’ve never left the view page. However, the view will not be updated with a new or modified document if it isn’t refreshed.

The Concept

Here are the steps required for a simple solution, at a high level:

  1. When opening a view, log the page name in a scope variable.
  2. From your form button, call a function to return to the last view opened.
  3. If it cannot determine the last view opened, return to a default view. (For example, when opening a document directly from a link outside of the application.)

The Solution

To track the name of the last view page opened, add this line of code to the beforePageLoad event of all XPages that contain view controls:

sessionScope.put('lastView', view.getPageName());

To return to the last view page when closing a document, use this code:

function returnToLastView() {
	var defaultView = 'myViewPage.xsp';
	
	if (sessionScope.containsKey('lastView')) {
		context.redirectToPage(sessionScope.get('lastView'))
	} else {
		context.redirectToPage(defaultView);
	}
}

I generally put this function in a script library and call it within the logic of the back/close and save buttons.

Other Ideas?

How have you handled this in your applications?