Horn

  • Tags : /
  • Latest : 1.0.57
  • Last Updated: 04 May 2012
  • Grails version : 1.3.1 > *
  • Authors : Chris Denman
0 vote
Dependency :
compile ":horn-jquery:1.0.57"
Custom repositories :
mavenRepo "http://grails.org/plugins"

Documentation

Summary

Provides JS libraries and tags for embedding data in your HTML content using the HORN specification

Description

Provides JS libraries and tags for embedding data in your HTML content using the HORN specification.

This enables you to render your data model as HTML for presentation to the user in the normal way, and have HORN pull this data out into a JS model for your client code to use. It You then alter the model from your JS and can reflect these changes back into the HTML.

For details of the HORN specification see the docs. However understanding of HORN is not required for usage of this plugin.

Usage

Install the plugin and then amend your GSPs to include the required resources and use Horn tags.

The premise is simple:

  • Horn tags with path attribute on specify a new relative or absolute model property path for their child nodes
  • If the Horn tag has just text child nodes, these will be extracted and used as the value for the model variable at the path specified on the Horn tag.
Thus tags with path are either defining a new value (text only child nodes) or defining a new path context for any values set in nested Horn tags.

<body>
    <h1>Welcome <horn:span path="user.name">${user}</horn:span></h1>
    <p>You have <horn:span path="inbox.unread">${inbox.unreadCount}</horn:span> messages</p>

<horn:div path="inbox.unreadMessages"> <g:each in="${inbox.unreadMessages}" var="msg"> <horn:div path="bodyText">${msg.text}</horn:div> </g:each> </horn:div> </body>

This will result in the JS model containing:

Including the resource modules

HORN uses the Resources plugin. The Javascript resources required to parse out the HORN data into a model are defined in modules that you must r:require in your GSP or add to your own modules' @dependsOn@.

The modules declared are:

  • horn-html5 - HORN using HTML5 data attributes. This is the recommended module. Use this or horn-css, not both.
  • horn-css - HORN using CSS classes. Only use if you cannot use HTML5 in your apps. Use this or horn-html5, not both.
  • horn-converters - Extra optional code for converting values to and from text and native Javascript types. Include this if you want the default date conversions.

Accessing the model data

To access the model data in your JS code, you just reference the horn.model() function:

<r:script>
window.alert( 'Unread messages count is "+horn.model().inbox.unreadCount);
</r:script>

Tags

All the horn tags follow the same pattern, providing common HTML tag equivalents that take the attributes necessary for HORN data.

The tags are in the "horn" namespace and support the following attributes:

NameUsage
pathThe HORN property path of the value being written. Use dot separator syntax as you would expect when accessing a model property i.e. "book.authors0.title". If you are in a nested path context and need to set a value at a higher level in the model, prefix the path with "/" i.e. "/totalBooks"
jsonOptional - boolean indicating whether or not to write out the value as hidden JSON block that HORN will merge using the current path context
templateOptional -
emptyBodyClassOptional - a CSS class to apply to the element if there is no value in the body of the tag and no non-text children. Defaults to "hidden". Use this so that entire tags can be hidden from the view if there is no value, and removed when a value is set in the model and synced back to the view.

Supported HTML tags

There is built in support for most HTML5 tags. These are called using some attributes from the previous section, and their content is used as the value for the model variable denoted by the path attribute specified.

  • horn:a
  • horn:abbr
  • horn:b
  • horn:br
  • horn:button
  • horn:caption
  • horn:col
  • horn:colgroup
  • horn:div
  • horn:em
  • horn:fieldset
  • horn:form
  • horn:head
  • horn:html
  • horn:i
  • horn:h1 through to h6
  • horn:input
  • horn:label
  • horn:legend
  • horn:li
  • horn:link
  • horn:object
  • horn:ol
  • horn:optgroup
  • horn:option
  • horn:p
  • horn:pre
  • horn:script
  • horn:select
  • horn:span
  • horn:string
  • horn:style
  • horn:sub
  • horn:sup
  • horn:table
  • horn:tbody
  • horn:textarea
  • horn:tfoot
  • horn:thead
  • horn:td
  • horn:th
  • horn:tr
  • horn:tt
  • horn:ul

Calling Grails tags

Sometimes you will want to use the text content of the output of a Grails tag as values in your model. To do this you use @horn:tag@.

This example creates a link to a product Description that is extracted into the JS data model:

<horn:tag tag="g:link" path="description" action="edit" id="${product.id}">${product.description}</horn:tag>

This simply delegates to g:link passing in all the arguments except from those used by HORN (path, tag, json, emptyBodyClass, template) and amends the attribute list to include the necessary values to hook up the HORN values.

If you need to call a tag that uses any of these "reserved" attribute names, you can use the alternate form where you pass the attributes for the delegate tag in @attrs@:

<horn:tag tag="g:link" path="description" attrs="[action:'edit', id:product.id]">${product.description}</horn:tag>

Configuration

By default the plugin defaults to using HTML5 HORN syntax, where data attributes are used for metadata. If you are not using HTML5 you can turn this off so that it falls back to using CSS classes for data.

In Config.groovy:

horn.no.html5 = true

You can also define the default CSS class used to hide empty or JSON data elements using

In Config.groovy:

horn.hiddenClass = true