Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improved the documentation for Foxx controller

This commit is contained in:
Michael Hackstein 2015-08-18 16:14:39 +02:00
parent 580066fe8a
commit 602c3d0d59
6 changed files with 282 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Documentation/Books/Users/Foxx/Develop/Controller.mdpp
View File

@ -1,4 +1,4 @@
!CHAPTER Details on FoxxController
!CHAPTER Details on Controller
!SUBSECTION Create
<!-- js/server/modules/org/arangodb/foxx/controller.js -->
@ -86,12 +86,16 @@ API by chaining the following methods onto your path definition:
<!-- js/server/modules/org/arangodb/foxx/request_context.js -->
@startDocuBlock JSF_foxx_RequestContext_notes
!SUBSECTION pathParams in buffer
@startDocuBlock JSF_foxx_RequestContextBuffer_pathParam
!SUBSECTION bodyParams in buffer
@startDocuBlock JSF_foxx_RequestContextBuffer_queryParam
!SUBSECTION extend
In many use-cases several of the functions are always used in a certain combination (e.g.: `onlyIf` with `errorResponse`).
In order to avoid duplicating this equal usage for several routes in your application you can
extend the controller with your own functions.
These functions can simply combine several of the above on a single name, so you only have to
invoke your self defined single function on all routes using these extensions.
@startDocuBlock JSF_foxx_controller_extend
!SECTION Documenting and constraining all routes
@ -123,18 +127,24 @@ ctrl.get('/another/route', function (req, res) {
}); // no errorResponse needed here either
```
!SUBSECTION Buffer errorResponse
!SUBSECTION errorResponse
<!-- js/server/modules/org/arangodb/foxx/request_context.js -->
@startDocuBlock JSF_foxx_RequestContextBuffer_errorResponse
!SUBSECTION Buffer onlyIf
!SUBSECTION onlyIf
<!-- js/server/modules/org/arangodb/foxx/request_context.js -->
@startDocuBlock JSF_foxx_RequestContextBuffer_onlyIf
!SUBSECTION Buffer onlyIfAuthenticated
!SUBSECTION onlyIfAuthenticated
<!-- js/server/modules/org/arangodb/foxx/request_context.js -->
@startDocuBlock JSF_foxx_RequestContextBuffer_onlyIfAuthenticated
!SUBSECTION pathParam
@startDocuBlock JSF_foxx_RequestContextBuffer_pathParam
!SUBSECTION bodyParam
@startDocuBlock JSF_foxx_RequestContextBuffer_queryParam
!SECTION Before and After Hooks
@ -222,9 +232,6 @@ convenience methods:
<!-- js/server/modules/org/arangodb/foxx/base_middleware.js -->
@startDocuBlock JSF_foxx_BaseMiddleware_request_rawBodyBuffer
<!-- js/server/modules/org/arangodb/foxx/base_middleware.js -->
@startDocuBlock JSF_foxx_BaseMiddleware_request_requestParts
!SUBSECTION params
<!-- js/server/modules/org/arangodb/foxx/base_middleware.js -->
@startDocuBlock JSF_foxx_BaseMiddleware_request_params
@ -233,6 +240,10 @@ convenience methods:
<!-- js/server/modules/org/arangodb/foxx/base_middleware.js -->
@startDocuBlock JSF_foxx_BaseMiddleware_request_cookie
!SUBSECTION requestParts
Only useful for multi-part requests.
<!-- js/server/modules/org/arangodb/foxx/base_middleware.js -->
@startDocuBlock JSF_foxx_BaseMiddleware_request_requestParts
!SECTION The Response Object
@ -341,6 +352,3 @@ To use the application-specific authentication in your own app, first activate i
!SUBSUBSECTION Restricting routes
To restrict routes, see the documentation for Documenting and Restraining the routes.
@startDocuBlock JSF_foxx_controller_extend

3
Documentation/Books/Users/Foxx/Develop/View.mdpp
View File

@ -1,3 +0,0 @@
@startDocuBlock JSF_foxx_TemplateMiddleware_initializer
@startDocuBlock JSF_foxx_TemplateMiddleware_response_render

3
Documentation/Books/Users/SUMMARY.md
View File

@ -5,7 +5,7 @@
* [Windows](Installing/Windows.md)
* [Compiling](Installing/Compiling.md)
* [Upgrading](Installing/Upgrading.md)
* [Incompatible changes in 2.6](Upgrading/UpgradingChanges27.md)
* [Incompatible changes in 2.7](Upgrading/UpgradingChanges27.md)
* [Incompatible changes in 2.6](Upgrading/UpgradingChanges26.md)
* [Upgrading to 2.6](Upgrading/Upgrading26.md)
* [Incompatible changes in 2.5](Upgrading/UpgradingChanges25.md)
@ -112,7 +112,6 @@
* [Controller](Foxx/Develop/Controller.md)
* [Scripts](Foxx/Develop/Scripts.md)
* [Model](Foxx/Develop/Model.md)
* [View](Foxx/Develop/View.md)
* [Repository](Foxx/Develop/Repository.md)
* [Queries](Foxx/Develop/Queries.md)
* [Sessions](Foxx/Develop/Sessions.md)

183
js/server/modules/org/arangodb/foxx/controller.js
View File

@ -275,7 +275,7 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_initializer
///
/// `new FoxxController(applicationContext, options)`
/// `new Controller(applicationContext, options)`
///
/// This creates a new Controller. The first argument is the controller
/// context available in the variable *applicationContext*. The second one is an
@ -417,11 +417,25 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_head
///
/// `FoxxController#head(path, callback)`
/// `Controller.head(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `head`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.head('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// This handles requests from the HTTP verb *head*. You have to give a
/// function as *callback*. It will get a request and response object as its
/// arguments
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@ -432,14 +446,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_get
///
/// `FoxxController#get(path, callback)`
/// `Controller.get(path, callback)`
///
/// This handles requests from the HTTP verb *get*.
///
/// When defining a route you can also define a so called 'parameterized'
/// *path* like */goose/:barn*. In this case you can later get the value
/// the user provided for *barn* via the *params* function (see the Request
/// object).
/// Defines a new route on `path` that handles requests from the HTTP verb `get`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
@ -459,10 +475,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_post
///
/// `FoxxController#post(path, callback)`
/// `Controller.post(path, callback)`
///
/// This handles requests from the HTTP verb *post*. See above for the
/// arguments you can give.
/// Defines a new route on `path` that handles requests from the HTTP verb `post`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
@ -482,10 +504,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_put
///
/// `FoxxController#put(path, callback)`
/// `Controller.put(path, callback)`
///
/// This handles requests from the HTTP verb *put*. See above for the arguments
/// you can give.
/// Defines a new route on `path` that handles requests from the HTTP verb `put`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
@ -505,10 +533,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_patch
///
/// `FoxxController#patch(path, callback)`
/// `Controller.patch(path, callback)`
///
/// This handles requests from the HTTP verb *patch*. See above for the
/// arguments you can give.
/// Defines a new route on `path` that handles requests from the HTTP verb `patch`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
@ -528,10 +562,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_delete
///
/// `FoxxController#delete(path, callback)`
/// `Controller.delete(path, callback)`
///
/// This handles requests from the HTTP verb *delete*. See above for the
/// arguments you can give.
/// Defines a new route on `path` that handles requests from the HTTP verb `delete`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
@ -556,14 +596,16 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_before
///
/// `FoxxController#before(path, callback)`
/// `Controller.before(path, callback)`
///
/// The before function takes a *path* on which it should watch and a
/// function that it should execute before the routing takes place. If you do
/// omit the path, the function will be executed before each request, no matter
/// the path. Your function gets a Request and a Response object.
/// Defines an additional function on the route `path` which will be executed
/// before the callback defined for a specific HTTP verb is executed.
/// The `callback` function has the same signature as the `callback` in the
/// specific route.
/// You can also omit the `path`, in this case `callback` will be executed
/// before handleing any request in this Controller.
///
/// If your callback returns the Boolean value *false*, the route handling
/// If `callback` returns the Boolean value `false`, the route handling
/// will not proceed. You can use this to intercept invalid or unauthorized
/// requests and prevent them from being passed to the matching routes.
///
@ -601,10 +643,10 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_after
///
/// `FoxxController#after(path, callback)`
/// `Controller.after(path, callback)`
///
/// This works pretty similar to the before function. But it acts after the
/// execution of the handlers (Big surprise, I suppose).
/// Similar to `Controller.before(path, callback)` but `callback` will be invoked
/// after the request is handled in the specific route.
///
/// @EXAMPLES
///
@ -635,14 +677,17 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_around
///
/// `FoxxController#around(path, callback)`
/// `Controller.around(path, callback)`
///
/// The around function takes a *path* on which it should watch and a function
/// that it should execute around the function which normally handles the
/// route. If you do omit the path, the function will be executed before each
/// request, no matter the path. Your function gets a Request and a Response
/// object and a next function, which you must call to execute the handler for
/// that route.
/// Similar to `Controller.before(path, callback)` `callback` will be invoked
/// instead of the specific handler.
/// `callback` takes two additional paramaters `opts` and `next` where
/// `opts` contains options assigned to the route and `next` is a function.
/// Whenever you call `next` in `callback` the specific handler is invoked,
/// if you do not call `next` the specific handler will not be invoked at all.
/// So using around you can execute code before and after a specific handler
/// and even call the handler only under certain circumstances.
/// If you omit `path` `callback` will be called on every request.
///
/// @EXAMPLES
///
@ -677,10 +722,10 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_activateAuthentication
///
/// `FoxxController#activateAuthentication(opts)`
/// `Controller.activateAuthentication(opts)`
///
/// To activate authentication for this controller, first call this function.
/// Provide the following arguments:
/// To activate authentication for this controller, call this function before defining any routes.
/// In the `opts` object you can set the following keys:
///
/// * *type*: Currently we only support *cookie*, but this will change in the future
/// * *cookieLifetime*: An integer. Lifetime of cookies in seconds
@ -712,10 +757,10 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_activateSessions
///
/// `FoxxController#activateAuthentication(opts)`
/// `Controller.activateSessions(opts)`
///
/// To activate sessions for this sessions, first call this function.
/// Provide the following arguments:
/// To activate sessions for this controller, call this function before defining any routes.
/// In the `opts` object you can set the following keys:
///
/// * *type*: Currently we only support *cookie*, but this will change in the future. Defaults to *"cookie"*.
/// * *cookieName*: A string used as the name of the cookie. Defaults to *"sid"*.
@ -737,6 +782,7 @@ class Controller {
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
activateSessions(opts) {
var sessions = require('org/arangodb/foxx/sessions');
_.extend(this, sessionControllerProps);
@ -748,11 +794,11 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_apiDocumentation
///
/// `FoxxController#apiDocumentation(path, [opts])`
/// `Controller.apiDocumentation(path, [opts])`
///
/// Mounts the API documentation (Swagger) at the given *path*.
/// Mounts the API documentation (Swagger) at the given `path`.
///
/// Note that the **path** can use URL parameters as usual but must not use any
/// Note that the `path` can use URL parameters as usual but must not use any
/// wildcard (`*`) or optional (`:name?`) parameters.
///
/// The optional **opts** can be an object with any of the following properties:
@ -819,12 +865,49 @@ class Controller {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_extend
///
/// `FoxxController#extend(extensions)`
/// `Controller.extend(extensions)`
///
/// Extends all functions to define routes in this controller.
/// This allows to combine several route extensions with the invocation
/// of a single function.
/// This is especially useful if you use the same input parameter in several routes of
/// your controller and want to apply the same validation, documentation and error handling
/// for it.
///
/// The `extensions` parameter is a JSON object with arbitrary keys.
/// Each key is used as the name of the function you want to define (you cannot overwrite
/// internal functions like `pathParam`) and the value is a function that will be invoked.
/// This function can get arbitrary many arguments and the `this` of the function is bound
/// to the route definition object (e.g. you can use `this.pathParam()`).
/// Your newly defined function is chainable similar to the internal functions.
///
/// **Examples**
///
/// Define a validator for a queryParameter, including documentation and errorResponses
/// in a single command:
///
/// ```js
/// controller.extend({
/// myParam: function (maxValue) {
/// this.queryParam("value", {type: joi.number().required()});
/// this.onlyIf(function(req) {
/// var v = req.param("value");
/// if (v > maxValue) {
/// throw new NumberTooLargeError();
/// }
/// });
/// this.errorResponse(NumberTooLargeError, 400, "The given value is too large");
/// }
/// });
///
/// controller.get("/goose/barn", function(req, res) {
/// // Will only be invoked if the request has parameter value and it is less or equal 5.
/// }).myParam(5);
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
extend(extensions) {
var attr;
var extensionWrapper = function(scope, functionName) {

207
js/server/modules/org/arangodb/foxx/request_context.js
View File

@ -146,8 +146,15 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_pathParam
///
/// If you defined a route "/foxx/:id", you can constrain which format a path
/// parameter (*/foxx/12*) can have by giving it a *joi* type.
/// `Route.pathParam(id, options)`
///
/// If you defined a route "/foxx/:name", containing a parameter called `name` you can
/// constrain which format this parameter is allowed to have.
/// This format is defined using *joi* in the `options` parameter.
/// Using this function will at first allow you to access this parameter in your
/// route handler using `req.params(id)`, will reject any request having a paramter
/// that does not match the *joi* definition and creates a documentation for this
/// parameter in ArangoDBs WebInterface.
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
@ -162,20 +169,20 @@ class RequestContext {
/// *Examples*
///
/// ```js
/// app.get("/foxx/:id", function {
/// app.get("/foxx/:name", function {
/// // Do something
/// }).pathParam("id", joi.number().integer().required().description("Id of the Foxx"));
/// }).pathParam("name", joi.number().integer().required().description("Name of the Foxx"));
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.get("/foxx/:id", function {
/// app.get("/foxx/:name", function {
/// // Do something
/// }).pathParam("id", {
/// }).pathParam("name", {
/// type: joi.number().integer(),
/// required: true,
/// description: "Id of the Foxx"
/// description: "Name of the Foxx"
/// });
/// ```
/// @endDocuBlock
@ -243,12 +250,16 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_queryParam
///
/// `FoxxController#queryParam(id, options)`
/// `Route.queryParam(id, options)`
///
/// Describe a query parameter:
///
/// If you defined a route "/foxx", you can constrain which format a query
/// parameter (*/foxx?a=12*) can have by giving it a *joi* type.
/// If you defined a route "/foxx", you can allow a query paramter with the
/// name `id` on it and constrain the format of this parameter by giving it a *joi* type in the `options` parameter.
/// Using this function will at first allow you to access this parameter in your
/// route handler using `req.params(id)`, will reject any request having a paramter
/// that does not match the *joi* definition and creates a documentation for this
/// parameter in ArangoDBs WebInterface.
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
@ -360,29 +371,29 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_bodyParam
///
/// `FoxxController#bodyParam(paramName, options)`
/// `Route.bodyParam(paramName, options)`
///
/// Expect the body of the request to be a JSON with the attributes you annotated
/// in your model. It will appear alongside the provided description in your
/// Documentation.
/// This will initialize a *Model* with the data and provide it to you via the
/// params as *paramName*.
/// Defines that this route expects a JSON body when requested and binds it to
/// a pseudo parameter with the name `paramName`.
/// The body can than be read in the the handler using `req.params(paramName)` on the request object.
/// In the `options` parameter you can define how a valid request body should look like.
/// This definition can be done in two ways, either using *joi* directly.
/// Accessing the body in this case will give you a JSON object.
/// The other way is to use a Foxx *Model*.
/// Accessing the body in this case will give you an instance of this Model.
/// For both ways an entry for the body will be added in the Documentation in ArangoDBs WebInterface.
/// For information about how to annotate your models, see the Model section.
/// If you provide the Model in an array, the response will take multiple models
/// instead of one.
/// All requests sending a body that does not match the validation given this way
/// will automatically be rejected.
///
/// If you wrap the provided model in an array, the body param is always an array
/// and accordingly the return value of the *params* for the body call will also
/// return an array of models.
/// You can also wrap the definition into an array, in this case this route
/// expects a body of type array containing arbitrary many valid objects.
/// Accessing the body parameter will then of course return an array of objects.
///
/// Alternatively you can provide a joi schema instead of a model to allow
/// arbitrary data. When using a joi schema or a model that has a joi schema,
/// well-formed request bodies will be rejected if they don't pass schema validation.
///
/// The behavior of *bodyParam* changes depending on the *rootElement* option
/// set in the [manifest](../Develop/Manifest.md). If it is set to true, it is
/// Note: The behavior of `bodyParam` changes depending on the `rootElement` option
/// set in the [manifest](../Develop/Manifest.md). If it is set to `true`, it is
/// expected that the body is an
/// object with a key of the same name as the *paramName* argument.
/// object with a key of the same name as the `paramName` argument.
/// The value of this object is either a single object or in the case of a multi
/// element an array of objects.
///
@ -506,10 +517,37 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_summary
///
/// `FoxxController#summary(description)`
/// `Route.summary(description)`
///
/// Set the summary for this route in the documentation.
/// Can't be longer than 8192 characters
/// Can't be longer than 8192 characters.
/// This is equal to using JavaDoc style comments right above your function.
/// If you provide both comment and `summary()` the call to `summary()` wins
/// and will be used.
///
/// *Examples*
///
/// Version with comment:
///
/// ```js
/// /** Short description
/// *
/// * Longer description
/// * with multiple lines
/// */
/// app.get("/foxx", function() {
/// });
/// ```
///
/// is identical to:
///
/// ```js
/// app.get("/foxx", function() {
/// })
/// .summary("Short description")
/// .notes(["Longer description", "with multiple lines"]);
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@ -524,9 +562,33 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_notes
///
/// `FoxxController#notes(...description)`
/// `Route.notes(...description)`
///
/// Set the long description for this route in the documentation
//
/// *Examples*
///
/// Version with comment:
///
/// ```js
/// /** Short description
/// *
/// * Longer description
/// * with multiple lines
/// */
/// app.get("/foxx", function() {
/// });
/// ```
///
/// is identical to:
///
/// ```js
/// app.get("/foxx", function() {
/// })
/// .summary("Short description")
/// .notes(["Longer description", "with multiple lines"]);
/// ```
///
/// Set the notes for this route in the documentation
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@ -539,15 +601,16 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_errorResponse
///
/// `FoxxController#errorResponse(errorClassOrName, code, description)`
/// `Route.errorResponse(errorClassOrName, code, description, [callback])`
///
/// Define a reaction to a thrown error for this route: If your handler throws an error
/// of the errorClass or with the name, it will be caught and the response will have the given
/// of the errorClass defined in `errorClassOrName` or the error has an attribute `name` equal to `errorClassOrName`,
/// it will be caught and the response object will be filled with the given
/// status code and a JSON with error set to your description as the body.
///
/// If you want more control over the returned JSON, you can give an optional fourth
/// parameter in form of a function. It gets the error as an argument, the return
/// value will transformed into JSON and then be used as the body.
/// value will be transformed into JSON and then be used as the body.
/// The status code will be used as described above. The description will be used for
/// the documentation.
///
@ -593,11 +656,14 @@ class RequestContext {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_onlyIf
///
/// `FoxxController#onlyIf(check)`
/// `Route.onlyIf(check)`
///
/// Provide it with a function that throws an exception if the normal processing should
/// not be executed. Provide an `errorResponse` to define the behavior in this case.
/// This can be used for authentication or authorization for example.
/// This functionality is used to secure a route by applying a checking function
/// on the request beforehand, for example the check authorization.
/// It expects `check` to be a function that takes the request object as first parameter.
/// This function is executed before the actual handler is invoked.
/// If `check` throws an error the actual handler will not be invoked.
/// Remember to provide an `errorResponse` on the route as well to define the behavior in this case.
///
/// *Examples*
///
@ -680,40 +746,31 @@ _.each([
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_pathParam
///
/// If you defined a route "/foxx/:id", you can constrain which format a path
/// parameter (*/foxx/12*) can have by giving it a *joi* type.
/// `Controller.allRoutes.pathParam(id, options)`
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
/// *Parameter*
///
/// * *id*: name of the param.
/// * *options*: a joi schema or an object with the following properties:
/// * *type*: a joi schema.
/// * *description*: documentation description for the parameter.
/// * *required* (optional): whether the parameter is required. Default: determined by *type*.
/// This is equal to invoking `Route.pathParam` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allroutes.pathParam("id", joi.number().integer().required().description("Id of the Foxx"));
/// app.allRoutes.pathParam("id", joi.number().integer().required().description("Id of the Foxx"));
///
/// app.get("/foxx/:id", function {
/// // Do something
/// // Secured by pathParam
/// });
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.allroutes.pathParam("id", {
/// app.allRoutes.pathParam("id", {
/// type: joi.number().integer(),
/// required: true,
/// description: "Id of the Foxx"
/// });
///
/// app.get("/foxx/:id", function {
/// // Do something
/// // Secured by pathParam
/// });
/// ```
/// @endDocuBlock
@ -722,26 +779,9 @@ _.each([
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_queryParam
///
/// `FoxxController#queryParam(id, options)`
/// `Controller.allRoutes.queryParam(id, options)`
///
/// Describe a query parameter:
///
/// If you defined a route "/foxx", you can constrain which format a query
/// parameter (*/foxx?a=12*) can have by giving it a *joi* type.
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
/// You can also provide a description of this parameter and
/// whether you can provide the parameter multiple times.
///
/// *Parameter*
///
/// * *id*: name of the parameter
/// * *options*: a joi schema or an object with the following properties:
/// * *type*: a joi schema
/// * *description*: documentation description for this param.
/// * *required* (optional): whether the param is required. Default: determined by *type*.
/// * *allowMultiple* (optional): whether the param can be specified more than once. Default: `false`.
/// This is equal to invoking `Route.queryParam` on all routes bound to this controller.
///
/// *Examples*
///
@ -777,15 +817,14 @@ _.each([
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_errorResponse
///
/// `RequestContextBuffer#errorResponse(errorClass, code, description)`
/// `Controller.allRoutes.errorResponse(errorClass, code, description)`
///
/// Defines an *errorResponse* for all routes of this controller. For details on
/// *errorResponse* see the according method on routes.
/// This is equal to invoking `Route.errorResponse` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allroutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
/// app.allRoutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
///
/// app.get("/foxx", function {
/// // Do something
@ -798,15 +837,14 @@ _.each([
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIf
///
/// `RequestContextBuffer#onlyIf(code, reason)`
/// `Controller.allRoutes.onlyIf(code, reason)`
///
/// Defines an *onlyIf* for all routes of this controller. For details on
/// *onlyIf* see the according method on routes.
/// This is equal to invoking `Route.onlyIf` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allroutes.onlyIf(myPersonalCheck);
/// app.allRoutes.onlyIf(myPersonalCheck);
///
/// app.get("/foxx", function {
/// // Do something
@ -819,15 +857,14 @@ _.each([
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIfAuthenticated
///
/// `RequestContextBuffer#onlyIfAuthenticated(code, description)`
/// `Controller.allRoutes.onlyIfAuthenticated(code, description)`
///
/// Defines an *onlyIfAuthenticated* for all routes of this controller. For details on
/// *onlyIfAuthenticated* see the according method on routes.
/// This is equal to invoking `Route.onlyIfAuthenticated` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allroutes.onlyIfAuthenticated(401, "You need to be authenticated");
/// app.allRoutes.onlyIfAuthenticated(401, "You need to be authenticated");
///
/// app.get("/foxx", function {
/// // Do something

8
js/server/modules/org/arangodb/foxx/template_middleware.js
View File

@ -31,7 +31,7 @@ var db = require("org/arangodb").db,
_ = require("underscore");
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_TemplateMiddleware_initializer
/// @start Docu Block JSF_foxx_TemplateMiddleware_initializer
///
/// Initialize with the name of a collection or a collection and optionally
/// a set of helper functions.
@ -48,7 +48,7 @@ var db = require("org/arangodb").db,
///
/// app.before(templateMiddleware);
/// ```
/// @endDocuBlock
/// @end Docu Block
////////////////////////////////////////////////////////////////////////////////
function TemplateMiddleware(templateCollection, helper) {
@ -59,7 +59,7 @@ function TemplateMiddleware(templateCollection, helper) {
responseFunctions = {
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_TemplateMiddleware_response_render
/// @start Docu Block JSF_foxx_TemplateMiddleware_response_render
///
/// `response.render(templatePath, data)`
///
@ -74,7 +74,7 @@ function TemplateMiddleware(templateCollection, helper) {
/// ```js
/// response.render("high/way", {username: 'Application'})
/// ```
/// @endDocuBlock
/// @end Docu Block
////////////////////////////////////////////////////////////////////////////////
render: function (templatePath, data) {