Edit functions
An edit function is a JavaScript function responsible for editing a value in a custom view in the web client, as a render function is for displaying it. Its name is given in a property's CUSTOM option, after the CHANGE keyword, and in the CUSTOM block of the INPUT operator, for the value that operator requests from the user. In the desktop client the value is edited by the standard mechanism.
The edit function
By default the value is edited by the property's standard mechanism — a text input, for instance. The CHANGE keyword of the CUSTOM value view replaces or extends that mechanism with an editor of your own, written in JavaScript:
PROPERTIES(o) address CUSTOM CHANGE 'googleAutocomplete'
The editor function, like the display function, is registered as a wrapper and returns an object of several functions. The editor kind is determined by which rendering function that object contains:
| function | editor |
|---|---|
renderInput(element, controller, value) | extends the standard text input; element is that input itself |
renderDialog(element, controller, value) | a window editor. Losing focus does not automatically commit the edit |
render(element, controller, value) | an editor replacing the cell content |
value is the current property value converted to a JS value. Besides the rendering function, the object may contain:
getValue(element)— returns the value to commit. The string'canceled'cancels the edit. For an input editor, when this function is absent, the text of the input itself is taken.clear(element, cancel)— cleanup when the edit finishes.cancelis true on cancellation.onBrowserEvent(event, element)— handling browser events during the edit.
The editor's controller
The editor controller provides:
| method | what it does |
|---|---|
commit([value]) | commit the edit: the passed value or, with no argument, the current one (from getValue or the input) |
cancel() | cancel the edit |
setDeferredCommitOnBlur(true) | defer the commit on focus loss — for picking from a suggestion list rendered outside element |
setDeferredCommitOnBlur(false) | when the editor commits on focus loss, process the commit immediately (the default) |
getColorThemeName() | the current color theme name |
form | the form controller |
The committed value goes through the property's ordinary change channel — the same way as a value entered by the standard editor.
Calling commit() on a window or replacement editor requires getValue(element). Calling commit(value) skips getValue and converts the supplied value to the input type. The cancellation string 'canceled' is recognized only as a result of getValue.
For example, the built-in googleAutocomplete editor extends an address input with Google Maps suggestions:
function googleAutocomplete() {
return {
renderInput: (element, controller) => {
// the suggestion list is rendered outside element, and picking from it ends with a focus loss,
// so the commit on focus loss is deferred until the value is set
controller.setDeferredCommitOnBlur(true);
new google.maps.places.Autocomplete(element, { types: ['address'] });
},
clear: (element, cancel) => {
// remove the suggestion list elements added to <body>
$(".pac-container").remove();
}
};
}