templates.plugins.spincast-date-formatter.spincast-date-formatter.html Maven / Gradle / Ivy
Show all versions of spincast-website Show documentation
{% extends "../../layout.html" %}
{% block sectionClasses %}plugins hasBreadCrumb plugins-spincast-date-formatter{% endblock %}
{% block meta_title %}Plugins - Spincast Date Formatter{% endblock %}
{% block meta_description %}Spincast Date Formatter plugin for easy date formatting.{% endblock %}
{% block scripts %}
{% endblock %}
{% block body %}
Plugins- 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:
{% verbatim %}
@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);
{% endverbatim %}
You can then configure the options of the formatter, and finally call .format()
to get the resulting formatted date:
{% verbatim %}
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();
{% endverbatim %}
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:
{% verbatim %}
<div class="date">{{someDate | dateFormat() }}</div>
{% endverbatim %}
Options for dateFormat()
relative formatting
If the first parameter of dateFormat() is "relative", the date will be formatted using
the relative formatter. For example:
{% verbatim %}
<div class="date">{{someDate | dateFormat('relative') }}</div>
{% endverbatim %}
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:
{% verbatim %}
// "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>
{% endverbatim %}
literal formatting
If the first parameter of dateFormat() is not "relative", the date will be formatted using
the literal formatter. For example:
{% verbatim %}
<div class="date">{{someDate | dateFormat('short', 'full', ',') }}</div>
{% endverbatim %}
When the literal formatter is used, the parameters are:
-
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.
-
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.
-
The "separator" to use between the date part and
the time part, if both are returned.
Examples:
{% verbatim %}
// "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>
{% endverbatim %}
Installation
1.
Add this Maven artifact to your project:
<dependency>
<groupId>org.spincast</groupId>
<artifactId>spincast-plugins-date-formatter</artifactId>
<version>{{spincast.spincastCurrrentVersion}}</version>
</dependency>
2. Add an instance of the SpincastDateFormatterPlugin
plugin to your Spincast Bootstrapper:
{% verbatim %}
Spincast.configure()
.plugin(new SpincastDateFormatterPlugin())
// ...
{% endverbatim %}
Plugin class
The class implementing the SpincastPlugin
interface is SpincastDateFormatterPlugin.
Javadoc
-
Date Formatter Plugin javadoc
{% endblock %}
Spincast Date Formatter 
Spincast Date Formatter