[Spec] Cell Editor Interface

[dongwoo-kim]

Cell Editor

Intro

The ability to customize cell editing UI has been the most demanded feature for TOAST UI Grid for a long time. Users used to use the formatter for this purpose, but the formatter is aimed to customize the contents of the cell, not to customize editing UI.

With the release of version 4, the official Cell Editor interface is supported by default in the TOAST UI Grid so that users can customize the editing UI to meet their own requirements.

CellEditor Interface

The CellEditor should be the constructor function. The TOAST UI Grid will make instances of it using new keyword internally. We recommend using class keyword, but in case class keyword is not available, function and prototype can be used instead.

The CellEditor should implement the interface below.

interface CellEditor {
  getElement(): HTMLElement;
  getValue(): string | number | boolean;
  mounted?(): void;
  beforeDestroy?(): void;
}

getElement()

This method should return the root DOM element of the editor. When editing is started, the returned element will be appended to the editing layer DOM.

getValue()

This method should return the value of the cell. When editing is finished, the returned value will be used to set the cell value.

mounted()

This method is an optional, and can be used to initialize Input elements. This method is invoked right after the root element returned by getElement() is attached to the DOM.

beforeDestroy()

This method is an optional, and can be used to clean up input elements. This method is invoked right before the root element returned by getElement() is detached from the DOM.

Example

The following is the source code of the simple text editor.

class TextEditor {
  constructor(props) {
    const el = document.createElement('input');

    el.type = 'text';
    el.value = String(props.value);

    this.el = el;
  }

  getElement() {
    return this.el;
  }

  getValue() {
    return this.el.value;
  }

  mounted() {
    this.el.select();
  }
}

The constructor function is invoked whenever editing is started. It's common to store the root element as an instance member, so that it can be used later in other methods such as getElement() and getValue().

The constructor function receives props object which contains useful information for customizing editing UI. The interface of the props object is like below.

interface CellEditorProps {
  grid: Grid;
  rowKey: string | number;
  columnInfo: ColumnInfo
  value: string | number | boolean;
}

The grid property is an instance of TOAST UI Grid itself. This can be useful if you want to get specific data or manipulate the data manually.

The columnInfo property contains the all information of the column in which the target cell is contained. The inerface of the ColumnInfo is like below.

export interface ColumnInfo {
  readonly name: string;
  header: string;
  minWidth: number;
  editor?: CellEditorClass;
  editorOptions?: Dictionary<any>;
  renderer: CellRendererClass;
  rendererOptions?: Dictionary<any>;
  copyOptions?: ClipboardCopyOptions;
  hidden: boolean;
  formatter?: Formatter;
  prefix?: Formatter;
  postfix?: Formatter;
  baseWidth: number;
  resizable: boolean;
  fixedWidth: boolean;
  relationMap?: Dictionary<Relations>;
  related?: boolean;
  align?: 'left' | 'center' | 'right';
  valign?: 'top' | 'middle' | 'bottom';
  whiteSpace?: 'pre' | 'normal' | 'norwap' | 'pre-wrap' | 'pre-line';
  ellipsis?: boolean;
  escapeHTML?: boolean;
  defaultValue?: CellValue;
  sortable?: boolean;
  validation?: Validation;
  onBeforeChange?: Function;
  onAfterChange?: Function;
}

More information of every properties will be specified in the official document. Before that, please refer to the source code of store/dyptes.ts file.

Usage

Built-in Editors

Currently, 5 built-in editors are supported by default.

• text : <input type="text" />
• password : <input type="password" />
• checkbox : <input type="checkbox" /> and <label>
• radio : <input type="radio" /> and <label>
• select : <select> and <options>

For using these built-in editors, you can use string value for the editor property of the columns options.

const grid = new Grid({
  // ...
  columns: [
    {
      name: 'artist',
      editor: 'text'
    },
    {
      name: 'genre',
      editor: 'checkbox',
      editorOptions: {
        listItems: [
          { text: 'Pop', value: '1' },
          { text: 'Rock', value: '2' },
          { text: 'R&B', value: '3' }    
        ]
      }
    }
  ]
});

Note that editorOptions.listItems property is used for the checkbox editor. The checkbox, radio, select editor will use this data when displaying list items.

Custom Editors

You can register your own editor also. For this, the constructor function should be set to the editor property of the columns options.

class MyCustomEditor {
  constructor(props) {
    const options = props.columnInfo.editorOptions.myCustomOptions;
    // ...
  }
  // ...
}

const grid = new Grid({
  // ...
  columns: [
    {
      name: 'artist',
      editor: 'text',
    },
    {
      name: 'genre',
      editor: MyCustomEditor,
      editorOptions: {
        myCustomOptions: {
          // ...
        }
      }
    }
  ]
});

Note that you can define your own editorOptions and use it in the constructor function using props.columnInfo.editorOptions.

Feedback Welcome!

The TOAST UI Grid 4 is still in progress and plainning to release the official version by middle of June. If you are a passionate user of the TOAST UI Grid, please give the alpha version of V4 a try and give us some feedback about this specification. Thanks!!