Skip to content

Improve parameter support & support mixins w/ registerRoute#229

Merged
kadamwhite merged 14 commits intomasterfrom
enhancement/support-mixins-with-registerroute
Sep 23, 2016
Merged

Improve parameter support & support mixins w/ registerRoute#229
kadamwhite merged 14 commits intomasterfrom
enhancement/support-mixins-with-registerroute

Conversation

@kadamwhite
Copy link
Copy Markdown
Collaborator

registerRoute now takes an optional param array on its configuration object; this array can contain strings that will trigger existing mixins (like filter to be applied to the generated handler:)

site.handler = site.registerRoute( 'myplugin/v1', 'collection/(?P<id>)', {
    // Listing any of these parameters will assign the built-in
    // chaining method that handles the parameter:
    params: [ 'filter', 'before', 'after', 'author', 'parent', 'post' ]
});
// yields
site.handler().forPost( 8 ).author( 92 ).filter( 'etc', 'etera' )...

but if the params array contains a parameter name string that does not map to an existing parameter setter, a basic setter for that parameter will be auto-generated:

site.books = site.registerRoute( 'myplugin/v1', 'books/(?P<id>)', {
    params: [ 'genre' ]
});
// yields "myplugin/v1/books?genre[]=19&genre[]=2000"
site.books().genre([ 19, 2000 ]).toString()

Full changes:

  • Add support for all the most common first-party query parameters (where commonality is a function of number of routes on which the parameter can be used successfully):
  • Add ability to apply existing mixins to registerRoute-registered
    handler methods by referencing the parameter name (fixes Question: filtering custom content types? #203)
  • Add ability to auto-generate a basic .param() convenience wrapper
    for any given query parameter when using registerRoute
  • Document .param method & its derivatives (fixes Documentation of .param() #226)
  • Pork-Barrel the addition of a 404 page to the docs site
  • Remove skipped test blocks for deprecated methods
  • Clean up and standardize several test files
  • Resolve some general docs issues

For #178: pagination & search are applicable to any collection in the
API, so moving them up to the base WPRequest object makes them available
for any and all WPRequest extensions (including those created using
`registerRoute`, which does not yet properly support mixins: #203)
I am modifying wpapi-vagrant-varietal, the VM environment against
which these integration tests are run, to include some custom
post types and taxonomies. This change will prevent that commit
from breaking these integration tests because it switches to
validating that what we expect to be there is there, not that it
is the only content available.
This eliminates all of the tests using the legacy approach of validating
the integration between our library and superagent, instead of testing the
actual public service of the library's methods
- Meta endpoint has been superseded by register_meta functionality
- Auth has moved into the HTTP Transport object
- Pages do not have comment support
Also (and unrelatedly, mea culpa) removes the functionality of `.context()`
which would set authentication when called with "edit"; it is not the
responsibility of the client to enforce authentication, that's the API's job
registerRoute now takes an optional `param` array on its configuration
object; this array can contain strings that will trigger existing mixins
(like `filter` to be applied to the generated handler:)

```js
site.handler = site.registerRoute( 'myplugin/v1', 'collection/(?P<id>)', {
    // Listing any of these parameters will assign the built-in
    // chaining method that handles the parameter:
    params: [ 'filter', 'before', 'after', 'author', 'parent', 'post' ]
});
// yields
site.handler().forPost( 8 ).author( 92 ).filter( 'etc', 'etera' )...
```

but if the `params` array contains a parameter name string that does not
map to an existing parameter setter, a basic setter for that parameter
will be auto-generated:

```js
site.books = site.registerRoute( 'myplugin/v1', 'books/(?P<id>)', {
    params: [ 'genre' ]
});
// yields "myplugin/v1/books?genre[]=19&genre[]=2000"
site.books().genre([ 19, 2000 ]).toString()
```

Full changes:

- Add support for all the most common first-party query parameters
  (where commonality is a function of number of routes on which the
  parameter can be used successfully):
  + `_embed`, `context`, `exclude`, `include`, `offset`, `order`,
  `orderby`, `page`, `perPage`, `search`, and `slug` are supported
  wherever WPRequests are sold (closes #178)
- Add ability to apply existing mixins to `registerRoute`-registered
  handler methods by referencing the parameter name (fixes #203)
- Add ability to auto-generate a basic `.param()` convenience wrapper
  for any given query parameter when using `registerRoute`
- Document `.param` method & its derivatives (fixes #226)
- Pork-Barrel the addition of a 404 page to the docs site
- Remove skipped test blocks for deprecated methods
- Clean up and standardize several test files
- Resolve some general docs issues
@kadamwhite kadamwhite changed the title Enhancement/support mixins with registerroute Improve parameter support & support mixins w/ registerRoute Sep 23, 2016
@kadamwhite
Copy link
Copy Markdown
Collaborator Author

kadamwhite commented Sep 23, 2016

Lots of moving parts in this, but not as many as it seems:

  • Add more query parameters to WPRequest itself
    • M lib/constructors/wp-request.js
    • M lib/endpoint-request.js
    • M lib/mixins/index.js
    • M lib/mixins/parameters.js
    • M tests/unit/lib/constructors/wp-request.js
    • M tests/unit/lib/mixins/parameters.js
  • Add better support for mixins and custom parameters to registerRoute
    • M lib/wp-register-route.js
    • M tests/unit/lib/wp-register-route.js
  • Expand, Correct & Improve docs generally, and add docs for new functionality:
    • M CONTRIBUTING.md
    • M README.md
    • M documentation/_sass/_base.scss
    • M documentation/_sass/_layout.scss
    • M documentation/index.html.combyne
  • Added 404 page
    • A documentation/404.html
    • A documentation/404.html.combyne
    • M build/scripts/generate-docs-markdown.js
  • Refactor out utility methods to create & apply parameter setters:
    • A lib/util/apply-mixin.js
    • A lib/util/parameter-setter.js
    • A tests/unit/lib/util/apply-mixin.js
    • A tests/unit/lib/util/parameter-setter.js
  • Remove dead tests & standardize test naming
    • M tests/unit/route-handlers/media.js
    • M tests/unit/route-handlers/pages.js
    • M tests/unit/route-handlers/posts.js
    • M tests/unit/route-handlers/users.js
    • M tests/integration/taxonomies.js
    • M package.json
    • (Also WPRequest test suite)
  • Add integration tests for /types endpoint
    • A tests/integration/types.js

Copy link
Copy Markdown
Contributor

@edygar edygar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice 👍 ! That solves all the doubts I had, mostly involving the customRoutes and params/mixins and the best practice to use default mixins! Congrats and thank you!

@kadamwhite kadamwhite merged commit 59e5ae9 into master Sep 23, 2016
@kadamwhite kadamwhite deleted the enhancement/support-mixins-with-registerroute branch September 23, 2016 15:40
@sdgluck
Copy link
Copy Markdown
Contributor

sdgluck commented Sep 23, 2016

Awesome - thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation of .param() Question: filtering custom content types? Support all generally-supported query parameters in WPRequest itself

3 participants