[RFR] Update remoteComplete API for better configurability

README.md

@@ -761,42 +761,48 @@ Set the default field for list sorting. Defaults to 'id'
 * `sortDir(String)`
 Set the default direction for list sorting. Defaults to 'DESC'
 
-* `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:
+* `remoteComplete([true|false], options = {})`
+Enable autocompletion by fetching remote results (disabled by default). When enabled, the `reference` widget fetches the results matching the string typed in the autocomplete input from the REST API.
+If set to false, all references (in the limit of `perPage` parameter) would be retrieved at view initialization.
 
         comments.editionView().fields([
             nga.field('id'),
             nga.field('post_id', 'reference')
                 .targetEntity(post)
                 .targetField(nga.field('title'))
-                .permanentFilters({
-                    published: true
-                });
+                .remoteComplete(true) // populate choices from the response of GET /posts?title=XXX
         ]);
 
-    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.
+    Available options are:
+
+    * `refreshDelay`: minimal delay between two API calls in milliseconds. By default: 500.
+    * `searchQuery`: a function returning the parameters to add to the query string basd on the input string.
 
         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 + '%'
-                    };
-                });
+                .remoteComplete(true, {
+                    refreshDelay: 300,
+                    // populate choices from the response of GET /posts?q=XXX
+                    searchQuery: function(search) { return { q: search }; }
+                })
+                .perPage(10) // limit the number of results to 10
         ]);
 
-* `remoteComplete([true|false], options = {})`
-Enable remote completion. When enabled, it fetches remote API references corresponding to your input to refresh the choices list.
-If set to false, all references (in the limit of `perPage` parameter) would be retrieved at view initialization.
-
-Available options are:
+* `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:
 
-    * **refreshDelay:** minimal delay between two API calls in milliseconds. By default: 500.
+        comments.editionView().fields([
+            nga.field('id'),
+            nga.field('post_id', 'reference')
+                .targetEntity(post)
+                .targetField(nga.field('title'))
+                .permanentFilters({
+                    published: true
+                });
+        ]);
 
 * `perPage(integer)`
 Define the maximum number of elements fetched and displayed in the list.
@@ -831,8 +837,8 @@ 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 should be an object.
+* `permanentFilters({ field1: value, field2: value, ...})`
+Add filters to the referenced results list.
 
 * `perPage(integer)`
 Define the maximum number of elements fetched and displayed in the list.
@@ -866,29 +872,38 @@ Define a function that returns parameters for filtering API calls. You can use i
                 })
         ]);
 
-* `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.
 
-        myView.fields([
+* `remoteComplete([true|false], options = {})`
+Enable autocompletion by fetching remote results (disabled by default). When enabled, the `reference` widget fetches the results matching the string typed in the autocomplete input from the REST API.
+If set to false, all references (in the limit of `perPage` parameter) would be retrieved at view initialization.
+
+        post.editionView().fields([
+            nga.field('id'),
             nga.field('tags', 'reference_many')
-                .targetEntity(tag) // Select a target Entity
-                .targetField(nga.field('name')) // Select a label Field
-                .filters(function(search) {
-                    // will send `GET /tags?name=foo%&published=true` query
-                    return {
-                        name: search + '%',
-                        published: true
-                    };
-                });
+                .targetEntity(tag)
+                .targetField(nga.field('name'))
+                .remoteComplete(true) // populate choices from the response of GET /tags?name=XXX
         ]);
 
-* `remoteComplete([true|false], options = {})`
-Enable remote completion. When enabled, it fetches remote API references corresponding to your input to refresh the choices list.
-If set to false, all references (in the limit of `perPage` parameter) would be retrieved at view initialization.
+    Available options are:
 
-Available options are:
+    * `refreshDelay`: minimal delay between two API calls in milliseconds. By default: 500.
+    * `searchQuery`: a function returning the parameters to add to the query string basd on the input string.
 
-    * **refreshDelay:** minimal delay between two API calls in milliseconds. By default: 500.
+        post.editionView().fields([
+            nga.field('id'),
+            nga.field('tags', 'reference_many')
+                .targetEntity(tag)
+                .targetField(nga.field('name'))
+                .remoteComplete(true, {
+                    refreshDelay: 300,
+                    // populate choices from the response of GET /tags?q=XXX
+                    searchQuery: function(search) { return { q: search }; }
+                })
+                .perPage(10) // limit the number of results to 10
+        ]);
 
 ## Customizing the API Mapping
 

examples/blog/config.js

@@ -116,10 +116,10 @@
                 nga.field('tags', 'reference_many') // ReferenceMany translates to a select multiple
                     .targetEntity(tag)
                     .targetField(nga.field('name'))
-                    .permanentFilters(function(search) {
-                        return search ? { q: search } : null;
+                    .remoteComplete(true, {
+                        refreshDelay: 300 ,
+                        searchQuery: function(search) { return { q: search }; }
                     })
-                    .remoteComplete(true, { refreshDelay: 300 })
                     .cssClasses('col-sm-4'), // customize look and feel through CSS classes
                 nga.field('pictures', 'json'),
                 nga.field('views', 'number')
@@ -179,7 +179,10 @@
                     .label('Post')
                     .targetEntity(post)
                     .targetField(nga.field('title'))
-                    .remoteComplete(true, { refreshDelay: 300 })
+                    .remoteComplete(true, {
+                        refreshDelay: 200,
+                        searchQuery: function(search) { return { q: search }; }
+                    })
             ])
             .listActions(['edit', 'delete']);
 
@@ -194,15 +197,15 @@
                 nga.field('post_id', 'reference')
                     .label('Post')
                     .map(truncate)
-                    .permanentFilters(function(search) {
-                        return search ? { q: search } : null; // Full-text search
-                    })
                     .targetEntity(post)
                     .targetField(nga.field('title'))
                     .sortField('title')
                     .sortDir('ASC')
                     .validation({ required: true })
-                    .remoteComplete(true, { refreshDelay: 0 })
+                    .remoteComplete(true, {
+                        refreshDelay: 200,
+                        searchQuery: function(search) { return { q: search }; }
+                    })
             ]);
 
         comment.editionView()

package.json

@@ -9,7 +9,7 @@
     "url": "git://github.com/marmelab/ng-admin.git"
   },
   "devDependencies": {
-    "admin-config": "^0.2.11",
+    "admin-config": "^0.2.12",
     "angular": "~1.3.15",
     "angular-bootstrap": "^0.12.0",
     "angular-mocks": "1.3.14",