Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Grid Pro

Note
Commercial feature

A commercial Vaadin subscription is required to use Grid Pro in your project.

Grid Pro is an extension of the Grid component that provides inline editing with full keyboard navigation.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName)
        .text(Person::setFirstName)
        .setHeader("First name");

grid.addEditColumn(Person::getLastName)
        .text(Person::setLastName)
        .setHeader("Last name");

grid.addEditColumn(Person::getEmail)
        .text(Person::setEmail)
        .setHeader("Email");

grid.addEditColumn(Person::getProfession)
        .text(Person::setProfession)
        .setHeader("Profession");
Note
Features shared with Grid

Grid Pro is an extension of the Grid component and all Grid’s features are applicable to Grid Pro as well.

Usage

Begin editing by:

  • Double clicking on the editable cell

  • Pressing Enter, Space or typing an alphanumeric character when an editable cell is focused

When editing:

  • Esc discards the changes and exits edit mode

  • Enter and Shift+Enter saves the changes and exits edit mode

  • Tab and Shift+Tab saves the changes and focuses the next and previous editable cell, respectively, while remaining in edit mode

Modes

Edit on Single Click

Single Click Edit is a mode that enables the user to begin editing by single clicking on an editable cell.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();
grid.setEditOnClick(true);

Single Cell Edit

By default, when in edit mode, Tab and Shift+Tab moves to the next and previous editable cell, respectively, while remaining in edit mode.

Single Cell Edit is a mode that makes tabbing from one cell to another exit edit mode.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();
grid.setSingleCellEdit(true);

Enter Next Row

Pressing Enter and Shift+Enter saves the changes and exists edit mode by default.

Enter and Shift+Enter can be made to focus the editable cell in the next and previous row, respectively, by using the Enter Next Row mode.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();
grid.setEnterNextRow(true);

Edit Column

Editing is enabled on a per column basis.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();

grid.addColumn(Person::getFullName)
        .setHeader("Name (read-only)");

grid.addEditColumn(Person::getProfession)
        .text(Person::setProfession)
        .setHeader("Profession (editable)");

Grid Pro features three recommended built-in editors: Text Field, Checkbox, and Select.

Editor Usage Recommendation

Text

Editing basic text.

Checkbox

Editing boolean (binary) values.

Select

Selecting a single value from a set of options.

Although Grid Pro can be configured to use any input field for editing, the built-in editors have better keyboard usability and rendering.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName)
        .text(Person::setFirstName)
        .setHeader("First name");

List<String> membershipOptions = Arrays.asList("Regular", "Premium", "VIP");
grid.addEditColumn(Person::getMembership)
        .select(Person::setMembership, membershipOptions)
        .setHeader("Membership");

grid.addEditColumn(Person::isSubscriber)
        .checkbox(Person::setSubscriber)
        .setHeader("Subscriber");

DatePicker datePicker = new DatePicker();
datePicker.setWidthFull();

grid.addEditColumn(GridProEditor::getBirthdayAsLocalDate, birthdayDateRenderer)
        .custom(datePicker, (person, newValue) ->
                person.setBirthday(dateFromLocalDate(newValue))
        ).setHeader("Birthday");

Prevent Saving Changes

You can rollback changes when the entered input is incorrect or invalid.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName)
        .text(Person::setFirstName)
        .setHeader("First name");

grid.addEditColumn(Person::getLastName)
        .text(Person::setLastName)
        .setHeader("Last name");

grid.addEditColumn(Person::getEmail)
        .text((person, newValue) -> {
            if (isValidEmail(newValue)) {
                person.setEmail(newValue);
            } else {
                showErrorNotification("Please enter a valid email address");
            }
        })
        .setHeader("Email");

grid.addEditColumn(person -> person.getAddress().getPhone())
        .text((person, newValue) -> {
            if (isValidPhoneNumber(newValue)) {
                person.getAddress().setPhone(newValue);
            } else {
                showErrorNotification("Please enter a valid phone number");
            }
        })
        .setHeader("Phone");

Styling Editable Cells

Unless all columns are editable, apply styling to visually distinguish between editable and non-editable cells using the editable-cell part name selector. For example, you can suffix read-only columns with “(read-only)” and/or editable columns with “(editable)”.

Open in a
new tab
GridPro<Person> grid = new GridPro<>();
grid.addClassNames("editable-custom-effect");

grid.addColumn(Person::getFirstName).setHeader("First name");
grid.addColumn(Person::getLastName).setHeader("Last name");
grid.addColumn(Person::getMembership).setHeader("Membership");

grid.addEditColumn(Person::getEmail)
        .text(Person::setEmail)
        .setHeader("Email (Editable)");

Best Practises

Inline vs Non-Inline Editing

Inline editing is recommended when:

  • the user typically needs to make a lot of small changes to different items

  • quick editing is important

Non-inline editing is preferable

  • there’s a lot of columns/fields

  • users typically need to edit only one item at a time

  • adding new items is common (as you might want to have edit and create modes work the same way, and creating new items with inline editing is not recommended with Grid Pro).

  • any of the editors need to be bigger than a simple field, such as a Text Area or multi-select field of any kind

  • fields alone may be insufficient, for example when helpers, validation errors or other features are needed

  • explicit save/cancel actions are beneficial, for example to prevent accidental edits

If your use case would benefit more from non-inline editing, consider using CRUD.

Component Usage recommendations

CRUD

Component for creating, displaying, updating and deleting tabular data.

Grid

Component for showing tabular data.

Tree Grid

Component for showing hierarchical data.

1EF2EA01-DD67-42D0-A2C3-34AA957EE054