Edit "Views and Navigation" section in Building Apps

articles/building-apps/forms-data/add-grid/buffered-data.adoc

@@ -0,0 +1,69 @@
+---
+title: Buffered Data
+page-title: How to add a buffered grid to a Vaadin application 
+description: Learn how to populate a grid with data from an application service.
+meta-description: Learn how to populate a grid with data from an application service.
+order: 20
+---
+
+= Add a Buffered Grid
+
+Buffered data refers to data that is *loaded from an application service where the entire filtered result set is fetched at once*. This approach works well when you can guarantee that filtered result sets remain small enough to fit in memory (for example, orders for a single customer, or tasks assigned to a user).
+
+As with <<static-data#,static data>>, *buffered data is loaded into the grid at once and sorted in memory*. However, *the filtering happens in the application service*.
+
+This guide starts with a complete example that you can copy-paste into your project if you want. It then breaks down the example into sections that explain how to populate, filter, and sort the grid. The guides does not cover setting up the Grid component itself; for that, see the <</components/grid#,Grid>> component documentation.
+
+
+== Copy-Paste into Your Project
+
+If you want to quickly try out a buffered grid in your Vaadin application, copy-paste the following code into your project:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/BufferedGridView.java[tags=full,indent=0]
+----
+
+For more detailed walk-through of the example code, continue reading below.
+
+
+== Getting the Data
+
+In this example, the data is coming from a simple service class that _simulates_ fetching data from a database:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/BufferedGridView.java[tags=data,indent=0]
+----
+
+In a real world application, the service would be in its own file. The data would be loaded from a database
+and the result size limited to avoid flooding the UI with too many items. For the same reason an empty filter string returns no items in this example.
+
+.Can you call a repository or Data Access Object (DAO) directly from the UI?
+[NOTE]
+Yes, if you're not using <<../../security/protect-services#,method security>> or any other service layer logic.
+
+
+== Populating and Filtering the Grid
+
+Since the filtering happens in the service, you need to call the service whenever the filter string changes, and then call `setItems()` on the grid with the returned items:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/BufferedGridView.java[tags=filtering,indent=0]
+----
+
+There is one caveat with this approach: *selection is not preserved* between calls to `setItems()`. If you need to preserve selection, consider using a <<paginated-data#,paginated grid>> instead.
+// TODO Add link to guide about selection handling in grids
+
+
+== Sorting
+
+Sorting happens in the grid automatically, for every column that is *marked as sortable*:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/BufferedGridView.java[tags=sorting,indent=0]
+----
+
+For more information about sorting, see the <</components/grid#sorting,Grid>> component documentation.

articles/building-apps/forms-data/add-grid/index.adoc

@@ -0,0 +1,25 @@
+---
+title: Add a Grid
+page-title: How to add a data grid to a Vaadin view 
+description: Learn how to add a data grid to a Vaadin view.
+meta-description: Learn how to add a data grid to a Vaadin view.
+order: 10
+---
+
+= Add a Grid
+
+In business applications, grids are commonly used to display tabular data. Vaadin's <</components/grid#,Grid>> component provides a powerful and flexible way to present large datasets. However, the way you populate, filter, and sort the grid depends on the nature of your data.
+
+Data in business applications typically falls into one of the following categories:
+
+* *Static data*: A fixed collection of objects held entirely in memory that never changes. This is typically reference data (for example, countries, categories, status types) that is either hardcoded or loaded once at application startup. Java `enum` constants also fall into this category. Filtering and sorting happen entirely in memory.
+
+* *Buffered data*: Data that is loaded from an application service where the entire filtered result set is fetched at once. Because all matching records are held in memory, sorting can happen locally without additional service calls. This approach works well when you can guarantee that filtered result sets remain small enough to fit in memory (for example, orders for a single customer, or tasks assigned to a user).
+
+* *Paginated data*: Data that is too large to fit in memory, even after filtering. It is loaded in chunks (pages) from an application service as needed. Both filtering and sorting are delegated to the service layer.
+
+You can use the Grid component with all these data types, but the implementation details differ. Each data type has its own guide:
+
+section_outline::[]
+
+For detailed information about binding data sets to UI components in Vaadin, see the <</flow/binding-data/data-provider#,Data Provider>> reference guide.

articles/building-apps/forms-data/add-grid/paginated-data.adoc

@@ -0,0 +1,98 @@
+---
+title: Paginated Data
+page-title: How to add a paginated grid to a Vaadin application 
+description: Learn how to populate a grid with paginated data from an application service.
+meta-description: Learn how to populate a grid with paginated data from an application service.
+order: 30
+---
+
+= Add a Paginated Grid
+:toclevels: 2
+
+Paginated data refers to datasets that are too large to fit in memory, even after filtering. Instead, *the data is loaded in chunks (pages)* from an application service as needed. *Both filtering and sorting are delegated to the service layer* (typically a database).
+
+In Vaadin, the Grid component has built-in support for paginated data (often referred to as lazy loading in API documentation). When the user scrolls or changes the sorting/filtering criteria, the grid requests the appropriate data page from the backend service. To the user, this appears as a seamless scrolling experience.
+
+This guide starts with a complete example that you can copy-paste into your project if you want. It then breaks down the example into sections that explain how to populate, filter, and sort the grid. The guide does not cover setting up the Grid component itself; for that, see the <</components/grid#,Grid>> component documentation.
+
+
+== Copy-Paste into Your Project
+
+If you want to quickly try out a paginated grid in your Vaadin application, copy-paste the following code into your project:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/PaginatedGridView.java[tags=full,indent=0]
+----
+
+For more detailed walk-through of the example code, continue reading below.
+
+
+== Getting the Data
+
+The Grid component can request pages either by using a page number and size, or by using an offset and limit. If the dataset is sorted, you have to sort it before applying pagination.
+
+This example uses offset-based pagination and uses Vaadin's `QuerySortOrder` API to pass sorting information to the application service:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/PaginatedGridView.java[tags=data,indent=0]
+----
+
+In a real world application, the service would be in its own file and the data would be queried from a database.
+
+
+== Populating the Grid
+
+You populate the grid with paginated data by passing it a callback function that fetches data pages on demand. The callback function receives a `Query` object that contains information about the requested page, sorting, and filtering criteria.
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/PaginatedGridView.java[tags=dataprovider,indent=0]
+----
+
+
+=== Spring Data Support
+
+If you are using Spring Data, use the `setItemsPageable()` method. It passes a `Pageable` object to the callback function that you can use directly with <<../repositories/jpa#,Spring Data repositories>>:
+
+[source,java]
+----
+// Spring Data Repository:
+public interface ItemReposiory<Item, Long> extends PagingAndSortingRepository<Item, Long> {
+    Slice<Item> findByNameContainingIgnoreCase(String name, Pageable pageable);
+}
+
+// In the view class:
+grid.setItemsPageable(pageable -> repository
+    .findByNameContainingIgnoreCase(filterField.getValue(), pageable)
+    .getContent()
+);
+----
+
+.Can you call a repository directly from the UI?
+[NOTE]
+Yes, if you're not using <<../../security/protect-services#,method security>> or any other service layer logic.
+Otherwise, it's better to have an <<../../business-logic/add-service#,application service>> between the UI and the repository.
+
+
+== Filtering
+
+The filtering happens in the application service and the filter string is passed to the service via the callback function. Because of this, you have to refresh the grid whenever the filter string changes:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/PaginatedGridView.java[tags=filtering,indent=0]
+----
+
+
+== Sorting
+
+Sorting happens in the application service and the sort orders are passed to the service via the callback function. Only columns with a specific *sort property* are sortable:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/PaginatedGridView.java[tags=sorting,indent=0]
+----
+
+Sort properties are strings that are passed to the application service. They typically correspond to database column names, but in this example they are mapped to the record fields in the `Item` class.

articles/building-apps/forms-data/add-grid/static-data.adoc

@@ -0,0 +1,79 @@
+---
+title: Static Data
+page-title: How to add a static grid to a Vaadin application 
+description: Learn how to populate a grid with static data.
+meta-description: Learn how to populate a grid with static data in a Vaadin application.
+order: 10
+---
+
+= Add a Static Grid
+
+Static data refers to a fixed collection of objects held entirely in memory — such as *reference data (countries, categories, status types) that is either hardcoded or loaded once at application startup*. Java `enum` constants also fall into this category.
+
+Because the full dataset is available in memory, the static data is loaded into the grid at once. *Filtering and sorting can be performed without additional backend calls*.
+
+This guide starts with a complete example that you can copy-paste into your project if you want. It then breaks down the example into sections that explain how to populate, filter, and sort the grid. The guide does not cover setting up the Grid component itself; for that, see the <</components/grid#,Grid>> component documentation.
+
+
+== Copy-Paste into Your Project
+
+If you want to quickly try out a static grid in your Vaadin application, copy-paste the following code into your project:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/StaticGridView.java[tags=full,indent=0]
+----
+
+For more detailed walk-through of the example code, continue reading below.
+
+
+== Getting the Data
+
+In this example, the static data is a list of record objects returned by a simple service class:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/StaticGridView.java[tags=data,indent=0]
+----
+
+In a real world application, the service would be in its own file. The data could be statically defined as in this example, or loaded from a file or a database during application startup.
+
+
+== Populating the Grid
+
+You populate the grid with static data by passing the collection of items to the grid's `setItems()` method:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/StaticGridView.java[tags=dataprovider,indent=0]
+----
+
+The method returns a `ListDataView` object that you need if you want to filter the data. This is covered in the next section.
+
+
+== Filtering
+
+To filter the grid, you need to add a filter to the `ListDataView`. A filter is a predicate that tests each item in the data set in memory. The filter is applied whenever the data view is refreshed, or when the filter itself is changed.
+
+In this example, the filter checks whether the item's name contains the filter string entered into the filter text field. If the filter string is blank, all items are shown:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/StaticGridView.java[tags=filtering,indent=0]
+----
+
+[NOTE]
+The predicate executes once for each item in the data set. Because of this, you should keep the predicate as simple and efficient as possible. For instance, in the example above, the filter string is converted outside the predicate to avoid doing it repeatedly for each item.
+
+For more information about filtering, see the <</components/grid#filtering,Grid>> component documentation.
+
+== Sorting
+
+Sorting happens in the grid automatically, for every column that is *marked as sortable*:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/grid/StaticGridView.java[tags=sorting,indent=0]
+----
+
+For more information about sorting, see the <</components/grid#sorting,Grid>> component documentation.