Extending functionality
protocol details
data fetching
POST
Command parameters:
- none
GET
Command parameters:
- connector=true - flag of connector based request. The flag is set automatically, once you include the connector.js file on the page.
- dhx_colls=field1,field2…fieldN - optional, can contain a list of fields for which collections will be requested. dhtmlxGrid use such parameters to request data for combo columns and select filters ( such requests are executed just once , for initial data loading)
some.php?connector=true&dhx_colls=2,3
- dhx_sort[field]=directon - instruct server-side connector to sort dataset by defined field
some.php?connector=true&dhx_sort[2]=asc
- dhx_filter[field]=mask - instruct server-side connector to filter dataset by defined field
//filter by %test% some.php?connector=true&dhx_filter[2]=test
grid specific
Requsting part of data (Dynamic Smart Rendering or Dynamic Paging)
GET
- posStart - position from which data is requested
- count - count of requested rows
combo specific
Requsting part of data
GET
- pos - position from which data is requested
Filter by label field
GET
- mask - filtering mask for label field
tree/treeGrid specific
Requesting branch of tree
GET
- id - parent id for requested branch
data updating (using dataProcessor)
GET
- editing=true - mark of dataprocessor-based call
POST
- ids - list of updated records
- [id]_[property] - for each field inside updated record related field in POST is generated
- [id]_!nativeeditor_status - action type
porting connectors to another platforms
when should you use it?
The existing version of connectors supports a limited set of server platforms. In case database/framework/scripting language you'd like to use is not supported, you can port existing solution on your platform.
when shouldn't you use it?
Connectors are just wrappers around existing grid functionality, that's why if you need to use this solution once, you would better use grid API directly, instead of creating your own server connector.
implementation levels
Connector supports many operations implementing data processing. There is an opportunity to provide supporting basic operations and ignore higher-level ones, in case they are not used in your project.
basic support
Data assignment is basic connector operation which proceeds in the following way: connector connects to database, selects data and outputs this in stdout using XML format of the current component.
Key points:
- XML-data input must occur only after sending the appropriate http-header
- XML must start with XML declaration containing the appropriate data coding
- None other content must be sent to stdout (neither before nor after sending data by connector)
header("Content-type:text/xml"); print("<?xml version='1.0' encoding='utf-8' ?>"); print(xml_formatted_data);
- incoming parameters - there are no any;
- restriction for output data - there is no restriction.
Basic implementation allows to use resulting script as input parameter for load()/loadXML() methods.
filtration and sorting
At this stage, the number of supported operations is considerably extended: you are allowed to use #connector_text_filter, sorting type 'connector' and filter/sort data through URL manipulations.
Key points:
- An obvious advantage of this functionality can be estimated only for operating with grid, for other components such functionality doesn't seem to be necessary (it can be used only to filter/sort data through URL manipulations).
- The level 'uses' code from the previous one. Beware, that now, before using XML, data is sorted/filtered according to incoming data.
GET
Command parameters:
- dhx_filter - hash of filtering rules
- filtration pattern - any entry( like %x% )
- in case you have a few parameters, you should link them by AND logic
- parameter is available only for fields with active filter
- empty filter value means that filter wasn't set and it must be ignored
// where field1 like %some% AND field2 like %other% dhx_filter[1]=some&dhx_filter[2]=other
- dhx_sort - hash of sorting rules
- possible values for asc and dsc parameters
- in case you have a few parameters, you should link them by AND logic
- order of filtering implementation - not defined, at the moment no one component is able to create multi-field sorting
// order by field1 ASC, field2 DESC dhx_sort[1]=asc&dhx_filter[2]=dsc
Hashes of rules in question use name of fields (where filtration is enabled) or columns' indices (in case of grid).
Restriction for output data: order and structure are defined through filtering/sorting parameters.
combo specific:
dhtmlxCombo has an additional filtering GET parameter:
- mask - sets filtration in text label columns using “like x%” rule.
some.php?mask=abc
dynamic loading
After data output implementation goes dynamical loading. Dynamical loading has some particular features while working with hierarchical (tree/treegrid) and simple (grid/combo) components.
For hierarchical components, loading of data branch occurs at once.
some.php?id=123
Command parameters:
- id - 'parent id' which defines the appropriate branch (beware, all filtration/sorting rules set while the previous stage are applied to component).
For other components, data will be outputted according to incoming parameters.
//grid some.php?posStart=20&count=50 //combo some.php?pos=50
Command parameters:
grid:
- posStart - index of initial string
- count - number of strings to output
combo:
- pos - index of initial string
- number of strings is defined by server settings