-
Notifications
You must be signed in to change notification settings - Fork 66
MVC: Controller Helpers
The /src/lib/controller-helper.xqy library is included in controllers built by Roxy.
Specifies a particular view to be used for the given format. The view is expected to be in the views directory. This overrides the default, convention-based view. Consider a user controller with a register function. The client accesses this with the url /user/register, with HTML being the default format. Normally, the function will use the /src/views/user/register.html.xqy view. The ch:use-view() function allows that to be changed. This is handy if you want several endpoints to use the same view.
Note that the return value from this function must be returned in order to take effect.
Example
(: in the user controller function... :)
declare function c:register() as item()*
{
ch:use-view("welcome", ("html")),
lib:something-useful()
};
This says that when a client requests /user/register.html, use the view at /src/views/welcome.html.xqy.
Bad Example
declare function c:register() as item()*
{
(: WILL NOT WORK :)
let $_ := ch:use-view("welcome, ("html"))
return lib:something-useful()
};
Same as ch:use-view($view as xs:string?, $formats as xs:string*), but applies to all formats.
Default layouts are specified in /src/app/config.xqy in $DEFAULT-LAYOUTS. To override those defaults, use this function.
Example
(: in the user controller function... :)
declare function c:register() as item()*
{
ch:use-view("welcome", ("html")),
ch:use-layout("greetings", ("html")),
lib:something-useful()
};
This says that when a client requests /user/register.html, use the layout at /src/views/layouts/greetings.html.xqy.
Works the same as ch:use-layout($layout as xs:string?, $formats as xs:string*), but applies to all formats.
Add a value (or values) to the key. These values will be available to views and layouts through view-helper functions. This function's value does not need to be returned.
Example
(: a user controller function... :)
declare function c:register() as item()*
{
let $_ := ch:add-value("title", "User Registration"),
return lib:something-useful()
};
After this function call, the "title" key will have "User Registration" and any previously added value.
Sets a value that will be available to views and layouts. Similar to ch:add-value(), except that ch:set-value() overwrites an existing value with the same key. This function's value does not need to be returned.
Example
(: a user controller function... :)
declare function c:register() as item()*
{
let $_ := ch:set-value("title", "User Registration"),
return lib:something-useful()
};
After this function call, the "title" key will have "User Registration". Any previously set or added values will be overwritten.
Tells Roxy which format to use when choosing a view. Typical formats are html, xml, json, and text. Note that Roxy uses a convention of specifying the format in the url: http://server:port/controller/view.format. Use ch:set-format() to override the supplied format or the default format that was set in src/app/config/config.xqy.
The second parameter tells Roxy which formats you wish to override. So, if the requested format is html and you want to show json instead then you do the following. Note that if a format other than html is requested then Roxy will honor the requested format.
(: a user controller function... :)
declare function c:register() as item()*
{
(: use json when the user requests html :)
ch:set-format("json", "html"),
lib:something-useful()
};
If you want to override for all formats then use the following function signature.
Like the other ch:set-format except it tells Roxy to use the supplied format in all cases.
(: a user controller function... :)
declare function c:register() as item()*
{
(: use json no matter what :)
ch:set-format("json"),
lib:something-useful()
};