Template Engine

The template engine used in Grasshopper allows embedding any piece of Javascript code within your template files. The syntax for template files have just two simple rules to follow.

1. Text inside <% and %> are evaluated as Javascript code.
2. Text inside <%= and %> are evaluated as Javascript code and its result is included into the output after escaping HTML.
3. Text inside <%h and %> are evaluated as Javascript code and its result is included into the output without any modification.
4. The code fragments above can be terminated with -%> instead of %> if the immediately following newline must be ignored. This can be handy when iterating over an array and displaying the elements inside a <pre> or <textarea>. You can avoid unnecessary blank lines without making your original template ugly. It also keeps the generated HTML beautiful when viewing the source in browser.

View Model

The view model is the model field of the RequestContext (this context of controller functions). Any values you add to this model are available for use within the view templates directly. With the below code in your controller.

this.model['name'] = 'Chandru';
this.render('someView');

You can use the below content in someView.html to generate "Hi, Chandru!".

Hi, <%= name %>!

View Helpers

View helpers are objects with functions to help in the generation of the views' output. Grasshopper comes with a set of its own helpers and also allows you to add custom helpers for views within your application. Remember to use <%h %> with helpers instead of <%= %> as most of them generate HTML.

Built-In Helpers

Grasshopper provides these helpers by default for use in your applications.

error(model, property[, locale])

Retrieves the first error message for the specified property of the model. The error message is localized using the specified locale if locale is provided.

errors(model[, property][, locale])

Retrieves all the error messages for the specified property of the model or all properties of the model if property is not specified. The error messages are localized using the specified locale if locale is provided.

postLink(attribs)

Creates a link which uses POST instead of GET for its request. Useful when creating a delete link.

Note: Requires Javascript to work.

booleanCheckbox(attribs)

This is used to work around the fact that browsers don't send any parameter in the request for a single checkbox which is not checked. This makes using checkboxes to accept boolean input simple. It accepts a boolean state attribute to specify the default state of the checkbox.

collectionSelect(attribs)

Creates a select box with items from an array. It uses the following attributes to create the select box.

• items - An array of items in the select.
• valueProp - An optional string specifying the property of the objects in the array to be used for 'value' attribute of 'option' element.
• labelProp - An optional string specifying the property of the objects in the array to be used for the body of 'option' element.
• prompt - And optional string when specified, will be used as the label for an item with empty value inserted at the beginning of the list.
• value - An object (or array for multi-select lists) giving the values selected by default.

escapeHTML(text)

Escapes HTML special characters from the given text.

Adding Custom Helpers

Adding custom helpers to your application is as simple as creating an object with the required helper functions and adding it using gh.addHelpers(helperObj). The functions in this object can then be accessed within your views.