The Chicago Boss API is mostly stable, but still might change before 1.0.
Jump to: Routes Authorization Return values Post-processing SimpleBridge request object
Chicago Boss associates each URL with a function of a controller.
The URL foo_controller:bar.
Each controller module should go into your project's src/controller/ directory and the file name should start with the application name and end with "_controller.erl", e.g. "appname_my_controller.erl".
Helper functions should go into your project's src/lib/ directory.
Controllers can take one parameter or two parameters: the SimpleBridge request object, and an optional session ID (if sessions are enabled). Declare it like:
Or:
Each exported controller function takes two or three arguments:
'GET' or 'POST'before_ in the controllerExample function clauses:
These function clauses act as templates for constructing URLs in the view; for each CamelCase variable, simply use the lower-cased underscored equivalent as the parameter name. To continue the example above, you can construct URLs to match the above controllers with the following view tags:
Template variables can of course be used in place of string literals.
Most routing takes place in the controller pattern-matching code. You can define additional routes in priv/my_application.routes. The file contains a list of erlang terms, one per line finished with a dot. Each term is a tuple with a URL or an HTTP status code as the first term, and a {Controller::string(), Action::string()} or {Controller::string(), Action::string(), Parameters::proplist()} tuple as the second term.
A few examples:
Most routes directly render the specified action; however, routing across applications (as in the second example) results in a 302 redirect.
To define a default action for a controller, simply add a default_action attribute to the controller like so:
If an action takes three arguments, then the function before_/1 in your controller will be passed the action name as a string and should return one of:
ExtraInfo will be passed as the third argument to the action, and as a variable called "before_" to the templates.
Location = string() | [{Key::atom(), Value::atom()}]
Do not execute the action. Instead, perform a 302 redirect to Location, which can be a string or a proplist that will be converted to a URL using the routes system.
Probably most common before_ looks like:
Which might return a tuple of user credential or else redirect to a login page. This way, if you want to require a login to a set of actions, just give those actions a User argument, and the actions will be login protected and have access to the User variable.
Whether or not it takes a third argument, a controller action should return with one of the following:
The template will be rendered without any variables.
Variables will be passed into the associated Django template.
Variables will be passed into the associated Django template, and Headers are HTTP headers you want to set (e.g., Content-Type).
Location = string() | [{action, Value::string()}, ...]
Perform a 302 HTTP redirect to Location, which may be a URL string or a proplist of parameters that will be converted to a URL using the routes system.
Perform a 302 HTTP redirect to Location and set additional HTTP Headers.
OtherLocation = [{action, Value::string()}, ...]
Execute the controller action specified by OtherLocation, but without performing an HTTP redirect.
OtherLocation = [{action, Value::string()}, ...]
Render the view from OtherLocation, but don't actually execute the associated controller action.
Render the view from OtherLocation using Variables, but don't actually execute the associated controller action.
Skip views altogether and return Output to the client.
Skip views altogether and return Output to the client while setting additional HTTP Headers.
Return Data as a JSON object to the client. Performs appropriate serialization if the values in Data contain a BossRecord or a list of BossRecords.
Return Data to the client as a JSON object while setting additional HTTP Headers.
Returns Data as a JSONP method call to the client. Performs appropriate serialization if the values in Data contain a BossRecord or a list of BossRecords.
Return Data to the client as a JSONP method call (as above) while setting additional HTTP Headers.
Invoke the 404 File Not Found handler.
If it exists, a function called after_ in your controller will be passed the result that is about to be returned to the client. The 'after_' function takes two or three arguments:
The after_ function should return a (possibly) modified HTTP result tuple. Result tuples may be one of:
Performs a 302 HTTP redirect to Location and sets additional HTTP Headers.
Returns a 200 OK response to the client with Payload as the HTTP body, and sets additional HTTP Headers.
Controller functions are passed a SimpleBridge request object (slightly modified for Boss's purposes). Useful functions in the request object include:
Get the request method, e.g. GET, POST, etc.
Get the value of a given query string parameter (e.g. "?id=1234")
Get the value of a given POST parameter
Get the value of a given "deep" POST parameter. This function parses parameters that have numerical or labeled indices, such as "widget[4][name]", and returns either a value or a set of nested lists (for numerical indices) and proplists (for string indices).
Get the value of a given HTTP request header. Valid values are strings or one of these atoms:
acceptaccept_languageaccept_rangesauthorizationconnectioncontent_encodingcontent_lengthcontent_typecookiehostif_matchif_modified_sinceif_none_matchif_unmodified_sincekeep_alivelocationrangereferertransfer_encodinguser_agentx_forwarded_forGet the value of a given cookie.