Edit cells

object-table v3 supports comprehensive in-line cell editing. When a cell is editable its value can be changed with the help of nested edit- tags inside of a column. When a column contains an editable tag, it must also contain a display attribute, since the contents of the column contains additional parser information.

User Experience Tip: Specify an orderBy on your query

Since the default ordering for queries is by modification date, editing the value of an object's field via edit- will cause that object to be the last modified one. This causes your query to reload and the last modified object will be at the end of the list, creating the impression that it disappeared. To prevent this from happening, be sure to specify an orderBy on your query on something other than the modification date, e.g. DB.user.all().orderBy('name'). This keeps the ordering stable, resulting in better user experience.

The on-change attribute

The function to execute when a cell's value is edited is specified by the on-change attribute as follows:

<object-table ...>
   <column heading="Editable field" display="{name}">
      <edit-text on-change="$:valueChanged($object, newValue, oldValue)" />
   </column>
</object-table>

function valueChanged(object, newValue, oldValue){
   object.name = newValue;
   object.save();
}

The 'Loading' indicator

When the saving of a value is slow due to complex database logic, the table will show an inline loader to indicate that the value is being saved:

Providing a separate value when editing

The data displayed in a cell sometimes differs from what is displayed when it is being edited, as with monetary data. In these cases one can make use of the value attribute to override the display value, which is normally used when the user selects a cell for editing.

In the following code example, the value displayed by the cell is "Name: " followed by the format string generated by {name}:

<object-table ...>
   <!-- With object variable -->
   <!-- The displayed value is set by display="..." -->
   <column heading="Example 1 - display values directly from the object" display="Name: {name}">
       <!-- The value that appears when the cell is edited is defined in value="..." below -->
       <edit-text value="$object.name" on-change="$:valueChanged($object, newValue, oldValue)" />
   </column>
</object-table>

function valueChanged(object, newValue, oldValue){
   object.name = newValue;
   object.save();
}

In the next example, the value attribute accepts a function that provides access to $object from which the actual cell value is extracted by the $:getMonetaryValue($object) function:

 <object-table ...>
    <!-- With a function -->
    <!-- The displayed value is set by display="..." -->
    <column heading="Example 2 - use a function" display="{cost} USD">
        <!-- The value that appears when the cell is edited is generated by a function -->
        <edit-text value="$:getMonetaryValue($object)" />
    </column>
 </object-table>

function getMonetaryValue(object) {
    return object.cost;
}

function costChanged(object, newValue, oldValue) {
    object.cost = newValue;
    object.save();
}

Unlike display, value is not a text attribute and must therefore represent a variable or result of a function, i.e. do not use string literals to give it a value in curly brackets like this: value="{do_not_do_this}"

Data validation

Editable cells will attempt to sanitize a user's input and perform automatic validation depending on the type of input. It is possible to provide additional custom validation using the methods below:

Method 1: Return false

If the return value of the valueChanged method is false a validation error will occur and an error message will display with the cell.

function valueChanged(object, newValue, oldValue){
   if(newValue === null){
       return false;
   }
   object.name = newValue;
   object.save();
}

Method 2: Exception

An exception can be thrown, which will not only prevent further execution of the function, but also allow the error message to be custom. For example:

function valueChanged(object, newValue, oldValue){
   if(newValue === null){
       // this value is used as the error message
       throw new Error("Name cannot be empty");
   }
   object.name = newValue;
   object.save();
}

Disabled editable-cells

When a particular editable cell should not be editable based on a condition, the disabled attribute can be used to dynamically turn it into a standard display-only cell. This attribute has access to $object.

<object-table ...>
   <column heading="Editable field" display="{name}">
       <edit-text disabled="$:isDisabled()" />
   </column>
</object-table>