Extending Functionality

Protocol details

Data fetching

POST

Command parameters:

• none

GET

Command parameters:

• connector=true - flag of the connector-based request. The flag is set automatically, once you include the connector.js file on the page (note that if you use dhtmlxSuite package, connector.js is already included into the package and there's no need to include it additionally)

• dhx_colls=field1,field2...fieldN - optional, can contain a list of fields for which collections will be requested. dhtmlxGrid uses such parameters to request data for combo columns and select filter (such requests are executed just once for initial data loading)

some.php?connector=true&dhx_colls=2,3

• dhx_sort[field]=directon - instruct the server-side connector to sort dataset by the defined field

some.php?connector=true&dhx_sort[2]=asc

• dhx_filter[field]=mask - instruct the server-side connector to filter dataset by the defined field

//filter by %test%
some.php?connector=true&dhx_filter[2]=test

Grid specific

Requesting a 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 a part of data

GET

• pos - position from which data is requested

Filter by the label field

GET

• mask - filtering mask for the label field

Tree/TreeGrid specific

Requesting a branch of tree

GET

• id - parent id for the requested branch

Data updating (using dataProcessor)

GET

• editing=true - mark of the dataprocessor-based call

POST

• ids - a list of updated records
• [id]_[property] - for each field inside of the updated record the related field in POST is generated
• [id]_!nativeeditor_status - the action type

Back to top

Porting connectors to another platforms

When should you use it?

The existing version of connectors supports a limited set of server platforms. In case the database/framework/scripting language you'd like to use is not supported, you can port an existing solution on your platform.

When shouldn't you use it?

Connectors are just wrappers around the existing grid's functionality, that's why if you need to use this solution once, you'd better use grid API directly instead of creating your own server connector.

Implementation levels

The connector supports many operations that implement data processing. There is an opportunity to provide support for basic operations and ignore the higher-level ones, if they are not used in your project.

Basic support

Data assignment is a basic connector operation which proceeds in the following way: the connector connects to database, selects data and outputs it in stdout using XML format of the current component.

Key points:

1. XML-data input must occur only after sending the appropriate http-header
2. XML must start with XML declaration containing the appropriate data coding
3. No 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 aren't any;
• restriction for output data - there's no restriction.

XML Format used by connector

Basic implementation allows using the resulting script as the input parameter for the load() method.

Filtering 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. Note that now before using XML data is sorted/filtered according to the incoming data.

GET

Command parameters:

• dhx_filter - a hash of filtering rules
  • filtering pattern - any entry( like %x% )
  • in case you have a few parameters, you should link them by AND logic
  • the parameter is available only for the fields with an active filter
  • an empty filter value means that filter hasn't been set and it must be ignored

// where field1 like %some% AND field2 like %other%
dhx_filter[1]=some&dhx_filter[2]=other

• dhx_sort - a 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 none of the components 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 the name of fields (where filtering is enabled) or columns' indices (in case of grid).

Restriction for output data: order and structure are defined through the filtering/sorting parameters.

Combo specific:

dhtmlxCombo has an additional filtering GET parameter:

• mask - sets filtering in text label columns using “like x%” rule.

some.php?mask=abc

Dynamic loading

After data output implementation goes dynamic loading. Dynamic 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 (note, all filtering/sorting rules set during the previous stage are applied to the component).

For other components, data will be output according to the incoming parameters.

//grid
some.php?posStart=20&count=50
//combo
some.php?pos=50

Command parameters:

Grid:

• posStart - index of the initial string
• count - number of strings to output

Combo:

• pos - index of the initial string
• number of strings is defined by the server settings

While working with Grid, the initial request (grid doesn't know yet how many strings are expected) doesn't contain any additional parameters ( 'posStart' and 'count' are not defined)

Back to top

Back to top