DHTMLX Docs & Samples Explorer

Form Integration

dhtmlxGrid can integrate with a surrounding FORM - which means grid data will be sent as a part of form submitting (this functionality can be used to save changes in the grid, if you do not want to use dataprocessor library).

To enable form integration you need:

  • Include ext/dhtmlxgrid_form.js;
  • Place grid's container inside the FORM tag.

That is all, no additional steps are to be taken.

Submit Modes

Grid can work in the following modes:

  • Submit only the changed rows (the default mode);
  • Submit all rows;
  • Submit ID's of the selected rows;
  • Submit values of the selected rows.

"Submit Only the Changed Rows"

Submit only the changed rows is the default mode. In this mode the grid will include only the data of the changed rows in the process of form submitting.

For each changed row a virtual input field will be added:
The name of the field is [GRIDID]_[ROWID]_[CELLINDEX]
where

  • GRIDID - id of the container used for the grid;
  • ROWID - id of the row in which a value was changed;
  • CELLINDEX - the index of a cell inside the row.

The value of the field is equal to the cell value.

For example, if we have a grid similar to the following one:

      var grid = new dhtmlXGridObject("gridbox")
      ...
      grid.addRow("r1",["first","second","third"])

And later change the “second” to the “new second” and submit a form, it will have a

gridbox_r1_1=“new second”

If any row was added to the grid, all values of this new row will be marked as changed. Additional to it the
[GRIDID]_ROWS_ADDED
virtual input will be added. It will contain the list of IDs of the added rows (so on the server side it will be possible to separate added and updated rows).

If any row was deleted, the
[GRIDID]_ROWS_DELETED
virtual input will be added. The same as for the added rows, it will contain the list of IDs of the deleted rows.

Sending the information about added|deleted rows is enabled by default, but can be disabled in the following way:

      grid.submitAddedRows(false);

"Submit All Rows" Mode

It is a mode that is not going to be used quite often, in my opinion. It can be enabled by:

      grid.submitOnlyChanged(false);

In this mode a virtual input field for each cell will be created in the grid .

"Submit IDs of the Selected Rows" Mode

In this mode the grid will create a single virtual field: [GRIDID]_SELECTED This field will contain a list of row IDs which are selected (in the single select mode - it will be a single ID). The mode can be enabled by:

      grid.submitOnlySelected(true)
      grid.submitOnlyRowID(true);

"Submit Values from the Selected Rows" Mode

This mode works almost in the same way as the default mode. This mode will send updated values from the selected rows only:

      grid.submitOnlySelected(true);
      grid.submitOnlyRowID(false);

Sending form by direct submit call

If you are sending a form not by submit button, but by direct form.submit() call, the grid will not add its data automatically ( it can't intercept such kind of form sending ). To solve issue you can exec one more command before form sending to inform grid and restore the desired behavior.

    grid.parentFormOnSubmit();
    form.submit();

Some Additional Details

  1. As the names of fields contain gridId you can include multiple grids inside one and the same form tag.
  2. Pay your attention to the fact that only the rows edited by a user will be marked as changed. If you change some value by API calls, such row will not be included in the process of form submitting.

You can mark any row in the grid as updated in the following way:

      grid.cells(i,j).cell.wasChanged=true;