Instructions
Columns:

…for the Hypergrid Cell Formatter & Editor Workbench
This document discusses the workbench user interface and concludes with a tutorial/example.

This workbench is for learning about Hypergrid cell formatting and editing using localizers and cell editors. You can also use it for actual development and testing of these objects, but be aware this app does not persist your work anywhere. Be careful therefore to cut & paste anything you want to keep!

Data pane

A data pane is provided to adjust the data to suit the needs of your localizers and cell editors. Bind the data to the grid by clicking grid.setData(…) button. The grid in turn is bound to the data window for any edits made to cells using cell editors.

State pane

This pane lets you add a set of properties declaratively to the grid. Properties can also be set programmatically from the console with the various set property methods.

Example

Consider the default State pane: 
{
    editable: true,
    editor: "textfield",
    columns: {
        prevclose: {
            halign: "right",
            format: "trend"
        }
    }
}
  1. Edit the state pane to make the prevclose column use the ft-in (“foot-inch”) localizer rather than the trend localizer.
  2. Click the grid.addState(…) button.
  3. Notice how these values are now formatted as feet and inches.
  4. Double click one of these formatted values in the grid. Cell editing is enabled because:
    • The cell’s editable property is truthy.
    • The cell’s editor property is defined and resolves to a registered cell editor.
    • The cell’s ft-in localizer has a parse method. (You can see the localizer by selecting it from the dropdown in the Localizer pane.)
  5. Notice how editing in the grid is done in the format specified by the localizer — unlike the in the Data pane where these numbers are integers. The cell editor uses the localizer’s parse function to turn the edited value back into an integer.

Localizer pane

Value formatting in Hypergrid is controlled by localizers, objects with the following shape: 
{
  format: function(str), // required method that returns value
  parse: function(value), // required method that returns string
  invalid: function(value), // optional helper function for `parse`
  expectation: "optional error message describing expected syntax"
}
Formatting grid cell values is purely a text string manipulation. Any other graphical effects are the purview of cell renderers (not covered here). Cell editors can include fancy controls for manipulating the string, but the result needs to be a formatted string, parsable into a serializable value for storing into the data model.

format

Required. Formats raw data values for display in the grid.

parse

Required. Parses values in the displayed format, converting them back into raw data values. Used by cell editors to store results back to data model, or by search algorithms to compare a formatted value to other cells' raw values (without having to format every on of the other cells), etc.

Although parse is only called by Hypergrid when a formatted cell is edited, an implementation is currently required (by add). The reason for this is "completeness" — to be ready and available when your application inevitably needs to parse a value later on. The assumption is it’s easier to write a parser when you write the formatter than to have to go back later and rethink it. (That said, you can provide a no-op implementation to fake out add but you do so at your peril. So long as the cells using this localizer are not editable you should be all right.)

invalid

Optional. Validates the syntax. Usually implemented with a RegExp. For example (replace regex with an actual regex): 
  invalid: function(str) { return !/^regex$/.test(); }
Should be implemented when parse is not bulletproof (when it would jam unexpectedly on bad syntax). When implemented, invalid is called first; parse is only called if the syntax is valid (invalid returns falsy; i.e., “not invalid”).

expectation

Optional. A friendly description of the expected syntax. Used for error feedback, but also helpful for self-documenting the localizer.

Define a new localizer and add it to the grid

  1. Select (New) from the Load localizer drop-down.
  2. Rename it with a unique name by editing the name field.
  3. Add additional local variables by declaring them at the top, as needed.
  4. Code your localizer referring to examples and the localizer interface documentation.
  5. Be sure to assign your localizer to module.exports.
  6. Click the grid.localization.add(…) button.
  7. Optional: Edit the localizer and click grid.localization.add(…) again to update it.
For example, here’s a localizer to show a “degrees” unit: 
grid.localization.add('deg', { format: function(s) { return s + '°' } }
(Notice incidentally how add can optionally accept a name parameter for localizers that lack a name property.)

Bind the localizer to a cell

Bind a localizer using the format property. As always, a property can be set for the entire grid, a specific column (or row), or a specific cell. There are many ways to do this programmatically from the console with the various property setting methods.

From this interface, edit the state and click the grid.addState(…) button:

Edit an existing localizer

Duplicate an existing localizer

Cell editor pane

This pane lets you create and edit cell editors. It comes with a sample cell editor called Time for editing values formatted with the hh:mm localizer.

Define a new cell editor in this workbench

Procedure is similar to that for localizer (see above) except:

Bind the cell editor to a cell

Procedure is similar to that for localizer (see above) except:

Edit an existing cell editor

Procedure is similar to that for localizer (see above).

Duplicate an existing cell editor

Procedure is similar to that for localizer (see above).

Grid

The live Hypergrid appears below the other panes.

Tutorial / Example

The prevclose column is set to use this localizer (see the State pane), whose format function formats positive numbers with an up-arrow (⬆) and negative numbers with a down-arrow (⬇). The data for this column are all initially positive (see Data pane), so all values are formatted with up-arrows (see Grid).

Edit the cell value in the data pane

  1. In the data pane, change a couple of the prevclose values to negative numbers.
  2. Click the grid.setData(…) button.
  3. Notice how these values are now formatted with down-arrows in the grid.

Edit the cell in the grid

  1. Double click one of these formatted values in the grid to edit it using the Textfield cell editor.
  2. Cell editors append additional elements to the DOM, positioned precisely to the cell bounds.
  3. Edit the cell. This editor is for straight-forward text editing; it has no special controls for handling the arrows which are arrows are not available on the keyboard. You could cut & paste a down-arrow from another cell; or as a special accommodation to this problem the trend localizer’s parse function also accepts a prefixed negative sign.
  4. Press the enter key.
  5. The parse function converts the input to a value.
  6. Editor is closed.
  7. Grid is updated with the new value.
  8. Data pane is also updated with the new value.

Edit the localizer

Let’s improve the localizer.
Throw error on parser failer
The trend localizer’s parse function has a problem. It doesn't properly throw an error on failure:
  1. Double-click another cell to edit it, seting the contents to some invalid value (such as “xyz” which is not a number).
  2. Press the enter key.
  3. The parser cannot convert the value.
  4. Editor is closed.
  5. Grid is updated with null.
  6. Data pane is also updated with null.
The solution is to have the parse function throw an error when it cannot convert the value. If the native window.parseFloat function threw an error on failure we'd be there already. Instead, it returns NaN (“not a number”) on failure. Let’s catch the NaN and throw an actual error:
  1. In the Localizer pane, select the trend localizer.
  2. Uncomment the if statement with the throw statement within it.
  3. Click the grid.localization.add(…) button to update it.
  4. Edit another cell, again setting the contents to some invalid value.
  5. Press the enter key.
  6. The parser cannot convert the value.
  7. Negative feedback animation plays.
  8. Every third failure (press enter again) is accompanied by an alert with additional information (the error’s message is shown in the alert).
Check for valid syntax
The parse function as implemented correctly parses expected input. However, it’s not a fully realized finite-state machine; it doesn't parse the input as a grammar and therefore doesn't catch invalid syntax. Specifically, this parser ignores extraneous characters between a valid floating point number and the end of string, which conveniently ignores the arrows, but also anything else. There are two choices for addressing this:
  1. Make the parser "bulletproof" by implementing an FSM (from scratch or via a RegExp).
  2. Implement an invalid function to do a syntax pre-scan, which allows a (simpler) parser to assume the syntax is valid.
Display syntax hint
If you implement the expectation string property, that string (a friendly description of the syntax) will be included in the error alert mentioned above. If parse is called and it throws an error with a defined message property, that message will also be included (prepended to the expectation message).

Cell editors

We haven't discussed cell editors so far. Often, the Textfield cell renderer + a localizer with well-defined format and parse methods is all you need. A custom cell renderer is needed when what you’re editing cannot be easily represented or conveniently edited as text, or if you want to code special event handlers (such as ignoring illegal chars).
Bind to a cell editor
Cell editors depend on localizers and always have a default localizer that is used when the cell does not define a custom localizer (in its format property). Custom cell editors generally work hand-in-hand with a custom localizer. Let’s add a simple editor to the prevclose column. The column already specifies a custom localizer, trend. We're going to bind a custom cell editor to this column, also called Trend.
Note: The get methods, such as grid.localization.get(localizerName) and grid.cellEditors.get(cellEditorName) treat their parameter as case-insensitive. Localizer and cell editor names must be unique but exist in different name spaces which is why these two names don't clash (not because of the case differences.) The cell editor here could have been called "trend" but cell editors by convention start with a capital letter because they’re object constructors (or "classes" — which by long-standing convention are always capitalized).
  1. In the State pane, add editor: "Trend" to the prevclose column.
  2. Click the grid.addState(…) button.
  3. Double-click a cell in the prevclose column.
  4. Click the arrow and notice how it flips.
  5. Press the enter key to save the change or esc key to cancel it.
This cell editor makes toggling the arrow a simple matter of clicking on it. This usually would not be worth writing a cell editor for — except that in this case, the Unicode arrows are not on the keyboard so they're impossible to type.
Edit the cell editor
Let's add a keypress handler to provide a way to type the up-arrow and down-arrow. Take a look at the Trend cell editor:
  1. In the Cell Editor pane, select "Trend" from the drop-down.
  2. Uncomment the keypress event handler.
  3. Click the grid.cellEditors.add(…) button.
  4. Double-click a cell in the prevclose column.
  5. Type + or − and notice how the arrow flips.
This keypress handler does two things:
  1. The case '+' and case '-' cases let the user "type" in the arrows at any time during editing by pressing the + or − keys for up-arrow or down-arrow, respectively.
  2. The default case discards unexpected key presses, triggering an error feedback animation.
Regarding this.super
Calling the superclass’s implementation from setEditorValue, getEditorValue, and validateEditorValue, while not a requirement, is a common pattern and is recommended.

Debugging cell editors

Because the workbench's cell editors are dynamically added and don't exist as code files, debugging is challenging. Here’s one way to see your cell editor's code page:
  1. Make sure you have an initialize method (even if it’s empty).
  2. From the browser console, load up src/cellEditors/CellEditor.js.
  3. Place a breakpoint on the last line of the initialize method. If empty, you can place the breakpoint on the closing brace (}).
  4. Open the cell for editing by double-clicking it.
  5. From the breakpoint do 1 × "step-over" + 3 × "step-into" and you should find yourself in the subclass’s initialize method. (To get to a sub-subclass: 1 × "step-out" + 3 × "step-into")
Now that the debugger is displaying your cell editor, you can set breakpoints in your other methods.