Client-Server Protocol

This chapter will tell you about client-server communication in the context of 2 data operations: loading and update.

Format of data transmitting is JSON

Loading

Initially, Spreadsheet loads a default 'skeleton' and doesn't store any information on the server, except for the sheet's id. When you change something and send a request, data related to this change is saved on the server. Next time you refresh the page or another user accesses it, Spreadsheet loads the 'skeleton' and gets data saved on the server to rewrite the appropriate default values.

The server response can have the following look:

{
    "sheetid": "1",
    "config": "cols:10;rows:25;show_row_numbers:true;show_export_buttons:true",
    "readonly": false, 
    "head": [{
        "col": "4", 
        "width": "64", 
        "label": "D111" 
        }, 
        {  
        ...
        }],
    "cells": [{
        "row": "2", 
        "col": "2",  
        "style": "0;0;000000;ffffff;left;none;0", 
        "text": "3", 
        "calc": "3" 
        },
        { 
        ...
        }]
}

Available parameters

sheetid - (string) the name of a Spreadsheet instance;
config - (hash of values serialized into string) contains general Spreadsheet configuration.
Passed as array with 4 elements, in the following succession:
- cols - (number) the number of columns in the sheet;
- rows - (number) the number of rows in the sheet;
- show_row_number - (boolean) specifies whether row headings should be shown or hidden;
- show_export_buttons - (boolean) specifies whether export buttons('pdf', 'excel') should be shown or hidden.
readonly - (boolean) specifies whether a user can edit the spreadsheet;
head - (array) contains columns configurations:
- row - (number) the column index in the sheet (numeration starts from 1);
- width - (number) the width of the column;
- label - (string) the heading of the column.
cells - (array) specifies cells configuration:
- row -(number) the cell row index in the sheet (numeration starts from 1);
- col - (number) the cell column index in the sheet (numeration starts from 1);
- label - (string) the heading of the column;
- style - (hash of values serialized into string) defines cells' style.
  Passed as array with 7 elements in the following succession:
  - bold - (0 or 1) defines whether the bold style should be applied to the cell;
  - italic - (0 or 1) defines whether the italic style should be applied to the cell;
  - color - (hex value without the leading # sign) the text color;
  - background - (hex value without the leading # sign) the background color;
  - align - (left, right, center, justify) the alignment in the cell;
  - validator - (none, email, number, positive, not_empty) defines a validator applied to the cell;
  - lock - (0 or 1) specifies whether the cell is locked or unlocked.
text -(string|number) the value entered in the cell;
calc - (string|number) the calculated value (makes sense in case of formulas).

Data updates

Incoming parameters

Each time you update data, Spreadsheet sends a request (an array of cell properties) to the server.

For example, if you update the cell B1 by setting the value "Sales", the related request will look like:

rows[0]=1;
cols[0]=2;
values[0]='Sales'

In case you update several cells at once, the request will contain several 'properties' blocks:

rows[0]=3;
cols[0]=5;
values[0]='some_value';
..
rows[i]=5;
cols[i]=5;
values[i]='some_value';

where i=n-1, n - the number of cells which need updating.

Available parameters

Parameters and their number depend on a cell you update, whether it is a regular cell or a column heading.

Cells:

parameters sent by POST method:
- rows[i] - (number) the cell row index in the sheet (numeration starts from 1);
- cols[i] - (number) the cell column index in the sheet (numeration starts from 1);
- styles[i] - (hash of values serialized into string) defines cell style.
  Passed as array with 7 elements (see details above);
- values[i] - (string, number) the value of the cell.
parameters sent by GET method:
- edit=true - makes cells editable. Constant value;
- dhx.math - (boolean) enables formulas. Beware, if you activate this option you should write all calculation logic manually;
- sheet - (string) the id of the used sheet.

Headings:

parameters sent by POST method:
- col - (number) the column index in the sheet (numeration starts from 1);
- name - (string) the heading of the column;
- width - (number) the width of the column.
parameters sent by GET method:
- sheet - (string) the id of the using sheet;
- edit='header' - makes headings editable. Constant value.

Server response

The response of the server presents a hash of values, each of which defines configuration of a certain cell (or a heading).

Cells

Incoming parameters:

sheet= '5';
edit= true;
dhx.math= true;
rows[0]= 1;
cols[0]= 2;
styles[0]= '1;1;000000;ffffff;center;email;0'
values[0]= 'Sales'

Server response:

[{  
    row: '24',
    col: '4',
    text: '', 
    calc: '', 
    type: 'updated'
}]

Headings

Incoming parameters:

sheet= '5';
edit= 'header';
col= 2;
name= 'Total';
width= 200;

Server response:

[{  
    row: '',
    col: '4',
    text: '', 
    calc: '', 
    type: 'updated'
}]

See descriptions of the parameters used in the table in the section Loading.