Last updated by fletcherr 5 years ago

Joda-Time Plugin

The Joda-Time plugin makes it simple to use classes from the Joda-Time library in Grails applications. The plugin includes the core Joda-Time library and its Hibernate extensions. With the plugin installed Grails' scaffolding should work out of the box with domain classes that have Joda-Time fields (e.g. DateTime, LocalDate). The plugin's data binding support and taglibs make it easy to bind HTML form inputs to Joda-Time fields on Grails domain classes or command objects.

What 'Just Works' Already

Persistence

It's already possible without the Joda-Time plugin to persist domain object that have fields of types like DateTime, LocalDate, Duration, etc. Simply use the Hibernate UserType implementations supplied by the Joda-Time Hibernate Support library. For example:
import org.joda.time.*
import org.joda.time.contrib.hibernate.*

class Person { String name LocalDate birthdate static mapping = { birthdate type: PersistentLocalDate } }

This even works with some of the special functionality in Grails. For example fields 'dateCreated' and 'lastUpdated' in a Grails domain object will be updated automatically by the framework. Such properties do not have to be java.util.Dates, the functionality works fine if they are org.joda.time.DateTime, for example.

Multi-column UserTypes

To use multi-column types such as PersistentDateTimeTZ you need to include explicit mapping of both column names. For example:
import org.joda.time.*
import org.joda.time.contrib.hibernate.*

class User { DateTime registered static mapping = { registered type: PersistentDateTimeTZ, { column name: "registered_timestamp" column name: "registered_zone" } } }

You can use any name you like for the columns.

What The Plugin Adds

Data Binding

The Joda-Time plugin adds automatic binding support for the types LocalTime, LocalDate, LocalDateTime and DateTime. Text fields are bound on a locale-specific basis and the plugin also adds 'picker' controls (see below).

Tag Libs

The plugin makes several new tags available:

joda:datePicker, joda:timePicker and joda:dateTimePicker

These tags are based on the default g:datePicker tag and exhibit very similar functionality. However, they are designed to be used with Joda-Time typed properties. All the attributes are as-per g:datePicker except that 'value' and 'default' will expect either a ReadablePartial or ReadableInstant instance or a String in ISO8601 date/time format (such a String can be a partial representation depending on the particular tag and the precision attribute). The other difference from g:datePicker is that the 'second' precision is supported (although like g:datePicker the tags use 'minute' as the default precision).

joda:format

This tag formats a ReadableInstant or ReadablePartial instance for the page. Attributes are:
NameDescriptionOptionalDefault
valueAn instance of RedablePartial or ReadableInstantYnew DateTime()
localeThe Locale to use for formattingYrequest locale
zoneThe DateTimeZone to use for formattingYDateTimeZone.getDefault()
chronologyThe Chronology to use for formattingYISOChronology
patternThe pattern to use to render the date. This attribute cannot be used in conjunction with 'style'. See DateTimeFormat for more informationYnone
styleThe style to use to render the date. Composed of two characters S, M, L or - the first representing the date portion and the last the time portion. Using - means that portion is not output. This attribute cannot be used in conjunction with 'pattern'.Y"MM" for date/time values, "M-" for date values or "-M" for time values

Scaffolding

With the Joda-Time plugin installed Grails' dynamic scaffolding will be compatible with domain classes with LocalTime, LocalDate, LocalDateTime or DateTime properties. Create and edit views use the joda:dateTimePicker, joda:datePicker or joda:timePicker (see above) as appropriate. In addition, columns for supported Joda-Time properties on the list view are sortable.

When installing the plugin you should get a warning that the plugin wants to install some scaffolding templates. Be aware that these could overwrite any custom templates you already have in place. The plugin gives you the option to not install the templates but the enhanced scaffolding will not work without them.

Dynamic Methods

The plugin adds the following dynamic methods:

format(pattern)

Returns a String representation of the object according to the specified pattern. See DateTimeFormat for description of patterns. This method is available on ReadableInstant, ReadablePartial (and all sub-types).

Release Notes

0.4.1

  • Fixes template installation on Windows machines where Ant's patch task does not work.

0.4

  • Fixes corrupted template files from previous version.
  • Fixes template compatibility with Grails 1.0.4.

0.3

  • Adds the dynamic format(String) method on ReadableInstant and ReadablePartial.
  • Fixes installation script for Grails 1.0.4.
  • Plugin requires Grails 1.0.4 + as earlier versions don't support registering custom editors.

0.2

  • Fixes bug where registration of structured date/time editor overrides registration of text -> date/time editor.

0.1

  • Initial release

Contact

Questions, comments, bug reports, suggestions? rob@energizedwork.com.