Getting Started / Working with Components

New to Kendo UI for jQuery? Download free 30-day trial

Editing Components

Some Kendo UI components (widgets) provide the editing feature that is implemented with a specific editor element or a form that is bound to the model by using the Kendo UI MVVM bindings.

The following components support editing:

Getting Started

The Kendo UI components that support editing provide the following common configuration options:

  • editable—Controls whether the editing is enabled or not. For instance, the editing functionality in the Kendo UI Grid component is disabled by default. For detailed information, refer to the API article on editing of the Grid.
  • editable.template—Allows you to define a custom editor template.

Some components provide additional editable options. For more details, refer to the particular component API documentation. For example, the Grid component can disable the remove functionality by using the editable.destroy option.

The Kendo UI components that support editing provide the following common events:

  • edit—Triggered before the editor form is shown. The UI elements are already bound to the model.
  • save—Triggered before the model is saved. The editor form is still open.
  • remove—Triggered before the model is removed.
  • Only the Scheduler and the Gantt support the preventing of the edit, save, and remove events.
  • The components use only one editor form. It applies the same editor template for the create and update actions.

To enable the editing feature of the component:

  1. Configure the CRUD (Create, Read, Update, Destroy) data operation actions of the DataSource.
  2. Define the model fields by using the schema.model option.
  3. Enable the editable option.

For more information on setting up editing in Kendo UI, refer to the article on editing of the Grid. The approaches are largely applicable to the other Kendo UI components which support the editing.

Working with Editor Forms

You can build editor forms and bind specific models to editor forms.

Building Editor Forms

A Kendo UI component builds an editor form dynamically based on the schema.model structure and more specifically the fields collection.

  • Define the id field of the data items in schema.model.id. This ensures the correct adding, editing, and deleting of items.
  • Define the datatype of the fields to take advantage of the built-in editors, filterable UI and correct sorting, filtering and grouping.

The following table lists the available data types.

Data Type Editor Parser
string <input type="text" class="k-input k-textbox" name="fieldName" data-bind="value:fieldName"> Internal method. String conversion.
number kendo.ui.NumericTextBox kendo.parseFloat()
date kendo.ui.DatePicker kendo.parseDate()
boolean <input type="checkbox" name="fieldName" data-type="boolean" data-bind="checked:fieldName"> Internal method. Boolean conversion.
object <input type="text" class="k-input k-textbox" name="fieldName" data-bind="value:fieldName"> Not processed. The value is passed as is.

The following example demonstrates how to declare the fields definitions through the DataSource schema.model.

    schema: {
        model: {
             id: "id",
             fields: {
                id: {
                    editable: false,
                    // A defaultValue will not be assigned (default value is false).
                    nullable: true
                },
                name: {
                    type: "string",
                    validation: { required: true }
                },
                price: {
                     // A NumericTextBox editor will be initialized in edit mode.
                     type: "number",
                     // When a new model is created, this default will be used.
                     defaultValue: 42
                },
                discontinued:{
                    // A checkbox editor will be initialized in edit mode.
                    type: "boolean"
                },
                created: {
                    // A date picker editor will be initialized in edit mode.
                    type: "date"
                },
                supplier: {
                    type: "object" ,
                    defaultValue: { companyName: "Progress", companyId: 1 }
                }
            }
        }
    }

The Kendo UI Scheduler has a static model structure and it follows only the predefined model fields list. To edit the additional fields, use a custom editor template.

The auto-generated editor form is bound to the model through the Kendo UI MVVM pattern. The component also allows you to override this form by using a custom editor template.

Once the form is created, the component performs the following actions:

  1. Binds the editor fields to the model.
  2. Triggers the edit event.
  3. Shows the editor form.
  4. Updates the model based on the changes made in the editors.
  5. When the editor form is about to close, the component triggers the save event. At this stage, the changes can be either accepted or declined.

The editor form is created and bound before the edit event is triggered, and is already populated.

Binding Specific Models to Editor Forms

When the edit event is triggered, the component gets the corresponding model and binds the generated or custom editor form to it through the Kendo UI MVVM pattern. The connection between the model fields and the form editors is done by using the value binding.

This connection respects the following rules:

  • On initial load, the editor form is populated using the model values.
  • The model is updated when the related editor triggers a change event. The value binding gets its value and populates the model field.
  • The form editors are updated when the ObservableObject API is used. Use the set method if you want to update the corresponding UI editors. If this API is omitted, the editors do not change.

Common Scenarios

Defining Custom Editor Templates

When the default editor form does not cover your business needs, create a custom editor form by using the editable.template option that allows you to define a custom editor form.

Each component uses only one editor form for the create and update actions.

The following rules apply to the editor template:

Defining Default Model Values

By default, the model fields have predefined values based on the field type. You can also define the field as nullable. To define a specific default value, use the schema.model.fields.defaultValue option. The value binding uses the model value to set the editor value. The value of the editor will be lost in favor of the model value.

schema: {
    model: {
        id: "ProductID",
        fields: {
            ProductID: { editable: false, nullable: true },
            ProductName: { defaultValue: "Product Name 1" }
        }
    }
}

Referencing Specific Editor Controls

You can access a specific editor element from the editor form by using the edit event of the component. For a sample demo, refer to this runnable example.

Updating Models through Specific Editors

To modify the model by updating the relevant editor, trigger the change event manually. In this way, you notify the value binding of the change and the model is updated accordingly.

The Kendo UI components provide the trigger method which must be used to trigger the change event.

Adding Editors without Using MVVM Bindings

  • To implement custom editing, use a custom editor template.
  • The Kendo UI MVVM bindings cannot be used anymore and the model binding should be handled manually.

To avoid defining a custom editor template for editing a specific model field, add an additional editor after the form is created:

  1. Wire the edit event of the component.
  2. Add the editor manually in the edit event handler.
  3. Set editor's value by using the model, available in the arguments of the edit event handler.
  4. Wire the change event of the editor and update the model accordingly.

For a sample demo on adding a control to the editor form, refer to this runnable example.

Accessing Models before Editing

Wire the edit event of the component. You will get the model from the passed arguments.

function edit(e) {
    var model = e.model;
}

The Scheduler passes the e.event field instead of the model one. The event is an instance of the SchedulerEvent class. For more details, see the corresponding edit event API documentation of the respective Kendo UI component.

Accessing Models by UID

Every model has a unique identifier. It is applied to the HTML element that holds the editor form. You are able to recognize that element by the data-uid HTML attribute. Use that uid value to get the model from the DataSource of the component by using getByUid method.

Identifying New Models

To differentiate between the create and update actions, use the Model.isNew() method.

Troubleshooting

This section provides solutions for common issues you might encounter while configuring the editing functionality.

Model field values in edit events are not updated

Description A common scenario is to modify the model in the edit event of the component which will be prevented if the initial (default) value of the model field is invalid. In this case, the attached UI validation prevents any additional model modifications until the value is updated from the editor form.

Cause The following actions that occur during a model update create the issue:

  • A model field is updated using the set method.
  • The model gets the new value, compares it to the current one and, if they are different, the new value is ready to be set.
  • UI validation is triggered. Note that it uses the editor element value to perform the validation check. However, it is invalid and hence the new value that we try to set is ignored.

Solution Define a valid defaultValue by using the schema.model.fields.defaultValue option.

See Also

In this article
Related articles
Not finding the help you need? Improve this article