Customization¶
There are various options which can be passed to customize the HTML output and the behaviour of ajja.
Providing a save url for the server¶
One great feature of ajja is that it automatically pushes changes in your form fields to the server. By default, changes are sent to the same url that form data was loaded from. You can also specify a separate url to save to:
var form = new ajja.Form('form', {save_url: '/save.json'});
The server end point at save_url
is expected to implement
ajja’s communication protocol.
Customizing the form template¶
The default behaviour is to simply append every new field as a child to the form tag. If you need to customize the order of your fields or just need different overall HTML for your form, you can use a custom form template with containers for all or just some of the fields:
ajja.register_template(
'form',
['<form method="POST" action="{{action}}" id="{{form_id}}" class="ajja form-horizontal">',
' <div class="statusarea"></div>',
' <table><tr><td><span id="field-firstname" /></td>',
' <td><span id="field-lastname" /></td></tr></table>',
'</form>'].join('')
);
var form = new ajja.Form('form');
form.load({firstname: 'Max', lastname: 'Mustermann'});
This will replace the span
containers with ids firstname
and
lastname
with the appropriate input
fields.
CSRF token¶
In order to prevent Cross-site request forgery (CSRF),
ajja can handle CSRF tokens and always submit them with every save
request. The token needs to be generated on the server and injected into the
DOM in a hidden input field with the id csrf_token
.
<input type="hidden" id="csrf_token" value="secure-random" />
<div id="form"></div>
The token will be sent with every request under the key csrf_token
.
Customizing field widgets¶
You can either customize widgets by their type (e.g. all fields rendered for strings) or customize single widgets by their name.
Customization by field type¶
You can overwrite the default templates by registering your own templates prior to form initialization:
ajja.register_template('form_boolean', '<bool_template_html />');
ajja.register_template('form_string', '<string_template_html />');
var form = new ajja.Form('form');
For every string value, your input template would be rendered instead of the default input text field. Same for lists and boolean values.
Customization by field name¶
Imagine you want checkboxes instead of a select field. You can use the form_radio_list template for that purpose:
var form = new ajja.Form('form');
form.load({kind: ''},
{kind: {source: [
{token: 'dog', title: 'Dog'},
{token: 'cat', title: 'Cat'},
{token: 'mouse', title: 'Mouse'}],
label: 'What kind of animal do you love?',
template: 'form_radio_list'}});
You can pass the load method a JS object containing customizations for each field. One of these customization options is the name of the registered template, which results in rendering two checkboxes instead of the default select box.
Rendering readonly widgets¶
If you need to make a field widget immutable, you can pass it the disabled flag in the options:
var form = new ajja.Form('form');
form.load({kind: 'Immutable'},
{kind: {label: 'Immutable text',
disabled: true}});
Its possible to render the whole form with immutable fields, too:
var form = new ajja.Form('form', {disabled: true});
form.load({name: 'John Doe', gender: 'male'},
{name: {label: 'Name'},
gender: {label: 'Gender',
'source': [{token: 'unknown', title: 'Not specified'},
{token: 'male', title: 'Male'},
{token: 'female', title: 'Female'}]}});