|
This example demonstrates how to use the fieldEditor element to customize how data inside a grid is edited.
Prerequisites and Intended Audience
This example is intended for Web developers interested to develop feature rich lists and grids. To work through this example you need the Backbase Client Framework, and intermediate level experience developing with BTL and JavaScript.
Overview
The listGrid is an element designed to display and manipulate tabulated data. Besides viewing and navigating the data, there is often a requirement to edit data. The listGrid incorporates inline editors that allow data to be edited inside the grid. The editor that is available can be defined using the fieldEditor element.
Note: Because the treeGrid extends the listGrid, all the rules concerning editors for the fields applicable to the listGrid are true for the treeGrid.
The Default Editor
By default, the contents of all the cells in a listGrid, or more specifically a listGridCol, are editable. Clicking on the selected record triggers an editor to appear in the cell where the data is located. You can edit any record in the grid, and edit any field within it. The default editor is the XHTML input element.
Disabling Editing
It is not always desirable to allow the entire contents of a grid to be editable. For example, unique identifiers such as social security numbers and machine generated keys may need to be displayed but should not be edited. The readonly attribute is available to set whether a field can be edited. The default setting for the readonly attribute is false, meaning that all cells are editable by default. Setting this attribute to true for some particular listGridCol element will disable editing of that field in all records of the listGrid.
Note: You cannot disable editing behavior on an individual record basis.
<b:dataContainer>
<movies>
<movie id="film-1">
<title>The Seven Samurai</title>
<director>Akira Kurosawa</director>
<genre>Drama</genre>
<premiere>1954-01-12</premiere>
<price>42.99</price>
</movie>
<movie id="film-2">...</movie>
<movie id="film-3">...</movie>
<movie id="film-4">...</movie>
<movie id="film-5">...</movie>
</movies>
</b:dataContainer>
</b:dataSource>
<b:listGrid rows="5" dataSource="data">
<b:listGridCol label="Title" readonly="true" />
<b:listGridCol label="Director" readonly="true" />
<b:listGridCol label="Genre" />
<b:listGridCol label="Premier Date" readonly="true" />
<b:listGridCol label="Price" />
</b:listGrid>
Listing: Default listGrid editing behavior and readonly attribute.
The behavior of the grid defined by the previous listing is demonstrated in the following live demo:
Live Demo: Default listGrid editing behavior and readonly attribute.
Defining a Custom Editor With the fieldEditor
Although the default input will almost always match the type of the data you are editing (because it is almost always a string), it may not be the most appropriate editor. Dates, for example, will require a particular format, and other custom validation rules will require certain formats or values that can be better implemented using another inline editor. In this case, the inline editor can be defined using the fieldEditor.
For the purpose of adding a custom editor to the listGrid, each listGridCol element can have fieldEditor element as a child. The fieldEditor element wraps the element to be used to edit the field. For example, you can include the XTHML select element inside fieldEditor element, so that each time a record is opened for editing, a predefined list will be displayed from which the value for the field can be selected.
There are many use cases for this feature, and all of them concern the convenience of editing a particular type of field. For example, you may want to define a check box element as the editor for a boolean field, or a text area for editing large multiline fields.
In the following listing, the XHTML select element is implemented as the custom editor, thereby limiting the editing choice to a set of predefined values:
<b:dataContainer>
<movies>
<movie id="film-1">
<title>The Seven Samurai</title>
<director>Akira Kurosawa</director>
<genre>Drama</genre>
<premiere>1954-01-12</premiere>
<price>42.99</price>
</movie>
<movie id="film-2">...</movie>
<movie id="film-3">...</movie>
<movie id="film-4">...</movie>
<movie id="film-5">...</movie>
</movies>
</b:dataContainer>
</b:dataSource>
<b:listGrid rows="5" dataSource="data">
<b:listGridCol label="Title" readonly="true" />
<b:listGridCol label="Director" readonly="true" />
<b:listGridCol label="Genre">
<b:fieldEditor>
<select>
<option>Crime</option>
<option>War</option>
<option>Drama</option>
</select>
</b:fieldEditor>
</b:listGridCol>
<b:listGridCol label="Premier Date" readonly="true" />
<b:listGridCol label="Price" />
</b:listGrid>
Listing: Incorporating a custom XHTML editor into a listGrid.
The behavior of the grid with the custom XHTML editor defined is demonstrated in the following live demo:
Live Demo: listGrid with the XHTML select element as the custom editor.
Using BTL Elements as Inline Editors
Although not all XHTML elements are suitable to be used editors for listGrid fields, certain Backbase BTL elements can be used as editors. These include the spinner, slider, comboBox, suggestBox, calendar and listBox.
The following listing shows how to use a BTL element as a custom editor in a listGrid:
<b:dataContainer>
<movies>
<movie id="film-1">
<title>The Seven Samurai</title>
<director>Akira Kurosawa</director>
<genre>Drama</genre>
<premiere>1954-01-12</premiere>
<price>42.99</price>
</movie>
<movie id="film-2">...</movie>
<movie id="film-3">...</movie>
<movie id="film-4">...</movie>
<movie id="film-5">...</movie>
</movies>
</b:dataContainer>
</b:dataSource>
<b:listGrid rows="5" dataSource="data">
<b:listGridCol label="Title" readonly="true" />
<b:listGridCol label="Director" readonly="true" />
<b:listGridCol label="Genre">
<b:fieldEditor>
<select>
<option>Crime</option>
<option>War</option>
<option>Drama</option>
</select>
</b:fieldEditor>
</b:listGridCol>
<b:listGridCol label="Premier Date">
<b:fieldEditor>
<b:calendar format="yyyy-MM-dd" />
</b:fieldEditor>
</b:listGridCol>
<b:listGridCol label="Price">
<b:fieldEditor>
<b:spinner decimals="2" min="0" max="100" step="0.01" stringAfter="$" />
</b:fieldEditor>
</b:listGridCol>
</b:listGrid>
Listing: Incorporating a BTL element as a custom editor in a listGrid.
The behavior of the grid with a BTL element used as a custom editor is demonstrated in the following live demo:
Live Demo: listGrid with XHTML and BTL elements used as custom editors.
The prerequisites for an element to be used as a field editor is that it must be a form element. This is an important consideration if a custom widget is to be created because this requirement for a field to be an editor defines the interface to be used to implement the custom element.
The current implementation of the fieldEditor relies on the presence of value property of the element to be used as an editor. All form elements have this property, which is the reason they can be used as editors for grid fields. Consequently, and custom element that has the value property can also be used for editing grid fields.
Download
You can download a zipped version of the examples provided on this page to try them out for yourself.
Note: Make sure to extract the content of this zip file to the root folder of your web server or application server (for example, htdocs), and then run it from your local development environment.
Additional Resources
For more information on advanced topics in data binding, refer to the following documentation:
