Porting dhtmlxConnectors

The existing version of connectors supports just a limited set of server platforms, although we are trying to extend the list of supported languages and databases - you can't embrace the unembraceable. In case database/framework/scripting language you use in your project is not supported, you can port existing solution on your platform.

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.

Connector supports many operations implementing data load/manipulation and saving. There is an opportunity to provide supporting basic operations and ignore higher-level ones, in case they are not used in your project.

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.

Important points:

1. XML-data input must occur only after sending an appropriate http-header;
2. XML must start with XML declaration which contains an appropriate data coding;
3. 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.

XML Format used by connector

Implementation of this level allows to use resulting script as url for load|loadXML operations.

(technically there is an opportunity to use JSON or any other supported by component format, but you should bear in mind that complex scenarios are XML-oriented, that's why you would better use XML)

At this stage, the number of supported operations is considerably extended; you are allowed to use #connector_text_filter, connector to sort in grid and sort/filter through URL.

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 by direct parameters setting in URL)

In point of fact, you should use the code of the previous stage, but there is one particularity - before using XML data is sorted/filtered according to incoming data.

• Incoming parameters - GET
  • 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

Names of fields where filtering is enabled or columns indexes in case of grid, will be used as names in above hashes.

• Restriction for output data - order and structure are defined by filtering/sorting parameters.

dhtmlxCombo has an additional filtering parameter GET - mask, which is used for setting filtering in the text label column, using “like x%” rule.

   some.do?mask=abc

The next step after data output implementation is dynamical loading. Dynamical loading has some particular features when working with hierarchical ( tree| treegrid ) and simple ( grid | combo ) components.

For hierarchical components, loading of data branch occurs at once.

     some.do?id=123

id parameter contains “parent id” value which defines an appropriate branch, meanwhile all filtering/sorting rules which were mentioned above are always working.

For simple structure, only section data will be output according to incoming parameters.

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

In grid, posStart parameter sets index of initial string and count parameter sets number of strings to output.

In combo, pos parameter sets index of initial string, number of strings is defined by server settings.

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

Component uses dateProcessor in send-all-at-once mode. The articles below describe format of data sent to server side and expected reply

• adjusting server side code
• data sending modes