Mercurial > p > roundup > code
comparison doc/rest.txt @ 5677:1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
will return the label prop for each item returned by the get. Also
added an example of using this to doc/rest.txt.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Tue, 26 Mar 2019 23:29:35 -0400 |
| parents | 6dc4dba1c225 |
| children | b8e8b1b3ec77 |
comparison
equal
deleted
inserted
replaced
| 5676:e70885fe72a4 | 5677:1fa59181ce58 |
|---|---|
| 61 This endpoint supports pagination. With the attributes @page_size and | 61 This endpoint supports pagination. With the attributes @page_size and |
| 62 @page_index, pagination is controlled. The @page_size specifies how many | 62 @page_index, pagination is controlled. The @page_size specifies how many |
| 63 items are displayed at once. The @page_index (which defaults to 1 if not | 63 items are displayed at once. The @page_index (which defaults to 1 if not |
| 64 given) specifies which page number of @page_size items is displayed. If | 64 given) specifies which page number of @page_size items is displayed. If |
| 65 no @page_size is specified, all items are returned. | 65 no @page_size is specified, all items are returned. |
| 66 | |
| 67 Adding the query parameter @verbose=2 to the GET will include the label | |
| 68 property in addition to id and link for the items. This is useful as | |
| 69 documented below in "Searches and selection". | |
| 70 | |
| 66 In addition this method supports searching. Search parameters are names | 71 In addition this method supports searching. Search parameters are names |
| 67 of properties of the given class, e.g., ``status`` for ``issue``. Links | 72 of properties of the given class, e.g., ``status`` for ``issue``. Links |
| 68 and Multilinks can be specified numerically or symbolically, e.g., | 73 and Multilinks can be specified numerically or symbolically, e.g., |
| 69 searching for issues in status ``closed`` can be achieved by searching | 74 searching for issues in status ``closed`` can be achieved by searching |
| 70 for ``status=closed`` or ``status=3`` (provided the ``closed`` status | 75 for ``status=closed`` or ``status=3`` (provided the ``closed`` status |
| 71 has ID 3). Note that searching for strings (e.g. the issue title) | 76 has ID 3). Note that searching for strings (e.g. the issue title, or a |
| 72 performs a case-insensitive substring search, so searching for | 77 keyword name) performs a case-insensitive substring search, so searching |
| 73 title=Something will find all issues with "Something" or "someThing", | 78 for title=Something will find all issues with "Something" or "someThing", |
| 74 etc. in the title. There is currently no way to perform an exact string | 79 etc. in the title. There is currently no way to perform an exact string |
| 75 match. | 80 match. |
| 76 | 81 |
| 77 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a | 82 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a |
| 78 ``link`` attribute contains the link to the item, ``id`` contains the | 83 ``link`` attribute contains the link to the item, ``id`` contains the |
| 174 >>> print(r.json()) | 179 >>> print(r.json()) |
| 175 >>> d = {'@op:'action', '@action_name':'restore'} | 180 >>> d = {'@op:'action', '@action_name':'restore'} |
| 176 >>> r = s.patch(u + 'issue/42', data = d, headers = h) | 181 >>> r = s.patch(u + 'issue/42', data = d, headers = h) |
| 177 >>> print(r.json()) | 182 >>> print(r.json()) |
| 178 | 183 |
| 184 Searches and selection | |
| 185 ====================== | |
| 186 | |
| 187 One difficult interface issue is selection of items from a long list. | |
| 188 Using multi-item selects requires loading a lot of data (e.g. consider | |
| 189 a selection tool to select one or more issues as in the classic | |
| 190 superseder field). | |
| 191 | |
| 192 This can be made easier using javascript selection tools like select2, | |
| 193 selectize.js, chosen etc. These tools can query a remote data provider | |
| 194 to get a list of items for the user to select from. | |
| 195 | |
| 196 Consider a multi-select box for the superseder property. Using | |
| 197 selectize.js (and jquery) code similar to: | |
| 198 | |
| 199 $('#superseder').selectize({ | |
| 200 valueField: 'id', | |
| 201 labelField: 'title', | |
| 202 searchField: 'title', ... | |
| 203 load: function(query, callback) { | |
| 204 if (!query.length) return callback(); | |
| 205 $.ajax({ | |
| 206 url: '.../rest/data/issue?@verbose=2&title=' | |
| 207 + encodeURIComponent(query), | |
| 208 type: 'GET', | |
| 209 error: function() {callback();}, | |
| 210 success: function(res) { | |
| 211 callback(res.data.collection);} | |
| 212 | |
| 213 Sets up a box that a user can type the word "request" into. Then | |
| 214 selectize.js will use that word to generate an ajax request with the | |
| 215 url: .../rest/data/issue?@verbose=2&title=request | |
| 216 | |
| 217 This will return data like: | |
| 218 | |
| 219 { | |
| 220 "data": { | |
| 221 "@total_size": 440, | |
| 222 "collection": [ | |
| 223 { | |
| 224 "link": ".../rest/data/issue/8", | |
| 225 "id": "8", | |
| 226 "title": "Request for Power plugs" | |
| 227 }, | |
| 228 { | |
| 229 "link": ".../rest/data/issue/27", | |
| 230 "id": "27", | |
| 231 "title": "Request for foo" | |
| 232 }, | |
| 233 | |
| 234 selectize.js will look at these objects (as passed to | |
| 235 callback(res.data.collection)) and create a select list from the each | |
| 236 object showing the user the labelField (title) for each object and | |
| 237 associating each title with the corresponding valueField (id). The | |
| 238 example above has 440 issues returned from a total of 2000 | |
| 239 issues. Only 440 had the word "request" somewhere in the title greatly | |
| 240 reducing the amount of data that needed to be transferred. | |
| 241 | |
| 242 Similar things can be set up to search a large list of keywords using | |
| 243 | |
| 244 .../rest/data/keyword?@verbose=2&name=some | |
| 245 | |
| 246 which would return: "some keyword" "awesome" "somebody" making | |
| 247 selections for links and multilinks much easier. | |
| 248 | |
| 249 Hopefully future enhancements will allow get on a collection to | |
| 250 include other fields. Why do we want this? Selectize.js can set up | |
| 251 option groups (optgroups) in the select pulldown. So by including | |
| 252 status in the returned data: | |
| 253 | |
| 254 { | |
| 255 "link": ".../rest/data/issue/27", | |
| 256 "id": "27", | |
| 257 "title": "Request for foo", | |
| 258 'status": "open" | |
| 259 }, | |
| 260 | |
| 261 a select widget like: | |
| 262 | |
| 263 === New === | |
| 264 A request | |
| 265 === Open === | |
| 266 Request for bar | |
| 267 Request for foo | |
| 268 | |
| 269 etc. can be generated. Also depending on the javascript library, other | |
| 270 fields can be used for subsearch and sorting. |