1. Plugins
  2. Spincast Date Formatter plugin

Spincast Date Formatter plugin

Spincast Date Formatter plugin

Overview

This plugin allows you to format dates in many ways, using any Locale and any TimeZone. The fonctionnalities are available both in Java code and in templates (using the provided Pebble extension).

There are two kind of formats that can be used :

  • Literal - such as "Monday, December 3, 2007 - 10:15 AM" or "12/3/07".
  • Relative - such as "10 years ago" or "10 years from now".

The PrettyTime library is used for the relative formatting.

Usage

In Java code, you inject the DateFormatterFactory and use its createFormatter() or createRelativeFormatter() function to start creating a date formatter. The first parameter is the Date or the Instant to be formatted. For example: 

@Injected
private DateFormatterFactory dateFormatterFactory;

// ...

Instant now = Instant.now(); // or a Date

// For a "literal" formatter
DateFormatter formatter = getDateFormatterFactory().createFormatter(now);

// Or, for a "relative" formatter
RelativeDateFormatter formatter = getDateFormatterFactory().createRelativeFormatter(now);

You can then configure the options of the formatter, and finally call .format() to get the resulting formatted date: 

Date now = new Date(); // or an Instant

// A "literal" formatter
DateFormatter formatter = getDateFormatterFactory().createFormatter(now);
String dateFormatted = formatter.parts(DateParts.BOTH)
                                .datePattern("YYYY")
                                .timePattern(DatePattern.SHORT)
                                .separator(",")
                                .format();
                                
// A "relative" formatter
RelativeDateFormatter formatter = getDateFormatterFactory().createRelativeFormatter(now);
String dateFormatted = formatter.formatType(RelativeDateFormatType.DURATION)
                                .locale(Locale.JAPANESE)
                                .format();

Literal formatter options

The options to create a literal formatter (DateFormatter) are:

  • parts() - to indicate if you want the date part, the time part or both parts in the resulting formatted date. Possibles values are :

    • DateParts.DATE ("Monday, December 3, 2007")
    • DateParts.TIME ("10:15 AM")
    • DateParts.BOTH ("Monday, December 3, 2007 - 10:15 AM")

  • datePattern() and timePattern() - to indicate the standard Java provided formats or a custom pattern to use, for each part to format.

    • DatePattern.ISO (Date: "2017-12-03", Time: "10:15:46")
    • DatePattern.SHORT (Date: "12/3/07", Time: "10:15 AM")
    • DatePattern.MEDIUM (Date: "Dec 3, 2007", Time: "10:15:30 AM")
    • DatePattern.LONG (Date: "December 3, 2007", Time: "10:15:30 AM UTC")
    • DatePattern.FULL (Date: "Monday, December 3, 2007", Time: "10:15:30 AM UTC")
    • Custom pattern, as a String (Example for Date : "YYYY" will result in "2007").

    The default pattern is "DatePattern.ISO".

  • separator() - the separator string to use between the date and time parts, when both are returned.

    The default separator is " - ".

  • locale() - the Locale to use for the formatting.

    If not specified, the Locale returned by the LocaleResolver will be used.

  • timezone() - the TimeZone to use for the formatting.

    If not specified, the TimeZone returned by the TimeZoneResolver will be used.

Relative formatter options

The options to create a RelativeDateFormatter formatter are:

  • formatType() - the type of format to use, as supported by the PrettyTime library. Possibles values are :

    • RelativeDateFormatType.DEFAULT ("10 years ago")
      Standard PrettyTime formatting.
    • RelativeDateFormatType.DURATION ("10 years")

      From PrettyTime's Javadoc: "Format the given Date and return a non-relative (not decorated with past or future tense) String for the approximate duration of its difference between the reference Date."

    • RelativeDateFormatType.UNROUNDED ("9 years ago")

      From PrettyTime's Javadoc: "Format the given Date object. Rounding rules are ignored."

  • locale() - the Locale to use for the formatting.

    If not specified, the Locale returned by the LocaleResolver will be used.

Pebble extension

The plugin provides an extension for Pebble, the default Templating Engine. The interface of this extension is SpincastDateFormatterPebbleExtension and the default implementation is SpincastDateFormatterPebbleExtensionDefault.

The main filter provided by this extension, "dateFormat()", takes an Instant, a Date or an ISO-8601 string representation of a date, and formats it.

For example: 


<div class="date">{{someDate | dateFormat() }}</div>

Options for dateFormat()

relative formatting

If the first parameter of dateFormat() is "relative", the date will be formatted using the relative formatter. For example: 


<div class="date">{{someDate | dateFormat('relative') }}</div>

When the relative formatter is used, the second parameter can be "default", "duration" or "unrounded". Those values correspond to the formatType options, as listed in the Relative formatter options section.

Examples: 

// "10 years ago"
<div class="date">{{someDate | dateFormat('relative') }}</div>

// "10 years"
<div class="date">{{someDate | dateFormat('relative', 'duration') }}</div>

// "9 years ago"
<div class="date">{{someDate | dateFormat('relative', 'unrounded') }}</div>

literal formatting

If the first parameter of dateFormat() is not "relative", the date will be formatted using the literal formatter. For example: 


<div class="date">{{someDate | dateFormat('short', 'full', ',') }}</div>

When the literal formatter is used, the parameters are:

  1. The "datePattern" :
    - Can be a standard format : "iso", "short", "medium", "long" or "full".
    - If it is an underscore "_", the default pattern will be used.
    - If it is empty "", the date part won't be returned.
    - For any other value, the parameter will be considered as a custom pattern for the date part.
  2. The "timePattern" :
    - Can be a standard format : "iso", "short", "medium", "long" or "full".
    - If it is an underscore "_", the default pattern will be used.
    - If it is empty "", the time part won't be returned.
    - For any other value, the parameter will be considered as a custom pattern for the time part.
  3. The "separator" to use between the date part and the time part, if both are returned.

Examples: 

// "12/3/07 , 10:15:30 AM UTC"
<div class="date">{{someDate | dateFormat('short', 'full', ' , ') }}</div>

// "2007-12-03 - 10:15:30 AM UTC"
<div class="date">{{someDate | dateFormat('_', 'full') }}</div>

// "2007-12-03 ~ 10:15:30"
<div class="date">{{someDate | dateFormat('_', '_', ' ~ ') }}</div>

// "10:15:30"
<div class="date">{{someDate | dateFormat('', '_') }}</div>

// "12/3/07"
<div class="date">{{someDate | dateFormat('short', '') }}</div>

// "2007 - 10:15:30"
<div class="date">{{someDate | dateFormat('YYYY', '_') }}</div>

Installation

1. Add this Maven artifact to your project: 

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-date-formatter</artifactId>
    <version>2.2.0</version>
</dependency>

2. Add an instance of the SpincastDateFormatterPlugin plugin to your Spincast Bootstrapper: 


Spincast.configure()
        .plugin(new SpincastDateFormatterPlugin())
        // ...

Plugin class

The class implementing the SpincastPlugin interface is SpincastDateFormatterPlugin.

Javadoc