DHTMLX Docs & Samples Explorer

Index
dhtmlxgrid

## Cells Manipulation

### Available Types of Cell Editors (Excell)

There are some predefined cell editors delivered with dhtmlxGrid. They are:

- ReadOnly (ro) - the cell can't be edited;
- Simple Editor (ed) - the text is edited inside a cell;
- Text Editor (txt) - the text is edited in a popup multi-line textarea;
- Checkbox (ch) - a standard checkbox;
- Radio button (ra) - a column oriented radio button;
- Select box (coro) - a simple select box;
- Combobox (co) - a select box with the ability to add some other value;
- Image (img) - not editable; the value is considered as a URL of image;
- sub_row - shows HTML content in a sub-row;
- sub_row_ajax - treats content as a URL to load sub-row content from;
- dhxCalendar - popup calendar;
- dhxCalendarA - popup calendar with the ability to enter data manually.

Special types of cell editors:

- Color picker (cp) - a simple color picker (just for example); the value is considered as color code or name;
- Price oriented (price) - shows $ before the value, all values equal 0 are shown as na in red color;
- Dynamic of Sales (dyn) - shows up|down icon depending on the value; color coding is also available (green|red).

### Assigning Cell Editor

To assign necessary types to columns, the following script method with comma delimited list of editor codes should be used:

      <script>
          grid.setColTypes("ro,ed,txt,txt,ro,co");
      </script>

The parameter here is typeStr - list of type codes (default delimiter is ”,”).

There is possibility to change type of the colum dinamically:

      <script>
          grid.setColumnExcellType(columnIndex,type);
      </script>

The parameters here are:

- columnIndex - index of a column which you want to change;
- type - type of the excell.

### Setting Type for Cell/Row

Since v1.2, the user can set the type for each cell, row, or change the default column type.

Setting all cells in a row to the specified type from script is done through the following method:

      <script>
          grid.setRowExcellType(rowId,type);
      </script>

The parameters are:

- rowId - id of the row;
- type - type of the excell.

Setting particular cell type for a certain cell from script in a row is also possible:

      <script>
          grid.setCellExcellType(rowId,cellIndex,type);
      </script>

The user should indicate:

- rowId - id of the row;
- cellIndex - index of the cell;
- type - type of the excell (code like “ed”, “txt”, “ch”, etc).

Setting column type from XML looks like this:

      <cell type="[eXcell code]">...</cell>

### Cell Text Manipulations

The user can set text style for a specified cell in the following way:

      <script>
          grid.setCellTextStyle(row_id, ind, styleString);
      </script>

The parameters here are:

- row_id - id of the row;
- ind - index of the cell;
- styleString - style string in the common format (example: “color:red;border:1px solid gray;”).

### Getting Select Box Collection

The following method can be used to get Combo object of the specified column:

        <script>
            var combo = grid.getCombo(index); // index of the column to get combo object for
        </script>

If the user needs a collection to be specific for a cell, the following method should be used:

        <script>
            var combo = grid.getCustomCombo(rowId,cIndex);
        </script>

The parameters of this method are:

- id - id of the row;
- ind - index of the column.

### Managing Select Box Collection

The collection supports the following API:

        <script>
            combo.put(value,label) - adds a new record in the collection;
            combo.remove(value) - removes a record from the collection;
            combo.clear() - removes all records from the collection;

            combo.size() - returns the current size of the combo box;
            combo.get(value) - returns the label by value;
            combo.getKeys() - returns the array of all possible values;

            combo.save() - saves the current state;
            combo.restore() - restores the previously saved state.
        </script>

The less common use-case is the one that gets the value by label. This can be done using the following code:

        <script>
            var value = combo.values[combo.keys._dhx_find(key)];
        </script>

### Merging Cells

Activating the possibility to merge cells in the grid, the user can display row cells the same way as he uses colspan or rowspan (since v1.5) in the HTML table. Cell groups can be managed from XML or Script. In both cases rowspan and colspan must be enabled while dhtmlxGrid initialization:

          <script>
              grid.enableRowspan();
              grid.enableColSpan(true);
          </script>

The user should include dhtmlxgrid_rowspan.js file into the page to make rowspan work. Colspan doesn't require any additional files. There are several methods responsible for grouping and ungrouping cells with colspan and rowspan.

#### Managing Cell Groups from XML

The number of cell tags in a row should not be changed. The example of a row with 3 cells, 2 of which are grouped, is presented below:

        <row id="r01">
            <cell colspan="2">value</cell>
            <cell/>
            <cell>value of third cell</cell>
        </row>

The same for rowspan:

        <row id="r01">
            <cell rowspan="2">value0</cell>
            <cell>value1</cell>
        </row>
        <row id="r02">
            <cell/>
            <cell>value2</cell>
        </row>

#### Managing Cell Groups from Script

1. Setting colspan in a row starting from the specified column index:

          <script>
              grid.setColspan(row_id, col_ind, colspan);
          </script>

The parameters of this method are as follows:

- row_id - id of the row;
- col_ind - index of the column;
- colspan - size of the colspan (number of cells in group).

2. Setting rowspan with specified length starting from the specified cell

          <script>
              grid.setRowspan(rowID,colInd,length);
          </script>

The parameters of this method are as follows:

- rowID - id of the row;
- colInd - index of the first cell in group;
- length - length of the rowspan (number of cells in group).

For example:

          <script>
                  // group two cells with colspan
              grid.setColspan("r01",0,2);
                  // ungroup cells
              grid.setColspan("r01",0,1);
                  // group two cells with rowspan
              grid.setRowspan("r01",0,2);
                  // ungroup cells
              grid.setRowspan("r01",0,1);

Note: simultaneous usage of rowspan and colspan for one cell is not possible. Also note setColspan() and setRowspan() methods must be called only after proper rows are loaded

### Getting dhtmlXGridCellObject Object

The user can get dhtmlXGridCellObject object in the following way:

1. By Cell Id:

          <script>
              var cellObj = grid.cellById(row_id, col);
          </script>

Using this functionality, the user should indicate the following:

- row_id - id of the row;
- col - index of the column.

Note: if no parameters are indicated, the method gets dhtmlXGridCellObject object of currently selected cell.

2. By Cell Index:

          <script>
              var cellObj = grid.cellByIndex(row_index, col);
          </script>

The user should specify the following parameters of this method:

- row_index - index of the row;
- col - index of the columns.

### Editing Cells

The following method creates the Editor object and switches the currently selected cell to edit mode if it is allowed:

          <script>
              grid.editCell();
          </script>

The following method should be used to return the value from the editor (if it is present) to the cell and close the editor:

          <script>
              grid.editStop(mode);
          </script>

### Marked Cells Manipulation

There is the possibility to set marked cells support for enabled or disabled state in dhtmlxGrid. The user should include dhtmlxgrid_markers.js file into the page to work with this functionality.

            <script>
                grid.enableMarkedCells(state); // true|false
            </script>

A cell can be marked/unmarked (selected or deselected) from script in the following way:

          <script>
              grid.mark(r,cInd,state);
          </script>

The parameters here are:

- r - row object or index of the row;
- cInd - index of the cell;
- state(true|false) - select or deselect the cell in question.

The user can get marked cells in the following way:

          <script>
              grid.getMarked();
          </script>

The method returns the array of marked cells (pairs of row id and column index). To unmark all cells in the grid, the user should call the following command:

            <script>
                grid.unmarkAll();
            </script>

### Enabling Cells Unique Ids

There is a method that is capable of enabling/disabling unique ids for cells. Ids will be automatically created using the following template: “c_[RowId]_[colIndex]”.

          <script>
               grid.enableCellIds(mode); // true to enable, false to disable
          </script>

### Finding Cell

To find a cell in the grid by its value, the user should apply the following method:

            <script>

              var cell = grid.findCell(value, c_ind, first);
          </script>

The user shouldn't forget to include dhtmlxgrid_filter.js file into his project. The parameters of the method mentioned above are:

- value - search string;
- c_ind - index of column to search in (optional; if it is not specified, then search everywhere);
- first - finds only the first occurrence (optional parameter).

The method returns array, each member of which contains array with row id and cell index.

### Getting Index of Selected Cell

Index of the selected cell can be easily got like this:

            <script>
                grid.getSelectedCellIndex();
            </script>

The method returns either index of selected cell or -1 if there is no any selected cell.

### Clearing wasChanged State

The user can clear wasChanged state for all cells in the grid in the following way:

          <script>
              grid.clearChangedState();
          </script>

### Enabling Edit Events

enableEditEvents() method is responsible for enabling|disabling events that start excell editing. This method is mutually exclusive with enableLightMouseNavigation() method. The user should indicate the following:

- click(true|false) - enable|disable editing by a single click;
- dblclick(true|false) - enable/disable editing by a double click;
- f2Key - enable|disable editing by pressing the F2 key.

            <script>
                grid.enableEditEvents(click, dblclick, f2Key);
            </script>

### Selecting Cell

The method selectCell() should be used to select the specified cell in the grid. The user indicates the following parameters:

- r - row object or row index;
- cInd - cell index;
- fl - if set to true, onRowSelect function will be called;
- preserve(true|false) - preserve previously selected rows, false by default;
- edit - switch the selected cell to edit mode;
- show(true|false) - scroll row to view, true by default.

            <script>
                grid.selectCell(r, cInd, fl, preserve, edit, show);
            </script>