type: utility

release: 0.0

status: in development

documentation: N/A

demo: http://view.jqueryui.com/grid/grid-spf/autocomplete.html

TODOs

• ...

1 - Description:

Work in progress covers a datasource that has an API for configuring sorting, paging and filtering, and an SPI for implementing different remote source (e.g. Flickr or Netflix API). There's also an implementation of a local datasource, which uses an array of existing data.

2 - Visual Design:

n/a

3 - Functional Specification:

A base $.ui.dataview widget, implements the API specified here. Extend to encapsulate additional features, e.g. $.ui.localDataview for working with a local array of data and $.ui.odataDataview for an implementation of a oData client.

Maps some input to an output, where the input may be a remote resource. The output can feed into other controls, but should be handled only as a view, not as the source of the data.

Options:

• filter (Object, default: null)
• keys reference property names, values specify what to filter with
• $.Widget.option method supports nested getters and setters, very useful to set a single field filter directly
• Set to null to remove all filters, set a single key to null to remove just that filter 
• Value can be anything, as long as the dataview implementation supports it.  
• examples: 
• .option( "filter.price", { value: 5, operator: ">=" } ) to filter by price greater or equal than 5
• .option( "filter.price.value", 10 ) to update the price filter to 10 (or set if not defined already)
• .option( "filter.price", null ) to remove the price filter; if its the last filter, the filter option is also set to null
• .option( "filter", null ) to remove all filters
• .option( "filter", { price: {...}, name: {...} } ) to set multiple filters, removing existing ones 
• .option( "filter.price", [  { value: 5, operator: ">="  }, { value: 10, operator: "<=" } ] ) to set a range filter  
• sort (String or Array, default: [])
• a single string or array of strings, with an optional minus-prefix to indicate descending order
• examples:
• .option( "sort", "price" ) to sort price ascending
• .option( "sort", "-price" ) to sort price descending
• .option( "sort", [ "EndTime", "-Price" ] ) to sort on EndTime ascending and then Price descending  
• paging (Object, default: { limit: null, offset: 0 })
• limit and offset
• examples:
• .option( "paging", { limit: 10, offset: 25 } ) to load 10 items per page and skip 25 items
• .option( "paging.offset", 50 ) to skip 50 items  

Methods:

• page( [index] )
• Get or set the current page, starts with 1 (not 0)
• detail on arguments, including types and behaviour for optional arguments
• Examples: 
• .page() returns the current page index by calculating it from limit and offset
• .page( 5 ) sets offset to match page five, based on the limit 
• totalPages
• returns the number of pages, by calculating it from totalCount and limit 
• refresh( [successCallback, errorCallback] )
• refresh the dataview, usually called after changing options 
• accepts success and error callbacks, for one-off events
• .refresh(function() {
    client.response( this.result )
  }) 

Events:

• request
• a the start of a refresh
• use to show a loading indicator 
• response
• at the end of a refresh, usually after data was received
• use to shop a loading indicator, rerender views 

4 - Markup & Style:

n/a

5 - Latest version of plugin:

http://view.jqueryui.com/grid/ui/jquery.ui.dataview.js

6 - Open issues being discussed

• What should the signatures for the success and error callback look like (when passed to refresh)?
• What event should get triggered when the request fails? Just request/response isn't enough.