From 6038c23a51776435b4bb395dba4cc1087744ba89 Mon Sep 17 00:00:00 2001 From: Francois Zaninotto Date: Wed, 5 Aug 2015 15:10:15 +0200 Subject: [PATCH] Add permanent filters Closes #548 --- README.md | 48 ++++++++++++++++++++++++++++++++--------- UPGRADE-0.8.md | 30 ++++++++++++++++++++++++++ examples/blog/config.js | 12 +++-------- package.json | 2 +- 4 files changed, 72 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 9ba3a865..0d638530 100644 --- a/README.md +++ b/README.md @@ -346,25 +346,39 @@ Enable or disable lazy loading. * `filters()[field1, field2, ...])` Add filters to the list. Each field maps a property in the API endpoint result. - listView.filters([ + customers.listView().filters([ nga.field('first_name'), nga.field('last_name'), nga.field('age', 'number') ]); - Filters appear when the user clicks on the "Add filter" button at the top of the list. You can also set a filter field as "pinned", to be sure it's always displayed. + Filters appear when the user clicks on the "Add filter" button at the top of the list. Once the user fills the filter widgets, the list is immediately refreshed based on the filter values, with unerlying API requests looking like: + + GET /customers?first_name=XXX&last_name=XXX&age=XXX + + You can also set a filter field as "pinned", to make it always visible. listView.filters([ nga.field('q').label('Search').pinned(true) ]); - Filter fields can be of any type, including `reference` and `template`. this allows to define custom filters with ease. + Filter fields can be of any type, including `reference` and `template`. This allows to define custom filters with ease. listView.filters([ nga.field('q', 'template').label('') .template('
'), ]); + Note that you can use `map()` and `transform()` on filter fields (see [General Field Settings](#general-field-settings)). + +* `permanentFilters({ field1: value, field2: value, ...})` +Add permanent filters to the results list. + + posts.listView().permanentFilters({ + published: true + }); + // calls to the API will be GET /posts?published=true + * `listActions(String|Array)` Add an action column with action buttons on each line. You can pass a list of button names among 'show', 'edit', and 'delete'. @@ -745,15 +759,29 @@ Set the default field for list sorting. Defaults to 'id' * `sortDir(String)` Set the default direction for list sorting. Defaults to 'DESC' -* `filters({ field1: value, field2: value, ...})` -Add filters to the referenced results list. It may be either an object or a function with a single parameter: the current search string. +* `permanentFilters({ field1: value, field2: value, ...})` +Add filters to the referenced results list. This can be very useful to restrict the list of possible values displayed in a dropdown list: - myView.fields([ + comments.editionView().fields([ + nga.field('id'), nga.field('post_id', 'reference') - .targetEntity(post) // Select a target Entity - .targetField(nga.field('title')) // Select a label Field - .filters(function(search) { - // will send `GET /posts?title=foo%` query + .targetEntity(post) + .targetField(nga.field('title')) + .permanentFilters({ + published: true + }); + ]); + + The parameter can be be either an object or a function with a single parameter: the current search string typed by the user in the autocompletion input. + + comments.editionView().fields([ + nga.field('id'), + nga.field('post_id', 'reference') + .targetEntity(post) + .targetField(nga.field('title')) + .permanentFilters(function(search) { + // when the user types 'foo' in the autocompletion input + // fetch the results as `GET /posts?title=foo%` return { title: search + '%' }; diff --git a/UPGRADE-0.8.md b/UPGRADE-0.8.md index a941bb4c..042b4ab2 100644 --- a/UPGRADE-0.8.md +++ b/UPGRADE-0.8.md @@ -96,3 +96,33 @@ nga.field('last_name') return value.toUpperCase(); }); ``` + +## `ReferenceField.filters()` has been renamed to `ReferenceField.permanentFilters()` + +When displaying a reference widget in the edition view, you can filter the list of possible values displayed in the dropdown using the `filters()` function. In 0.8, this function has been renamed to `permanentFilters()`: + +``` diff +nga.entity('comments').fields([ + nga.field('id'), + nga.field('post_id', 'reference') +- .filters({ published: true }) ++ .permanentFilters({ published: true }) +]); +``` + +Just like the previous `filters()` feature, `permanentFilters()` also accepts a function, receiving the string typed by the user in the autocomplete field: + +``` diff +nga.entity('comments').fields([ + nga.field('id'), + nga.field('post_id', 'reference') +- .filters(function(search) { ++ .permanentFilters(function(search) { + return search ? { q: search } : null; + }); +]); +``` + +`filters()` will remain available until the next version, although it logs a deprecation warning in the console. + +**Tip**: `permanentFilters()` now also works on the `listView`, which allows you to define a pre-filtered datagrid. diff --git a/examples/blog/config.js b/examples/blog/config.js index 4a4f3541..b45ff5e2 100644 --- a/examples/blog/config.js +++ b/examples/blog/config.js @@ -116,7 +116,7 @@ nga.field('tags', 'reference_many') // ReferenceMany translates to a select multiple .targetEntity(tag) .targetField(nga.field('name')) - .filters(function(search) { + .permanentFilters(function(search) { return search ? { q: search } : null; }) .remoteComplete(true, { refreshDelay: 300 }) @@ -194,14 +194,8 @@ nga.field('post_id', 'reference') .label('Post') .map(truncate) - .filters(function(search) { - if (!search) { - return; - } - - return { - q: search // Full-text search - }; + .permanentFilters(function(search) { + return search ? { q: search } : null; // Full-text search }) .targetEntity(post) .targetField(nga.field('title')) diff --git a/package.json b/package.json index b8898842..ce797782 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "npm": "^2.10.0" }, "devDependencies": { - "admin-config": "^0.2.7", + "admin-config": "^0.2.10", "angular": "~1.3.15", "angular-bootstrap": "^0.12.0", "angular-mocks": "1.3.14",