MWLUG 2013
Living on the Grid – Unlock the Power of
Dojo Data Grids (AD104)
Brad Balassaitis, PSC Group
Brad Balassaitis
• Notes/Domino developer for 17 years, XPages 3+ years
• Senior Consultant at PSC Group
– XPages Develope...
Agenda
• Dojo Data Grid Control
– Creation and Default Features
• Dojo Data Grid – Additional Features
– Sorting, Opening ...
Dojo Data Grid Control
• Availability
– Extension Library
– 8.5.3 Upgrade Pack 1
– Notes 9
• Creates a Dojo DataGrid
Why use the Dojo Data Grid?
• It’s not a view panel
• Feature-rich
– Adjustable columns, storing, editing, and much more
•...
Creating a Dojo Data Grid
1. Create REST Service to provide data
2. Add the Dojo Data Grid control and bind to the REST se...
REST Service
• REST is a standard for client-server data exchange on the web
• Common method for providing data to a grid
...
REST Service - Creation
1. Add REST Service control to the page
2. Select the service type
– basics > service > + > xe:vie...
REST Service - Customization
• Compute columns
• System columns
• Roll your own
REST Service - Verification
• Set pathInfo
– All Properties > basics > pathInfo
• Test it
– Server.com/dbname.nsf/XPage.xs...
Creating a Dojo Data Grid
1. Create REST Service to provide data
2. Add the Dojo Data Grid control and bind to the REST se...
Default Grid Features
• Infinite scrolling
• Adjustable column widths
• Row highlighting
• Extended selection mode
• Sorta...
Additional Grid Properties
• rowSelector
• autoHeight
• rowsPerPage
• escapeHTMLInData
• loadingMessage
• errorMessage
• d...
Dojo Attributes
• More grid features are available, but not via properties
– e.g. Column Reordering, Grid Width
• Dojo > D...
Column Reordering
• Allows user to rearrange columns
• Set via dojo attribute
Column Reordering
• Alternate method of setting attribute
Grid Width
• By default, takes up width of containers
• autoWidth attribute sizes to the required width
• Set via dojo att...
Grid Column Properties
• label
• width
• hidden
• editable
• formatter
– Client JavaScript function to manipulate column d...
Sorting
• Automatically attempts to provide ascending and descending
sorting on all columns
• Each sort only works if enab...
Preventing Sort Options
• Attach a function to the canSort property of the grid
– Receives column index number
• 1-based i...
Opening Documents
• Link not built-in
• Row click events: onRowClick, onRowDblClick
– Client JavaScript
– Events receive a...
REST Service Output
viewJsonService viewItemFileService
Open Doc - viewJsonService
var grid = arguments[0].grid;
var index = arguments[0].rowIndex;
var item = grid.getItem(index)...
Open Doc - viewItemFileService
var index = arguments[0].rowIndex;
var unid =
REST_SERVICE._items[index].attributes[‘@unid’...
Search – Full Text
• Same steps as other display controls
1. Create search field and bind to scope variable
2. Set REST se...
Editable Columns
• Set column’s editable property to true
• Double-click cell to change to edit mode
• Save the changes – ...
Editable Columns – Field Types
• cellType property
– Cell (default) – plain text
– Select – drop-down list (compute option...
Editable Columns – Field Types
• Combo Box
1. Include module: dojox.grid.cells.dijit
2. Set cell type: dojox.grid.cells.Co...
Editable Columns – Field Types
• Multi-line Edit box
1. Include module: dojox.grid.cells.dijit
2. Set cell type: dojox.gri...
Editable Columns – Field Types
• Date Picker
1. Include module: dojox.grid.cells.DateTextBox
2. Set cell type: dojox.grid....
Editable Columns
• REST service’s save() function can accept callbacks
– Useful for displaying an error if save fails
var ...
HTML Columns
• Create custom column in REST service (or use existing view
column) with HTML content
• Add Grid Column to d...
Icon Columns
• Images don’t work as pass-thru HTML
• Requires column formatter function (client JS)
• Formatter can condit...
Dojo EnhancedGrid
• Dojo module that extends DataGrid
• Already available on the server
• Provides enhanced features via p...
Converting to EnhancedGrid
• Dojo Data Grid control creates a Dojo DataGrid
• Can modify to create a Dojo EnhancedGrid
1. ...
Converting to EnhancedGrid
1. Load the EnhancedGrid module on the page
– Resources > Add > Dojo Module
– dojox.grid.Enhanc...
Converting to EnhancedGrid
2. Set grid Dojo type to dojox.grid.EnhancedGrid
– Properties > Dojo > Dojo type
Converting to EnhancedGrid
3. Load required style sheets
– Load relative to Domino server path
<xp:styleSheet
href="/.ibmx...
Verify EnhancedGrid
EnhancedGrid Plugin - DnD
• Provides ability to drag and drop columns, rows, and cells
– Configuration object defines opti...
EnhancedGrid Plugin - DnD
1. Load the DnD plugin
– Properties > Resources > Add > Dojo Module
– dojox.grid.enhanced.plugin...
EnhancedGrid Plugin - DnD
2. Add plugin to grid as an attribute
– Dojo > Add
• Name: plugins
• Value: {dnd: {dndConfig:{}}...
EnhancedGrid Plugin - Filter
• Adds filter bar
• Up to 3 filtering rules
– Match all rules or any rule
– Select column to ...
EnhancedGrid Plugin - Filter
1. Load the Filter plugin
– Properties > Resources > Add > Dojo Module
– dojox.grid.enhanced....
EnhancedGrid Plugin - Filter
2. Add plugin to grid as an attribute
– Dojo > Add
• Name: plugins
• Value: {filter: true}
EnhancedGrid Plugin - Filter
3. Add a stylesheet
<xp:styleSheet
href="/.ibmxspres/dojoroot/dojox/grid/enhanced/resources/
...
EnhancedGrid – More Plugins
• Print
– Provides ability to preview or print grid contents
– Print/Preview “All”, Selected, ...
Dojo TreeGrid
• Provides multi-level categorization
• Can provide column totals and counts
• Extends Dojo DataGrid
– Canno...
TreeGrid - Implementation
• Programmatic – NOT the Dojo Data Grid control
1. Include required dojo modules and stylesheets...
TreeGrid – Totals and Counts
• Inline when collapsed, below when expanded
• Requires a different (but simpler) JSON model
...
TreeGrid – Data Format Caveat
• Simpler JSON format causes blank rows when used without
counts/totals
TreeGrid - Features
• defaultOpen – expanded or collapsed
• openAtLevels – auto expand all categories with less items than...
Questions?
• Data Grid Blog Series: http://xcellerant.net/dojo-grids-in-xpages
• Sample database coming to openNTF soon
• ...
Upcoming SlideShare
Loading in …5
×

Living on the Grid - Unlock the Power of Dojo Data Grids in XPages - MWLUG 2013

4,240 views

Published on

Explore the rich functionality of dojo data grids in XPages.

This presentation starts with how to create a Dojo Data Grid and REST service in XPages and discusses the features available with the standard grid.

It proceeds to demonstrate how to convert the grid to a Dojo EnhancedGrid and take advantage of additional plugins for enhanced functionality.

Finally, it demonstrates how to use a Dojo TreeGrid in XPages to create categorized grids with or without calculated totals and counts.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Living on the Grid - Unlock the Power of Dojo Data Grids in XPages - MWLUG 2013

  1. 1. MWLUG 2013 Living on the Grid – Unlock the Power of Dojo Data Grids (AD104) Brad Balassaitis, PSC Group
  2. 2. Brad Balassaitis • Notes/Domino developer for 17 years, XPages 3+ years • Senior Consultant at PSC Group – XPages Developer – Project Lead • Contact Information – Blog: xcellerant.net – Twitter: @Balassaitis – LinkedIn: linkedin.com/in/bradbalassaitis
  3. 3. Agenda • Dojo Data Grid Control – Creation and Default Features • Dojo Data Grid – Additional Features – Sorting, Opening Docs, Searching, Editing • Dojo EnhancedGrid – Conversion – Plugins • Dojo TreeGrid – Categorization – Counts and Totals
  4. 4. Dojo Data Grid Control • Availability – Extension Library – 8.5.3 Upgrade Pack 1 – Notes 9 • Creates a Dojo DataGrid
  5. 5. Why use the Dojo Data Grid? • It’s not a view panel • Feature-rich – Adjustable columns, storing, editing, and much more • Dojo is already on the Domino server • Enhanced plugins are available
  6. 6. Creating a Dojo Data Grid 1. Create REST Service to provide data 2. Add the Dojo Data Grid control and bind to the REST service 3. Add Dojo Data Grid Columns
  7. 7. REST Service • REST is a standard for client-server data exchange on the web • Common method for providing data to a grid • REST Service Control (ExtLib, 8.5.3 UP1, Notes9) – Data Access > REST Service
  8. 8. REST Service - Creation 1. Add REST Service control to the page 2. Select the service type – basics > service > + > xe:viewJsonService 3. Set the contentType to application/json – basics > service > contentType 4. Select the view – basics > service > viewName 5. Set defaultColumns to true – basics > service > defaultColumns
  9. 9. REST Service - Customization • Compute columns • System columns • Roll your own
  10. 10. REST Service - Verification • Set pathInfo – All Properties > basics > pathInfo • Test it – Server.com/dbname.nsf/XPage.xsp/pathInfoName
  11. 11. Creating a Dojo Data Grid 1. Create REST Service to provide data 2. Add the Dojo Data Grid control and bind to the REST service 3. Add Dojo Data Grid Columns
  12. 12. Default Grid Features • Infinite scrolling • Adjustable column widths • Row highlighting • Extended selection mode • Sortable columns • Multiple row entries
  13. 13. Additional Grid Properties • rowSelector • autoHeight • rowsPerPage • escapeHTMLInData • loadingMessage • errorMessage • dir
  14. 14. Dojo Attributes • More grid features are available, but not via properties – e.g. Column Reordering, Grid Width • Dojo > Dojo attributes – or • All Properties > dojo > dojo attributes
  15. 15. Column Reordering • Allows user to rearrange columns • Set via dojo attribute
  16. 16. Column Reordering • Alternate method of setting attribute
  17. 17. Grid Width • By default, takes up width of containers • autoWidth attribute sizes to the required width • Set via dojo attribute
  18. 18. Grid Column Properties • label • width • hidden • editable • formatter – Client JavaScript function to manipulate column data – Example: format to all upper case function allUpper(value) { return value.toUpperCase(); }
  19. 19. Sorting • Automatically attempts to provide ascending and descending sorting on all columns • Each sort only works if enabled in underlying view column
  20. 20. Preventing Sort Options • Attach a function to the canSort property of the grid – Receives column index number • 1-based index • Ascending sort is positive number, descending is negative – Returns true or false • Run code in onClientLoad event of page to attach function – Example: Allow even-numbered columns to sort dijit.byId('#{id:djxDataGrid1}').canSort = function(col){ if (col % 2 == 0) { return true; } else { return false; } };
  21. 21. Opening Documents • Link not built-in • Row click events: onRowClick, onRowDblClick – Client JavaScript – Events receive an argument with many properties • Code varies based on REST service type
  22. 22. REST Service Output viewJsonService viewItemFileService
  23. 23. Open Doc - viewJsonService var grid = arguments[0].grid; var index = arguments[0].rowIndex; var item = grid.getItem(index); var unid = item[‘@unid’]; var url = ‘MyPageName.xsp?documentId=’ + unid + ‘&action=openDocument’; window.document.location.href = url;
  24. 24. Open Doc - viewItemFileService var index = arguments[0].rowIndex; var unid = REST_SERVICE._items[index].attributes[‘@unid’]; var url = ‘MyPageName.xsp?documentId=’ + unid + ‘&action=openDocument’; window.document.location.href = url;
  25. 25. Search – Full Text • Same steps as other display controls 1. Create search field and bind to scope variable 2. Set REST service’s search property to the scope variable 3. Add button that triggers partial refresh on grid and REST service • Cannot sort results • DB must be full-text indexed
  26. 26. Editable Columns • Set column’s editable property to true • Double-click cell to change to edit mode • Save the changes – one line of client JavaScript – REST_SERVICE_ID.save() – Use the jsId property, if defined (otherwise id) – ** Does not work without grid autoHeight set • Undo changes – one line of client JavaScript (in theory) – REST_SERVICE_ID.revert() – Partial refresh on grid has same effect
  27. 27. Editable Columns – Field Types • cellType property – Cell (default) – plain text – Select – drop-down list (compute options w/ SSJS) – Bool – checkbox – AlwaysEdit – not a field type – RowIndex – has nothing to do with editing
  28. 28. Editable Columns – Field Types • Combo Box 1. Include module: dojox.grid.cells.dijit 2. Set cell type: dojox.grid.cells.ComboBox
  29. 29. Editable Columns – Field Types • Multi-line Edit box 1. Include module: dojox.grid.cells.dijit 2. Set cell type: dojox.grid.cells.Editor
  30. 30. Editable Columns – Field Types • Date Picker 1. Include module: dojox.grid.cells.DateTextBox 2. Set cell type: dojox.grid.cells.DateTextBox 3. Only works in Notes 9
  31. 31. Editable Columns • REST service’s save() function can accept callbacks – Useful for displaying an error if save fails var saveCallbacks = {onError: function() {alert('There was an error saving your changes.');} }; restServiceID.save(saveCallbacks); • Editable Columns work with viewItemFileService services, but require a Web Site document to allow put operations in order to work with viewJsonService • Can only edit columns mapped to a single field • Grid has a singleClickEdit property • Highlighting changes
  32. 32. HTML Columns • Create custom column in REST service (or use existing view column) with HTML content • Add Grid Column to display HTML content column • Set Grid property escapeHTMLInData = false – Not good practice – vulnerable to XSS
  33. 33. Icon Columns • Images don’t work as pass-thru HTML • Requires column formatter function (client JS) • Formatter can conditionally return <IMG> tag • Does not require the escapeHTMLInData property – Much more secure for all passthru HTML
  34. 34. Dojo EnhancedGrid • Dojo module that extends DataGrid • Already available on the server • Provides enhanced features via plugins • Check for available features based on Domino/Dojo version – Domino 8.5.3 – Dojo 1.6 – Domino 9 – Dojo 1.8 – http://dojotoolkit.org/reference- guide/1.6/dojox/grid/EnhancedGrid.html
  35. 35. Converting to EnhancedGrid • Dojo Data Grid control creates a Dojo DataGrid • Can modify to create a Dojo EnhancedGrid 1. Load the EnhancedGrid module 2. Set the grid Dojo type 3. Load required style sheets
  36. 36. Converting to EnhancedGrid 1. Load the EnhancedGrid module on the page – Resources > Add > Dojo Module – dojox.grid.EnhancedGrid
  37. 37. Converting to EnhancedGrid 2. Set grid Dojo type to dojox.grid.EnhancedGrid – Properties > Dojo > Dojo type
  38. 38. Converting to EnhancedGrid 3. Load required style sheets – Load relative to Domino server path <xp:styleSheet href="/.ibmxspres/dojoroot/dojox/grid/resources/Grid.css"> </xp:styleSheet> <xp:styleSheet href="/.ibmxspres/dojoroot/dojox/grid/resources/EnhancedGrid.css"> </xp:styleSheet>
  39. 39. Verify EnhancedGrid
  40. 40. EnhancedGrid Plugin - DnD • Provides ability to drag and drop columns, rows, and cells – Configuration object defines options – Add a row selector in order to drag and drop rows • Usage 1. Select content to drag 2. Release mouse button 3. Click on the data and drag • IMPORTANT: When cells are moved, changes are automatically saved
  41. 41. EnhancedGrid Plugin - DnD 1. Load the DnD plugin – Properties > Resources > Add > Dojo Module – dojox.grid.enhanced.plugins.DnD
  42. 42. EnhancedGrid Plugin - DnD 2. Add plugin to grid as an attribute – Dojo > Add • Name: plugins • Value: {dnd: {dndConfig:{}}} – All selection types enabled by default
  43. 43. EnhancedGrid Plugin - Filter • Adds filter bar • Up to 3 filtering rules – Match all rules or any rule – Select column to filter – Select matching condition (is, contains, starts with, ends with…) • No coding required!! • Results are sortable
  44. 44. EnhancedGrid Plugin - Filter 1. Load the Filter plugin – Properties > Resources > Add > Dojo Module – dojox.grid.enhanced.plugins.Filter
  45. 45. EnhancedGrid Plugin - Filter 2. Add plugin to grid as an attribute – Dojo > Add • Name: plugins • Value: {filter: true}
  46. 46. EnhancedGrid Plugin - Filter 3. Add a stylesheet <xp:styleSheet href="/.ibmxspres/dojoroot/dojox/grid/enhanced/resources/ claro/EnhancedGrid.css"> </xp:styleSheet>
  47. 47. EnhancedGrid – More Plugins • Print – Provides ability to preview or print grid contents – Print/Preview “All”, Selected, Custom • Exporter – Provides grid data for export – you handle the rest – Export “All”, Selected, Custom • Menu – Context menus for columns, rows, cells, selected – Build with dijit menus/menu items
  48. 48. Dojo TreeGrid • Provides multi-level categorization • Can provide column totals and counts • Extends Dojo DataGrid – Cannot use EnhancedGrid plugins • Poor documentation • Apparently cannot use Dojo Data Grid control
  49. 49. TreeGrid - Implementation • Programmatic – NOT the Dojo Data Grid control 1. Include required dojo modules and stylesheets 2. Set XPage property to parse dojo on load 3. Define a <div> to render the grid and set the size 4. Execute code onClientLoad to configure and generate the grid 5. Provide data for the grid (XAgent) – Complicated format ... { id: 'AS', name:'Asia', type:'continent', children:[{_reference:'CN'}, {_reference:'IN'}] }, { id: 'CN', name:'China', type:'country' }, { id: 'IN', name:'India', type:'country' }, ...
  50. 50. TreeGrid – Totals and Counts • Inline when collapsed, below when expanded • Requires a different (but simpler) JSON model {id:'AK', type: 'state', state:'AK', numPeople: 3, childItems:[ {id:'B3093953178C98E905257838007ABC48', firstname:'Bella', lastname: 'Martin', valueToAdd: 2}, {id:'7FDB9CCDE7D6923E05257838007ABC1E', firstname:'Brian', lastname: 'Leggett', valueToAdd: 2} ] }, • Add an aggregate property – Set to “sum” or “cnt” – Numeric columns handled properly – Text columns concatenated – Formatter functions can modify the display (and hide text)
  51. 51. TreeGrid – Data Format Caveat • Simpler JSON format causes blank rows when used without counts/totals
  52. 52. TreeGrid - Features • defaultOpen – expanded or collapsed • openAtLevels – auto expand all categories with less items than the defined amount – Can accept an array for multiple levels of categorization – Doesn’t work with ForestStoreModel • expandoCell – column in which the expand/collapse icon displays
  53. 53. Questions? • Data Grid Blog Series: http://xcellerant.net/dojo-grids-in-xpages • Sample database coming to openNTF soon • Twitter: @Balassaitis

×