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,23 @@
+---
+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::[]

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

@@ -0,0 +1,10 @@
+---
+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
+

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.

articles/building-apps/views/add-master-detail.adoc

@@ -0,0 +1,146 @@
+---
+title: Add a Master-Detail View
+page-title: How to add a master-detail view to a Vaadin application 
+description: Learn how to build a master-detail view.
+meta-description: Learn how to build a master-detail view using Vaadin.
+order: 25
+---
+
+
+= Add a Master-Detail View
+:toclevels: 2
+
+This guide teaches you how to build a rudimentary master-detail view in Vaadin. It focuses on the UI pattern only: how to structure the layout, represent selection in the URL, and synchronize the two. It does not define data models, persistence, or form/grid configuration. 
+
+.Copy-Paste into Your Project
+[TIP]
+====
+If you want to quickly try out a master-detail view, you can copy-paste the following class into your Vaadin project:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=full,indent=0]]
+----
+
+For more detailed instructions on how to build a master-detail view from scratch, continue reading below. The guide uses the same code as in the copy-paste example, but breaks it down into smaller parts with explanations.
+====
+
+
+== What is a Master-Detail View?
+
+In a master-detail view, the user selects an item from a list (the master), and the details of the selected item are shown in another area (the detail). When no item is selected, the detail area is either hidden or shows a placeholder message. 
+
+In the following mock-up, the master is a list of employees, and the detail shows information about the selected employee to the right of the list:
+
+[.device]
+image::images/master-detail.png[A mock-up of a master-detail view showing a list of employees on the left and details of the selected employee on the right]
+
+Master-detail views can look different depending on the application. In the following mock-up, the master is a list of offices, and the detail shows information about the selected office below the list:
+
+[.device]
+image::images/master-detail2.png[A mock-up of a master-detail view showing a list of offices on the top and details of the selected office below the list]
+
+The example code in this guide does not look like the mock-ups above. It uses simple components and focuses only on the UI pattern. Substitute your own components where indicated.
+
+
+== Scaffolding the View
+
+When creating a master-detail view, start with the general structure. You'll need:
+
+* a layout to arrange the master and detail components side by side,
+* a master component (e.g., a <</components/grid#,Grid>>),
+* a detail component (e.g., a form),
+* a placeholder component to show when no detail is selected, and
+* a way to represent the selected item's ID in the URL. 
+
+Because the selected item's ID appears in the URL, the view can always reconstruct the correct UI state after navigation, a refresh, or a shared link.
+
+The following listing shows the minimal structure of a master-detail view, using the same class as in the full example but with the implementation omitted for clarity. It uses a <</components/split-layout#,Split Layout>> to arrange the master and detail components side by side, and a
+<<pass-data/route-parameters#,route parameter>> to represent the selected item's ID:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=scaffolding,indent=0]
+----
+
+With the class structure in place, the next step is to implement the master, detail, and placeholder components that the layout will display.
+
+[NOTE]
+You can use any layout you like to arrange the master and detail components in your application. Split Layout is not the only option, but it works well for this simple example.
+
+== Creating the Master Component
+
+To keep this example simple, the master component is a list of buttons. The buttons represent user selections; each button simulates selecting a different item by navigating to a URL containing its ID:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=master,indent=0]
+----
+
+In a real application, the master component would be a Grid with data loaded from a database. Adding such a Grid is covered in the <<../forms-data/add-grid#,Add a Grid>> guide.
+
+
+=== Implementing Navigation Methods
+
+The master uses <<navigate#your-own-api,navigation utility methods>> for showing the master and detail views. These methods either set or clear the URL parameter, resulting in the `setParameter()` method being called with the appropriate value:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=navigation,indent=0]
+----
+
+The implementation of `setParameter()` is covered later in this guide.
+
+
+== Creating the Detail Component
+
+The detail component in this example is even simpler: it shows the selected ID in a paragraph:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=detail,indent=0]
+----
+
+In a real application, the detail component would be a form. How to build such a form is covered in the <<../forms-data/add-form#,Add a Form>> guide.
+
+
+== Creating the Placeholder
+
+When no detail is selected, it's good practice to show a placeholder message. Here's a simple implementation that shows a message in a paragraph:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=nodetail,indent=0]
+----
+
+This is helpful when a user opens the list view without selecting anything.
+
+
+== Implementing View Logic
+
+With the components in place, the next step is to implement the view logic that ties everything together. Since the master is always visible, add it to the primary area of the Split Layout in the constructor:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=constructor,indent=0]
+----
+
+The secondary area of the Split Layout should be updated based on the user's selection:
+
+* If the user has selected an item, show the detail component. 
+* If no item is selected, show the placeholder component. 
+
+Because you're using a route parameter to represent the selected item's ID, implement this logic in the `setParameter()` method - remove the old detail area, check whether the ID is present, then show either the detail or the placeholder accordingly:
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/buildingapps/masterdetail/MasterDetailView.java[tags=setparameter,indent=0]
+----
+
+In this simple example, the selection is not visible in the master component. In a real application, you'd want to reflect the selection state in the master component as well. 
+
+For example, if you're using a Grid, you could select the corresponding row when an item is selected, and clear the selection when no item is selected. All this logic would also go into the `setParameter()` method.
+
+
+
+With these methods in place, the master-detail view is complete. The next step is to integrate it into your application and enhance it with real data and more complex UI components as needed.