This project is read-only.

mvcct.Queryable, mvcct.oDataQueryable, mvcct.upshotQueryable, and mvcct.localQueryable

Requires MVCControlToolkit.Controls.Core.x.x.x.js, MvcControlToolkit.Bindings-x.x.x, knockout.x.x.x.js, knockout.mapping.x.x.x.js,  MvcControlToolkit.Utils-x.x.x.js, and MVCControlToolkit.JsQueryable-x.xx.min.js.

MvcControlToolkit.Utils-x.x.x.js must be placed AFTER knockout.x.x.x.js, since it checks if knockout.js features have been installed.

There are several implementations of the abstract javascript class mvcct.Queryable:

  •  mvcct.oDataQueryable builds query against oData sources. An instance of this class can be built with:
    mvcct.oDataQueryable(link, [fop=mvcct.$$.and], [options], [negate=false])where:
    • link, is the url of the oData source that can be also a  ApiController method returning anIQueryable.
    • fop is the logical operator that will be used to combine the root conditions. A condition can be either a simple condition like EqualStartsWith, or a complex condition obtained, in turn,  by combining other conditions with another logical operator.  The allowed logical operators are: mvcct.$$.and and mvcct.$$.or.
    • negate is a boolean. If true the whole filter condition is negated.
    • options, is an object containing some options. The allowed options with their default values are:
      { includeTotalcount: true,
      connector: '?',
      skip: '$skip=',
      top: '$top=',
      orderby: '$orderby=',
      filter: '$filter=',
      desc: 'desc',
      asc: 'asc'    } 
      They are just the keywords used to build the url that will be passed to the oData source, plus two more options, includeTotalCount, and connector. Normally we don't need to change the keywords since they are integral part of the oData standard. connector is put between link and the query parameters that compose the oData query. Its default is "?", however if link contains other query parameters we must pass the value "&" for this option. If includeTotalCount is true, themvcct.Queryable will ask the oData source to provide also the total count of all entities to improve the paging experience. Unluckly the ApiController implementation of the oData protocol doesn't support this option, so the total number of entities will be never returned. However, it is quite easy to build an Action Filter to overcome this problem.
  • not supported anymore starting from release 2.4.mvcct.upshotQueryable builds a query that will be passed to an upshot Datasource. It is useful when we would like to use upshot and simultaneously to import query informations from the Mvc Controls Toolkit, sorting, filering and paging controls. An instance of this class can be built with:
    mvcct.upshotQueryable(dataSource, fop, options, negate), where:
    • fop, and negate have the same meaning as in the mvcct.oDataQueryable class.
    • dataSource is the upshot DataSource that will be used to issue the queries.
    • options is an object containing some options. By now just one option is allowed:
      {  includeTotalcount: true } 
      That is completely analogous to the option with the same name of the mvcct.oDataQueryable 
  • mvcct.localQueryable builds a query against a javascript array. An instance of this class can be built with:
    mvcct.localQueryable(array, fop, negate), where:
    • array, contains the array to query. The result of the query will be another array, while the original array will not be modified.
    • fop, and negate have the same meaning as in the mvcct.oDataQueryable class.
  • mvcct.html.forms.queryable, builds a query by using all Mvc Controls Toolkit queries related controls (like pagers and sort buttons) to build a dynamic form or an ajax post that is submitted to the server. Available, only if the Data Moving Plugin is installed.

For a quick start on the  mvcct.Queryable see the tutorial: Mvc Controls Toolkit Support to Mvc4 WebApi. The tutorial, and the associated code  use the mvcct.oDataQueryable. A code sample on the mvcct.localQueryable is contained in the Advanced JSon Communication file in the download area

Once created, the interface to operate on all implementations of the mvcct.Queryable will be exactly the same:

  • isLocal; returns true if the mvcct.Queryable works with local data sources.
  • setPaging(page, pageSize); Specifies current page and page size.
  • importPager(pagerId, pageSize): imports the paging data contained in the ClientPager whose id is pagerId. The id of the  ClientPager can be obtained with the PefixedId helper.
  • addSort(field, desc, enabled): if enabled is true adds a new orderby clause to the order being built. field is the name (actually a string expression) of the property, and the boolean desc specifies if the order is descending.
  • resetSorting():clears all previously added sorting clauses, so that a completely new sorting can be started.
  • addCondition(operator, value1, value2, enabled): if enabled is true a new filtering condition is added to the filter being built. All filter conditions are combined with the currently active logical operator. The initial logical operator is specified in the constructor of the Queryable. A different logical operator can be specified each time we build a complex condition made of several sub-conditions with the help of the open and close methods (see later), value1 is the property to be constrained by the condition,  value2 the second argument of the comparison , and operator is the condition operator  that is one of:
    • mvcct.$$.eq, mvcct.$$.ne, mvcct.$$.gt, mvcct.$$.ge, mvcct.$$.lt, mvcct.$$.le;
    • mvcct.$$.startswith, mvcct.$$.endswith
    • mvcct.$$.substringofInv; that is the Contains operator.
    • mvcct.$$.substringof; that requires the property value is a substring of the value2 argument
  • resetFilter(): clears all previously added filter clauses, so that a completely new filter can be started.
  • open(logicalOperator, enabled, negate): if enabled is true, it starts a complex condition made of several sub-conditions that will be combined with logicalOperator. If negate is true the whole condition will be negated. Its effect is opening a parenthesys in the filter expression being built.
  • close(enabled): close a previously opened parenthesys. enabled must match the enabled of the matching open otherwise the parenthesys of the resulting expression will be unbalanced.
  • importSorting(sortingString): imports all sorting information contained in sortingString. In turn, sortingString is contained in a property a the data argument of the queryChanged event that is triggered by the EnableSortingFor helper when the sorting changes. The new sorting subsitutes completely any previous sorting.
  • importSortingControl,(controlId): imports all sorting information contained in the EnableSortingFor helper whose id is controlId. The id of an EnableSortingFor helper can be obtained with the PefixedId helper. The new sorting subsitutes completely any previous sorting.
  • importClauses(filterId):  imports all filtering information contained in the DataFilterClauseFor helpers, whose id is filterId .  The id of the DataFilterClauseFor helpers can be obtained with the PefixedId helper (several of them are "attached" on the same id when they define an unique condition). The imported filter is combined  with the existing filter with the current logical operator. Thus, if we would like to substitute completely the old filter, please, call the resetFilter() method before.
  • get(): returns an object whose nature depends on the implementation of the Queryable: the oDataQueryable returns the complete url to be passed to the server, the localQueryable returns a function that once executed performs all operations specified in the query, and the upshotQueryable returns the upshot DataSource that is the target of its queries.
  • execute(callback): executes the query and passes the result returned by the server as argument to the callback. The upshotQueryable ignores the callback because the only operation performed is the refresh of the DataSource: this is enough to dispatch the server results in the right place.
  • getState() and setState(x) respectively returns an object that encodes the full state of the Queryable, and set the state of the Queryable by using a previously saved state. They are usefull to handle the Back and Forward buttons of the browsers to navigate the history of all query passed to the server.

getState and setState can be connected with the browser navigation arrows for navigating through the various queries issued. However, we need first to transform the object returned by getState into a string that we can use as value for an url parameter with something like:

encodeURIComponent(JSON.stringify(query.getState()))

A previous state can be recovered with:

query.setState(JSON.parse(decodeURIComponent(parameterValue)))

The above technique works with both the mvcct.upshotQueryable and the mvcct.oDataQueryable but it doesn't work with the mvcct.localQueryable  because the state it returns contains some functions that are created dynamically. In this case can call the native browser Html5 history handling functions: 

window.history.pushState(query.getState(), null, url)

That allows generic data to be stored in the history.

Last edited Jun 22, 2014 at 11:44 AM by frankabbruzzese, version 8

Comments

No comments yet.