type: widget

release: 0.0

status: in planning

documentation: N/A

 

 

---

 

1 - Description:

 

A grid is essentially an HTML table that has additional features like re-sizable columns, fixed header (only body scrolls), remote sorting, filtering, search, pagination, direct editing, hierarchical rows, and much more.

 

In detail, a grid is usually used to connect a backend API that prepares a set of information in JSON or XML form to a 'live' Ajax frontend/table. Therefore, the grid has to support remote sorting, filtering and pagination.  At a later state, client side sorting/filtering can be added - this is fairly difficult, since all the logic has to be implemented in the frontend.

 

Most users also assign actions to the actual information in the grid. In order to make it possible to select a certain row, the grid features a multiselection as you would expect in file managers like Windows Explorer. Using the selection, the grid can show or highlight related action buttons at the right of the row - by default edit and delete, where edit transforms the grid's content into seperate inputs, and delete simply deletes the row with an optional warning. Also supported could be a way to add a new row.

 

The grid makes heavy use of other widgets and utilities, most noticeably Selectable to make rows keyboard+mouse selectable, Resizable to make the whole grid panel and seperate columns resizable and Menu to create possible toolbars and their associated dropdown menus.

 

One thing to consider for the grid (and many other future UI plugins) is that HTML 5 provides detailed specs for these widgets that we should seriously consider using as a blueprint for our plugins. If we shared similiar naming and conventions, it will provide a cleaner interface in the future when we all have to support both the HTML 5 version (where available) and the JS-based UI plugin verison on the same site (i.e. use the native HTML 5 if availble, fall back to JS if not supported).  The other benefit is that these specs have been refined by a large group of people so they are fairly mature and there may be no need to reinvent the wheel. Thoughts?

http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#datagrid

 

jQuery plug-ins:

 

http://www.trirand.com/jqgrid/jqgrid.html (ThemeRoller-Ready!)

http://github.com/mleibman/SlickGrid

 

http://reconstrukt.com/ingrid/

http://www.datatables.net

http://tablesorter.com (was part of early versions of UI, got dropped)

http://flexigrid.info/ (Seems dead)

 

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

(Detailed descrition of how the script will be structured: defaults, options, architecture, extensibility, etc.)

 

Features of the alpha implementation Paul did:

 

•  Uses ui.grid.datamodel.js to fetch JSON data
• Uses ui.selectable.js to make rows multiselectable (and navigable) using keyboard+modifiers+click
• Remote pagination
• Remote sorting (by clicking on column headers)
• Display of total rows
• automatic scroll adjusting while navigating using the keyboard

 

 

Details from April grid planning session:

 

Grid usecases

 - Enhance a table with local sorting (ala wiki.jqueryui.com  Overview table) - applicable for Progressive Enhancement * (+10 hours)

 - Build a CRUD interface to a  single table (page, sort, filter, create) aka Spreadsheet * (+20 hours)

 - Reporting views (page,  sort and filter rows, reorder and filter columns)

 - Email client (select rows  for archiving, click to open thread - GridTree!) - applicable for  Progressive Enhancement * (+30 hours)

 - Netflix queue (maybe)

 - Checkbox selection

 - Dynamic columns -  Teacher/Student grades * (+10 hours)

 - Calculate values based upon selected columns

 - User list - multi-select -  show multiple user information (master/details with multiple) * (+25  hours)

 - A  chart that renders from a data store - with cell editing * (+30 hours)

   (example http://dwpe.googlecode.com/svn/trunk/charting/vanilla.html)

 - Box selector range of  cells (highlight on a chart)

 - grid with empty row at bottom for new item creation by  entering data into any (already editable) cell. New empty row is created  as soon as editing starts in cell. Allows for super-fast item creation  with down-arrow and typing in one column

Other usecases

   - Live search * (+15  hours)

   -  Data-bound list

   - Autocomplete * (+15 hours)

   - Paging (for search  results)

   -  Spreadsheet with arbitrary cells and spreadsheet formulas

   - Combobox

   - Tree

   - Chained Selects

   - Image grid, Floated  images grid with infite scroll and width resizing

   - Coverflow (images)

   - Carousel (images)

   - iTunes

   - Hotel / Travel UI (like  kayak.com)

 

Goals for the Grid

 - Modular/Extensible

 - Scalable (# of rows -  1,000,000, # of columns - 256)

 - Build off of existing markup

 - Themable (ThemeRoller  ready)

 -  jQuery UI Widget

 - Reuses jQuery UI interactions and jQuery UI widgets

 - Accessible (keyboard,  ARIA, focus management)

 

markup/css statics: http://jquery-ui.googlecode.com/svn/branches/labs/grid/tests/static/grid/default.html

 

<div id="test" data-ui-dataType="currency"></div>

$("#test").sortable();

$("#test").sortable({  dataType: "currency" });

 

<input type="submit"  data-ui-icons.primary="ui-wrench" />

Same as? $(":submit").button({  icons: { primary: "ui-wrench" } });

 

<table>

<thead>

<tr>

  <th data-ui-sort="desc"  data-ui-dataType="currency" data-ui-hidden="false">Name</th>

</tr>

 

[

     { title: "Name", sort: "desc", dataType: "currency", hidden: false,  sortable: true, sorted: "desc", sortedIndex: 1 }

]

 

columns: [

   {

       id: String

       label: String,   

       dataType: String,

       sortable: Boolean

       sorted "(asc|desc)",

       sortedIndex: Integer,

       visible: Boolean

    }

]

 

 - Data Model (100 hours)

   - Dataset, Column, Item,  Field

   -  Data Model is an object that's instantiated and holds the datastore and  element list

    - Ability to specify the name of the ID on the table -  data-ui-id="MyID"

   - Ability to specify the ID on a row data-ui-id="1234"

   - Provide _default type

   - We need to support  multiple elements representing a single "row"

   - Initialization

     - Init the data

       - An array of data

       - A string pointing  to a URL

        - A function with a callback - callback gets passed an array

       - DOMElement or  jQuery Set - run the extractor functionality

     - Need a data model  ready event

    - Data Extractor

     - .datastoreAttributes .columnAttributes (both arrays)

     - Snap in new  extractors: jQuery.dataStore.extractor.table = function( elem,  dataStoreObject ) { // Init columns // Init metadata // Extract row data  };

        Builtin: _default

     - Extractors populate .columns, .data?, and misc metadata  properties

      - Tables

        - Extract table metadata

       - Extract header names (IF thead, get columns, IF NO  thead, get ths from first, IF NO ths use indices).

       - Extract row data -  completely up to the extractor

     - Lists (or anything else)

       - Extract element  metadata

        - No headers to extract

     - Load Table From XML

     - Remember that data loaded from server  could have null fields

     - Figure out a syntax for XML and JSON loaded from the  server

 

   dom element -->  $(domElement).data("data-row-id") // uuid?

 

   null == do it all

   id == do it to single row

   array<id> == do it  to each id

    dom element -> id

   array<dom elements> -> array<id>

   jquery set ->  array<dom elements> -> array<id>

   number = row at offset #

   number, number = row  range from offset to offset

   array<number> = selection of items at row numbers

 

    jQuery("#someRow").dataStore("hide");

 

   if (  domElement.data("data-row-id") ) { // Must be of type string not number!

      $(this).closest(":datastore").dataStore("hide",  domElement.data("data-row-id"));

   }

 

   hide

   remove

   delete (?) sort (?) - should be implemented by other plugins

   show

   refresh

 

   - Elem store should be  populated when data is loaded/refreshed.

 

   Need a way to hook in to  the render to post-process

 

   // Example of how .dataStore will store the actual data on  an element

     $("#display").data({

        "elemStore", [ .... ],

        "dataStore":  refToDataStore,

        "viewTemplate": "...."

    })

 

    // Attaching a Data Store  to a couple data store views

    $("ul, #display").dataStore( myDataStore );

 

    // Watching for when a  few users are selected in one data store view

    $("ul").bind("selected",  function(e){

         // And updating another data store view with the results

         $("#display").dataStore("show", $("ul li:selected"));

    });

 

    // When nothing is  selected, hide the details data store view

     $("ul").bind("unselected", function(e){

         $("#display").dataStore("hide");

    });

 

   - A way to invalidate the entire data store

     .dataStore("remove")

 

   - A way to load chunks of  the data store (either from local or from remote) needs URL mapping

 

   Row number is the position  in the data set / position in the set on the server

   Row ID is a unique  identifier (used for editing, saving, etc.)

 

   .addClass("indicator")

   // Internally, updates  individual rows (merges the two objects for each row)

   // Then calls refresh on  all the rows (e.g. "refresh", 0, 9)

   .dataStore("update", 0, 9, object, {

      success / error /  timeout

       .removeClass("indicator")  

      //call refresh on other data store view

    }) // needs to support  array<object>

    // or .dataStore("refresh") on other data store view

 

   // Publish some events:  updating, updated, update-error 

 

   - A way to update existing records

     - Communicate changes to  a server

 

   - A way to update the  rendered view of a record

     $("#somerow").dataStore("refresh")

      $("table").dataStore("refresh") // refresh elemstore

 

 - URL Mapping

   - Use a template (?)

 

   function urlMapper( options ) {

    // options.offset

    // options.pagesize

    // options.columns = [

    //    { id: "name",  label: "Name", sorted: "asc", sortedIndex: 2, filter: "John" },

    //    ...

    // ];

   return "http://example.com/?offset={{offset}}&pagesize={{pagesize}}&sort={{column?}}&dir={{dir}}";

 }

 

 - Type (i18n/l10n) (30-40 hours)

   - Any plugin that uses these should have a 'refresh' to  reload the UI controls with the right values.

   - View (Number ->  String, e.g. 5000 - "5,000")

   - Read ("5,000" -> 5000)

   - Detect ("5,000" ->  "Number")

    - Edit (Produce Markup?)

     - Trigger an event when the change is complete

   - Filter (if it's a date -  datepicker)

    - Validation

   - Types

     - Currency

     - Number

     - Date

     - Time

     - Combobox (autocomplete - pass in values or  pre-population from existing values)

   - http://wiki.jqueryui.com/i18n

   - http://forum.jquery.com/topic/locale-information-should-be-separated-from-plugins

 

jQuery.types.aftertoday = {

  type: "date",

  options: { }

};

 

 - Zero Feature (50-60 hours)

   - Creating/populating the  titlebar from caption

   - Loading data from the table

   - Set column width  (defaults to auto, have an 'equal' option, and specify width)

   - Div around both tables,  can support horizontal scrolling

   - Set table height (data-ui-height?) can be a  pixel or 'auto' (auto expands to full contents)

     - If this is not  specified, then we should expand height/width (needs investigation)

   - Trimming table cell  contents to keep them from wrapping

   - A way to highlight a column explicitly

   - A way to refresh the  table or an individual row

   - Alignment of columns

   - Ability to Show Row # in a column (dynamic  column)

   -  Theming

      - Hover Row / Hover Column / Hover Cell

     - Striping

     - If height is  specified, and row body height could have scrollbar

 

 

 

 - Selection (80-100 hours)

   - UI styling needs more  detail (focus / active / selected)

   - Merge with existing Selectable  functionality into new Selection plugin

   - Event for when selection  occurs and a data method for accessing all selected items

   - Mouse Options:

     - Drag and select  multiple

      - At most one can be selected

     - Making a new selection clears any  previous selection

     - Clicking to select an already selected does not toggle

     - Should  checkboxes/radios be injected/used for the user to interact with

    - Modifier keys

      - Shift: Expands  continuous selection range

      - Meta (Mac-Cmd/Win-Ctrl): Toggles single item without  affected other selection(s) where the click without the modifier would

   - Keyboard navigation

     - Up/Down or Left/Right

 

 - Sorting (20-30 hours)

   - Top-level  data-ui-sortable="true" on table

   - Specify the column types (way to specify  types)

     -  Specified as an array of values

     - PE: data-ui-format="currency" vs.  data-ui-l10n-format="currency"

   - Specify the starting sort direction (desc,  asc)

     -  data-ui-sortdir="desc"

   - Enable/Disable Sorting on a particular column

     -  data-ui-sortable="false"

   - Depends upon Type(i18n/l10n) plugin

 

 - Paging (60-80 hours)

   - For Ajax-loading

   - # of items per page (specified and/or user  customizable)

     - data-ui-pagesize

   - 1 2 3 ... 1234 (links) OR [ 1 ] of 1234 OR  select [ 1, 2, 3 ] OR button to load more

     - Need to know the total  # of records

     - data-ui-totalrecords

     - Implement with templates

   - First / Last Links

   - Next / Prev Links

     - Need URL mappers -  given a page # and a # of records - give us a URL (!)

   - Scrolling

     - Hit (near-)bottom,  load more (alternative to button - just auto-load)

     - Show full scrollbar  (as if everything was loaded) and dynamically load more

       - Clean up old  results

        - Completely removes need for links or button

       - How does expandable  rows affect this?

   - Publish 'pagination' event (can be return false to stop  the user)

      - How do you rebuild the UI later on if changes were made?

   - Keyboard Navigation

     - Page Up / Page Down

 

 - Editing (120 hours)

   - Can make column  editable="false"

 

    .dataStore("edit"[, ID[, column]]) // How do we specify true or "date"?

   .dataStore("cancelEdit"[,  ID]) // remove dom nodes from editing, call refresh

    // All of these are  stored on the data store view

   editing = {

     "ID1": true,

     "ID2": "date"

   }

   editing = true;

   editing = "date";

   // Wipe out state on  refresh

    editing: {}

 

   Check editing state on  pagination

 

   .dataStore("update", ID,  dataObj?)

    Need to specify how frequently to update

 

 

       - Row-level blur event  (focusenter, focusleave)

     - Enter says done with row editing, moves to next row -  go to first column

     - Tab says done with cell editing, moves to next cell

     - Click on cell - turns  on editing for whole row (or just cell, if only that cell is on)

     - Make sure not to  conflate selection with triggering editing - use checkboxes for  selection when doing editing as well

 

   - Inline Edit Row

     - Generate 

 

   - Click to Edit Cell

   - Entire Table Editing

   - Column Editing

 

 

   - Add New Item POST

     - Dialog for adding in  an item?

      - Will return data item in format we're using (must contain ID)

     - Update the items with  the new IDs

    - Delete Row POST

     - Works like update (success / error / timeout)

     - On success, remove  and refresh

    - Reorder Row // Useful, will not work on at first

     - Communicate an  insertBefore event?

 

   - Event for when column  is changed, event for when entire row is done being edited

   - Ways of triggering  those events (columnchange and rowdone?)

   - Do we have a submit  button - if not handle enter key

 

   - Inputs, selects can be used in the page to trigger PE  editing

   -  Depends upon l10n plugin

    - Theming

      - Active Row / Active Cell / Editing Row/Cell / Error  Row/Cell

 

Default: <tr>{{each  columns}}<td>{{field this}}</td>{{/each}}</tr>

Custom:

<fieldset>

  <legend>${firstname}  ${lastname}</legend>

  <label>First name: </label>{{field "firstname"}}  {{editing "firstname"}}Uppercase!{{/editing}}

  <label>Last name:  </label>{{field "lastname"}}

</fieldset>

// Note: Names must be exact  matches from header names

 

$("#row5").dataModel("refresh");

 

name -> StringFilter -> "John"

city -> StringFilter ->  "Boston"

date  -> StringFilterEdit -> <input type="text" ....>

 

Need template methods:

  - field

  - editing

  - editable

 

 -  Filtering/Searching (40-60 hours)

   -  data-ui-filter="string|boolean|number|..."

   - Would be good to have a  way to have an external set of controls which you can use to filter

   - Have an extra row with  the filter controls

   - Need main function to filter, will AND multiple filters  whether on single column or multiple columns by default (can be  overidden)

    - Per column template and filter function definition

   - Filter Types:

       - text (exact- or  like-match), with optional Autocomplete support, based on column content

       - boolean  (true/false, checkbox or radio button)

       - numbers (exact  match, greater-then, less-then, range)

           - if min or max,  or both, are known, offer a slider

       - date (exact match, greater-then,  less-then, range)

       - select (checkboxes for distinct column values - none  checked, show everything, otherwise display all checked matches)

       - mulit-select,  populated with values from the column

 

[ Select =, <, >, <=>? ]

 

 -  Hide/Show Columns for Grid (20 hours)

   -  data-ui-visibility="hidden" on the  column header (Implements aria  hidden)

   -  Gear/button  above scrollbar for menu to hide/show columns

 

 - Column Reordering for Grid (20-30 hours)

   - Drag and Drop

   - Separate data structure  for header order

 

 - Column Resizing  (30-40 hours)

     - Some vertical indicator denoting the edge being dragged

     - Only change width on  the end of the drag

     - Try to use colgroup styling.

       #mygrid  td.ui-column-name { width: 160px; background-color: #F5F5F5; text-align:  right; }     

       <tr><td class="ui-column-name">My  Name</td>

 

 - Column Totals (15 hours)

   - Ask server for details?

   - Show on selection

 

 - Formulas (15 hours)

   - Compute row on update

   - Can only be done on  static tables when sorting

 

 - Row Grouping (30  hours)

    - Need template for the grouping plugin

   - A way to specify the  label to associate with the value

   - Hook to a specific column  data-ui-grouping="true"

   - Requires the existance of multi-column sorting (sort on  group, column)

   - Collapsing? Number totals?

 

 - Grid Tree (60-80 hours)

   - data-ui-parentid="pid"

   - Based upon the filter  plugin, select based upon parentid

   - Styling a particular column (should  probably be specified)

   - Requires the existance of multi-column sorting (sort on  pid, column)

    - Should not use paging with this

   - Dynamically insert elements into the right  part of the tree when dynamically loaded

 

ARIA Spec for tree grid http://www.w3.org/TR/wai-aria/roles#treegrid

from Mozilla site: https://wiki.mozilla.org/Accessibility/TreeGrid

 

 

http://mleibman.github.com/SlickGrid/examples/example3-editing.html

 

Why not use another grid?

 - Is not modularized or extensible

 - Is not written in the UI  style

 

Comparison with other grids

• http://www.trirand.net/ (commercial)
• http://trirand.com/blog/jqgrid/jqgrid.html (GPL/MIT)
• http://wiki.github.com/mleibman/SlickGrid/examples
• http://reconstrukt.com/ingrid/
• http://www.datatables.net
• http://flexigrid.info/
• http://tablesorter.com (was part of early versions of UI,  got dropped)
• TreeTable:  http://www.hanpau.com/index.php?page=jqtreetable
• dojo  http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/grid/tests/test_edit_dijit.html

 

 

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

     (Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )

 

     4.2 Recommended transformed HTML markup

 

     First pass: http://jquery-ui.googlecode.com/svn/branches/labs/grid/tests/static/grid/default.html

 

     4.3 Accessibility recommendation

 

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

 

     4.4 CSS & Theme

 

   First pass: http://jquery-ui.googlecode.com/svn/branches/labs/grid/tests/static/grid/default.html

 

---

 

5 - Latest version of plugin:

http://jquery-ui.googlecode.com/svn/branches/labs/grid/tests/visual/grid.html

 

---

 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 

---