Adding and editing a Data-Grid-Form view

The Data-Grid-Form view is a read-only grid that offers a design-time choice of two edit modes using a form: a read-only or read-only-to-edit form that displays with the grid in a single split screen on the app views page.

At run time, the grid initially displays with the first row selected and a read-only form displayed wherever it fits on the page (to the right or below the grid). Fields from the selected record are displayed in the read-only form as read-only, plain text. These fields can be organized into field groups that appear in labeled tabs within the form. You can then navigate the rows of the grid and select any other record, and the read-only form displays the selected record fields accordingly.

The same is true for a read-only-to-edit form, but you also have the option to edit the selected record or to add a new record to the bound data source. If you choose to edit the selected record, the view overlays the read-only form with a form that displays the fields for editing according to the editor types selected for the fields in the data source. This editable form also provides options to save or cancel the changes you make, or to delete the record from the data source that is displayed in the editable form.

If you select the option to add a new record, the view overlays the read-only form with a similarly editable form that displays the fields for a new record with initial values that you can change before adding the record to the data source. For any editable form, you can either save the changes or cancel the changes and return to the grid with the row selected with the most recently edited or added record, or with the first row selected in the current grid page after canceling a new record add.

At design time, you can separately customize what columns are displayed in the grid and what fields are displayed on the form, as well as other properties that affect the display of the grid, the form, and its data.

When you select an instance of this Data-Grid-Form view in a module at run time, the app displays a page similar to the view labeled Edit Customer in this read-only-to-edit mode example:

The view opens with a read-only grid similar to the previous Customer List Data-Grid view example (see Adding and editing a Data-Grid view), but presented in a split screen with a read-only form containing a tab folder for three field groups, with the Contact tab selected. These form fields are displayed from the record (initially) from the first row on the first page of the grid, then from any grid row that you select.

Clicking Edit above or below the form disables the grid and overlays the read-only form with an editable form, as in this example (a similar editable form displays to add a new record to the bound data source by clicking New):

Each field in the editable form is displayed according to the editor type that has been selected for it in the bound data source. In this example, the displayed value of the form field labeled Sales Rep Name can be changed by selecting a new value from a list (combo-box editor type) that is populated from a foreign key look up. The Kendo UI Builder provides built-in support for foreign key look ups in the forms of Data-Grid* views with forms. For more information on foreign key support, as well as selecting editor types for fields, see Adding and editing a data source.

From here, the edited record can be saved (by clicking Save), deleted (by clicking Delete), or the edit canceled (by clicking Cancel), all of which return to the read-only form displaying fields from an appropriate record, with the grid enabled.

To add a Data-Grid-Form view to a user-created module, edit the module, which opens a view design page in the module (see Figure 22 for an example), then click Add View at the top of the VIEWS pane.

In this example, the dialog box has edit_customer entered as the value of the view Name, Edit Customer entered as the value of the view Label, and Data Grid Form selected as the View Type. The options for entering these values are the same for all user-created views.

The Rolestab opens an Authorization Roles dialog box that allows you to select the user roles that the app can use to authorize access to this view. To know more about roles, see Using roles to authorize user access.

After specifying the Name, Label, and View Type, click Add View to create the specified view and display its view design page for editing, as shown for the edit_customer Data-Grid-Form view in this example:

Header — Similar to the header for the app design page, with the addition of breadcrumbs that track your path in the Designer to the current view design page.

Preview — Either invokes the Kendo UI Generator to rebuild and preview the latest state of the app, or immediately preview the most recent generated build (if one exists). The preview opens in a tab of your default browser using a webpack-dev-server with live data from the data sources mapped to the app views.

Publish — Invokes the Kendo UI Generator to build a deployment version of the app either for testing (Debug) or production (Release) in their own respective locations. For more information on app builds, see App generation and deployment.

— Selects a device whose view you want to simulate in the view design page and which resembles the view as displayed on the physical device at run time. The displayed icon reflects the selected device from these supported devices: Desktop (default), Laptop, Tablet landscape, or Tablet portrait.

The run-time preview that you open from the Designer using Preview always displays according to the physical device where you are running the Designer.

VIEWS pane (in panel on the left) — Lists the views in the current module, including the example edit_customer view. There is also an Add View button (used to create this view) for creating additional views and a search box for locating a view in a long list of views in the module.

View design panel (in the middle) — Shows a design simulation of the view, bounded on the left and top with a vertical and horizontal ruler. The view design panel contains the following elements that are common to all predefined Data-Grid* views, but which might contain different content for each predefined view type:

Custom top html section — Initially not implemented, this custom section appears in the view when you code the content of an HTML <div> element that displays at the top of the view.

Custom middle html section — Initially not implemented, this custom section appears in the view when you code the content of an HTML <div> element that displays in the middle, between the header and data sections of the view.

Data section — In this case, showing a design simulation of the grid and form in split screen as currently configured in the example Data-Grid-Form view instance for display. Note that this includes a simulation of the button configuration above and below for either a read-only or editable form, depending on the edit mode selected for the view (each form style has a subset of these buttons at run time).

Custom bottom html section — Initially not implemented, this custom section appears in the view when you code the content of an HTML <div> element that displays at the bottom of the view.

The design simulation in a view design panel changes as you modify some of the view properties that affect its appearance, and even as you click around in the simulated view design panel, depending on these property settings. For example, the edit_customer view title is set to Edit Customer using the Title property, there are five (5.00) rows on each page of the grid as set for the Page Size property, and the buttons available with the read-only and editable forms are shown for the Read-Only-to-Edit setting of the Edit mode property (see the VIEW PROPERTIES pane description, below, for more information).

The VIEW STYLES pane (in panel on the right) — provides an Edit CSS button that enables you to add and edit CSS styles for the view. Clicking the Edit CSS button opens the view's style.css file in a Monaco editor. The style.cssfile is located in application-folder\app\src\modules\module-folder\view-folder, where application-folder is the path to the folder that contains and is named for your web app, module-folder is the name of the folder defining the module, and view-folder is the name of the folder defining the view.

Note: To apply CSS classes (defined in the style.css file) to the view, you must specify the class names in the CSS Class List property in the VIEW PROPERTIES pane.

VIEW PROPERTIES pane (in panel on the right) — Contains all the properties that you can set that change the design-time appearance and content of the view, as well as some settings that can affect view behavior, such as view-specific event handler settings.

New Title and Edit Title — Allow you to enter separate titles for an editable form displayed for adding a new record and an editable form displayed for editing an existing record, when clicking New and Edit, respectively, on the read-only form.

Data Provider and Data Source — Allow you to select an available data provider and data source to bind to the view. For more information, see Data providers and data sources.

Edit Mode — Allows you to select Read-Only or Read-Only-to-Edit. With Read-Only selected, only a read-only form is displayed with no buttons, since no editable form is available.

Grid Columns — Clicking Edit for this property opens a Grid Columns dialog box that allows you to specify what data source fields appear as columns in the grid, and some features affecting how each field is displayed in the grid. This dialog box works the same for all Data-Grid* views. For more information, see the Grid Columns dialog box description in Adding and editing a Data-Grid view.

Form Fields — Clicking Edit for this property opens a Form Fields dialog box that allows you to specify what data source fields appear as fields on a form, and some features affecting how each field is displayed in the form:

This dialog box provides an Included Fields and Excluded Fields list, similar to the Included Columns and Excluded Columns lists in the Grid Columns dialog box for selecting the data source fields that are displayed in a form. However, for the Form Fields dialog box the fields are listed by their field Label values instead of by their data source field names.

Initially, all the fields in the Included Fields list are listed in a field group labeled Default Group (which you can change) and you can exclude or include them all, or move them individually between the lists. Once you create additional field groups, you must work with each field or field group one at a time, dragging-and-dropping each field either between the lists or between one field group and another. You can also reorder both the individual fields in a field group and the field groups themselves by dragging-and-dropping them within the Included Fields list. The final order reflects both the run-time order in which fields appear in each field group and in which the tabs that select each field group appear on the form.

In this example, three fields groups are defined, labeled Location, Contact, and Status, with most data source fields distributed among them. The field labeled Sales Rep is excluded, because a foreign key look-up field (labeled Sales Rep Name) is used to display a corresponding value instead.

The Properties that affect how each field that you select in Included Fields is displayed in the form include Name, which displays the read-only data source field name (Salesrep, in the example), Label, which allows you to specify a field label for the form, and Format, which allows you to specify a format to augment the value that is displayed in the form (similar to the Format property in the Grid Columns dialog box).

Additional properties (Editor Type *) affect how the specified editor type for the selected field is implemented and displayed in the form. In this example, the editor type is Combo Box, which is selected (as combo-box) in the data source definition for the foreign key look-up field labeled Sales Rep Name. The Id property value must be (and is initially generated as) unique among all editor types in the view, and the Title Text property allows you to specify a value that displays when the user hovers over the field in the form. (Note: In addition to its data source definition, this is all that is required to implement a foreign key look-up field in the form of a Data-Grid* view with forms. For more information, see Adding and editing a data source.)

Page Size through Enable * — Together, these properties control the general presentation of data in the rows and columns of the grid and work the same for all Data-Grid* views. For more information, see the description of these properties in Adding and editing a Data-Grid view.

Events — Provides one or more properties to change the default name of the event handler function defined for each Data-Grid-Form view-specific event:

You can also use properties in the Edit View dialog box to change the default names of event handler functions for general events that apply to all views. You can access this dialog by clicking the

drop-down menu for each view (as shown for the example edit_customer view listed in the VIEWS pane), then clicking the Edit option.

Caution: You must ensure that any change to the default name of an event handler function that you make using its view property you also make to the name of the actual JavaScript function in source code.

You must add custom code to each view event handler function in order to implement any useful behavior for it. The default behavior of these functions has no functional effect. Typically, you do not need to change the default names of event handler functions. However, the view properties exist to allow this name change if you have the need (for example, to avoid a naming conflict with existing JavaScript code you are using elsewhere in the app). For more information on coding both view-specific and general event handler functions (and changing their names in the source), see General view events and View-specific events in this document.