Merge pull request #17 from xdev-software/develop

Release

CHANGELOG.md

@@ -1,2 +1,16 @@
+# 2.0.0
+_Reworked component_
+
+* New customizable UI, including
+  * nested filters (AND, OR, NOT)
+    * depth can be limited
+  * customizable operations (=,>,<,contains,is empty)
+  * support for multiple value types
+    * can easily be bound with Vaadin components
+* Improved support for QueryParameters
+* Better translation support
+
+v1 component can now be found at https://github.com/xdev-software/vaadin-simple-grid-filter
+
 # 1.0.0
 _Initial release_

README.md

@@ -1,15 +1,50 @@
-[![Published on Vaadin Directory](https://img.shields.io/badge/Vaadin%20Directory-published-00b4f0?logo=vaadin)](https://vaadin.com/directory/component/vaadin-grid-filter)
+[![Published on Vaadin Directory](https://img.shields.io/badge/Vaadin%20Directory-published-00b4f0?logo=vaadin)](https://vaadin.com/directory/component/grid-filter-for-vaadin)
 [![Latest version](https://img.shields.io/maven-central/v/software.xdev/vaadin-grid-filter?logo=apache%20maven)](https://mvnrepository.com/artifact/software.xdev/vaadin-grid-filter)
 [![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/vaadin-grid-filter/check-build.yml?branch=develop)](https://github.com/xdev-software/vaadin-grid-filter/actions/workflows/check-build.yml?query=branch%3Adevelop)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xdev-software_vaadin-grid-filter&metric=alert_status)](https://sonarcloud.io/dashboard?id=xdev-software_vaadin-grid-filter)
 ![Vaadin 24+](https://img.shields.io/badge/Vaadin%20Platform/Flow-24+-00b4f0)
 
 # vaadin-grid-filter
 
-A Vaadin Flow component for filtering Grids.
+A customizable Vaadin Flow component for filtering Grids.
 
 ![demo](assets/demo.png)
 
+## Features
+* Customizable and dynamic filter UI
+  * Most common filters, operations and value types are supported out of the box
+  * Nested filters (AND, OR, NOT)
+    * depth can be limited
+  * customizable operations (=,>,<,contains,is empty)
+  * support for multiple value types
+    * can easily be bound with Vaadin components
+* Query parameter support
+* Support for custom translations
+
+> [!NOTE]
+> If you are looking for a simpler component you may check out our [simple-grid-filter](https://github.com/xdev-software/vaadin-simple-grid-filter).
+
+## Usage
+
+Here is a very simple example how the GridFilter can be used:
+```java
+Grid<Person> grid = createGrid();
+
+GridFilter<Person> filter = GridFilter.createDefault(grid)
+  .withFilterableField("ID", Person::id, Integer.class)
+  .withFilterableField("First Name", Person::firstName, String.class);
+
+this.add(filter, grid);
+```
+
+To get started further it's recommended to have a look at the [demo](./vaadin-grid-filter-demo).<br/>
+A description how to get it running can be found [below](#run-the-demo).
+
+> [!IMPORTANT]
+> This component is designed for "in memory" filtering of small to medium sized amounts of data.
+
+> [!NOTE]
+> Filtering multiple thousand items with complex filtering conditions can drastically impact performance and make the UI unresponsive!<br/> In these cases it's recommended to use backend filtering solutions like database queries or search engines like [ElasticSearch](https://en.wikipedia.org/wiki/Elasticsearch) in combination with a customized UI search framework. If you need help in implementing these feel free to [contact us](https://xdev.software/en/services/support).
 
 ## Installation
 [Installation guide for the latest release](https://github.com/xdev-software/vaadin-grid-filter/releases/latest#Installation)

pom.xml

@@ -6,7 +6,7 @@
 
 	<groupId>software.xdev</groupId>
 	<artifactId>vaadin-grid-filter-root</artifactId>
-	<version>1.0.2-SNAPSHOT</version>
+	<version>2.0.0-SNAPSHOT</version>
 	<packaging>pom</packaging>
 
 	<organization>

vaadin-grid-filter-demo/pom.xml

@@ -7,11 +7,11 @@
 	<parent>
 		<groupId>software.xdev</groupId>
 		<artifactId>vaadin-grid-filter-root</artifactId>
-		<version>1.0.2-SNAPSHOT</version>
+		<version>2.0.0-SNAPSHOT</version>
 	</parent>
 
 	<artifactId>vaadin-grid-filter-demo</artifactId>
-	<version>1.0.2-SNAPSHOT</version>
+	<version>2.0.0-SNAPSHOT</version>
 	<packaging>jar</packaging>
 
 	<organization>

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/DemoView.java

@@ -0,0 +1,81 @@
+package software.xdev.vaadin.gridfilter;
+
+import java.util.List;
+
+import com.vaadin.flow.component.AttachEvent;
+import com.vaadin.flow.component.Composite;
+import com.vaadin.flow.component.grid.Grid;
+import com.vaadin.flow.component.grid.GridVariant;
+import com.vaadin.flow.component.html.Anchor;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+import com.vaadin.flow.data.renderer.ComponentRenderer;
+import com.vaadin.flow.router.PageTitle;
+import com.vaadin.flow.router.Route;
+
+import software.xdev.vaadin.gridfilter.demo.LocalizationDemo;
+import software.xdev.vaadin.gridfilter.demo.MaxNestedDepthDemo;
+import software.xdev.vaadin.gridfilter.demo.MinimalisticDemo;
+import software.xdev.vaadin.gridfilter.demo.QueryParameterDemo;
+
+
+@PageTitle("Grid Filter demos")
+@Route("")
+public class DemoView extends Composite<VerticalLayout>
+{
+	private final Grid<Example> grExamples = new Grid<>();
+
+	public DemoView()
+	{
+		this.grExamples
+			.addColumn(new ComponentRenderer<>(example -> {
+				final Anchor anchor = new Anchor(example.route(), example.name());
+
+				final Span spDesc = new Span(example.desc());
+				spDesc.getStyle().set("font-size", "90%");
+				spDesc.getStyle().set("white-space", "pre");
+
+				final VerticalLayout vl = new VerticalLayout(anchor, spDesc);
+				vl.setSpacing(false);
+				return vl;
+			}))
+			.setHeader("Available demos");
+
+		this.grExamples.setSizeFull();
+		this.grExamples.addThemeVariants(GridVariant.LUMO_COMPACT, GridVariant.LUMO_NO_BORDER);
+
+		this.getContent().add(this.grExamples);
+		this.getContent().setHeightFull();
+	}
+
+	@Override
+	protected void onAttach(final AttachEvent attachEvent)
+	{
+		this.grExamples.setItems(List.of(
+			new Example(
+				MinimalisticDemo.NAV,
+				"Minimalistic",
+				"Showcasing the simplest form of using the component"
+			),
+			new Example(
+				QueryParameterDemo.NAV,
+				"Store filters in QueryParameter",
+				"Shows how filters can be persisted in and loaded from QueryParameters/Url"
+			),
+			new Example(
+				MaxNestedDepthDemo.NAV,
+				"Limit depth/nesting of filters",
+				"Limits the how many filters can be nested"
+			),
+			new Example(
+				LocalizationDemo.NAV,
+				"Localization",
+				"Showcases how localization can be done (UI in German)"
+			)
+		));
+	}
+
+	record Example(String route, String name, String desc)
+	{
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/demo/AbstractDemo.java

@@ -0,0 +1,33 @@
+package software.xdev.vaadin.gridfilter.demo;
+
+import java.time.LocalDate;
+
+import com.vaadin.flow.component.AttachEvent;
+import com.vaadin.flow.component.grid.Grid;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+
+import software.xdev.vaadin.gridfilter.GridFilter;
+import software.xdev.vaadin.gridfilter.model.Department;
+import software.xdev.vaadin.gridfilter.model.Person;
+
+
+public class AbstractDemo extends VerticalLayout
+{
+	protected final Grid<Person> grid = new Grid<>(Person.class, true);
+
+	protected GridFilter<Person> createDefaultFilter()
+	{
+		return GridFilter.createDefault(this.grid)
+			.withFilterableField("ID", Person::id, Integer.class)
+			.withFilterableField("First Name", Person::firstName, String.class)
+			.withFilterableField("Birthday", Person::birthday, LocalDate.class)
+			.withFilterableField("Married", Person::married, Boolean.class)
+			.withFilterableField("Department", Person::department, Department.class);
+	}
+
+	@Override
+	protected void onAttach(final AttachEvent attachEvent)
+	{
+		this.grid.setItems(Person.list());
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/demo/LocalizationDemo.java

@@ -0,0 +1,31 @@
+package software.xdev.vaadin.gridfilter.demo;
+
+import com.vaadin.flow.router.Route;
+
+import software.xdev.vaadin.gridfilter.GridFilter;
+import software.xdev.vaadin.gridfilter.GridFilterLocalizationConfig;
+import software.xdev.vaadin.gridfilter.model.Person;
+
+
+@Route(LocalizationDemo.NAV)
+public class LocalizationDemo extends AbstractDemo
+{
+	public static final String NAV = "/localization";
+
+	public LocalizationDemo()
+	{
+		final GridFilter<Person> filter = this.createDefaultFilter()
+			.withLocalizationConfig(new GridFilterLocalizationConfig()
+				.with(GridFilterLocalizationConfig.BLOCK_AND, "UND")
+				.with(GridFilterLocalizationConfig.BLOCK_OR, "ODER")
+				.with(GridFilterLocalizationConfig.BLOCK_NOT, "NICHT")
+				.with(GridFilterLocalizationConfig.OP_CONTAINS, "enthält")
+				.with(GridFilterLocalizationConfig.OP_GREATER_THAN, "größer als")
+				.with(GridFilterLocalizationConfig.OP_LESS_THAN, "kleiner als")
+				.with(GridFilterLocalizationConfig.OP_EQUALS, "ist gleich")
+				.with(GridFilterLocalizationConfig.OP_IS_EMPTY, "ist leer")
+				.with(GridFilterLocalizationConfig.CONDITION, "Bedingung"));
+
+		this.add(filter, this.grid);
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/demo/MaxNestedDepthDemo.java

@@ -0,0 +1,21 @@
+package software.xdev.vaadin.gridfilter.demo;
+
+import com.vaadin.flow.router.Route;
+
+import software.xdev.vaadin.gridfilter.GridFilter;
+import software.xdev.vaadin.gridfilter.model.Person;
+
+
+@Route(MaxNestedDepthDemo.NAV)
+public class MaxNestedDepthDemo extends AbstractDemo
+{
+	public static final String NAV = "/maxNestedDepth";
+
+	public MaxNestedDepthDemo()
+	{
+		final GridFilter<Person> filter = this.createDefaultFilter()
+			.withMaxNestedDepth(1);
+
+		this.add(filter, this.grid);
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/demo/MinimalisticDemo.java

@@ -0,0 +1,27 @@
+package software.xdev.vaadin.gridfilter.demo;
+
+import com.vaadin.flow.component.details.Details;
+import com.vaadin.flow.component.details.DetailsVariant;
+import com.vaadin.flow.router.Route;
+
+import software.xdev.vaadin.gridfilter.GridFilter;
+import software.xdev.vaadin.gridfilter.model.Person;
+
+
+@Route(MinimalisticDemo.NAV)
+public class MinimalisticDemo extends AbstractDemo
+{
+	public static final String NAV = "/minimalistic";
+
+	public MinimalisticDemo()
+	{
+		final GridFilter<Person> filter = this.createDefaultFilter();
+
+		// Add filter inside details block for better looking UI
+		final Details details = new Details("Filter data");
+		details.addThemeVariants(DetailsVariant.FILLED);
+		details.add(filter);
+		details.setOpened(true);
+		this.add(details, this.grid);
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/demo/QueryParameterDemo.java

@@ -0,0 +1,34 @@
+package software.xdev.vaadin.gridfilter.demo;
+
+import com.vaadin.flow.router.AfterNavigationEvent;
+import com.vaadin.flow.router.AfterNavigationObserver;
+import com.vaadin.flow.router.Route;
+
+import software.xdev.vaadin.gridfilter.GridFilter;
+import software.xdev.vaadin.gridfilter.model.Person;
+import software.xdev.vaadin.gridfilter.queryparameter.GridFilterQueryParameterAdapter;
+
+
+@SuppressWarnings("java:S1948")
+@Route(QueryParameterDemo.NAV)
+public class QueryParameterDemo extends AbstractDemo implements AfterNavigationObserver
+{
+	public static final String NAV = "/queryparameter";
+
+	private final GridFilterQueryParameterAdapter queryParameterAdapter;
+
+	public QueryParameterDemo()
+	{
+		final GridFilter<Person> filter = this.createDefaultFilter();
+
+		this.queryParameterAdapter = new GridFilterQueryParameterAdapter(filter, "filter");
+
+		this.add(filter, this.grid);
+	}
+
+	@Override
+	public void afterNavigation(final AfterNavigationEvent event)
+	{
+		this.queryParameterAdapter.afterNavigation(event);
+	}
+}

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/model/Department.java → vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/model/Department.java

@@ -1,4 +1,4 @@
-package software.xdev.vaadin.model;
+package software.xdev.vaadin.gridfilter.model;
 
 public enum Department
 {

vaadin-grid-filter-demo/src/main/java/software/xdev/vaadin/gridfilter/model/Person.java

@@ -0,0 +1,32 @@
+package software.xdev.vaadin.gridfilter.model;
+
+import java.time.LocalDate;
+import java.util.List;
+
+
+public record Person(
+	Integer id,
+	String firstName,
+	String lastName,
+	LocalDate birthday,
+	boolean married,
+	double salary,
+	Department department
+)
+{
+	@SuppressWarnings("checkstyle:MagicNumber")
+	public static List<Person> list()
+	{
+		return List.of(
+			new Person(0, "Siegbert", "Schmidt", LocalDate.of(1990, 12, 17), false, 1000, Department.HR),
+			new Person(1, "Herbert", "Maier", LocalDate.of(1967, 10, 13), false, 1000, Department.HR),
+			new Person(2, "Hans", "Lang", LocalDate.of(2002, 5, 9), true, 9050.60, Department.HR),
+			new Person(3, "Anton", "Meier", LocalDate.of(1985, 1, 24), true, 8000.75, Department.HR),
+			new Person(4, "Sarah", "Smith", LocalDate.of(1999, 6, 1), false, 5000, Department.IT),
+			new Person(5, "Niklas", "Sommer", LocalDate.of(1994, 11, 8), true, 4000.33, Department.HR),
+			new Person(6, "Hanna", "Neubaum", LocalDate.of(1986, 8, 15), true, 3000, Department.HR),
+			new Person(8, "Laura", "Fels", LocalDate.of(1996, 3, 20), true, 1000.50, Department.HR),
+			new Person(7, "Sofia", "Sommer", LocalDate.of(1972, 4, 14), false, 2000, Department.ACCOUNTING)
+		);
+	}
+}