Add permanent filters

Closes marmelab#548

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('<div class="input-group"><input type="text" ng-model="value" placeholder="Search" class="form-control"></input><span class="input-group-addon"><i class="glyphicon glyphicon-search"></i></span></div>'),
         ]);
 
+    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 + '%'
                     };

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.

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'))

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",