////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== formatDate



=== Purpose


Formats `java.util.Date`, `java.time.LocalDate`, and `java.time.LocalDateTime` instances using the patterns defined by the {javase}java.base/java/text/SimpleDateFormat.html[SimpleDateFormat] class.


=== Examples


[source,xml]
----
<g:formatDate format="yyyy-MM-dd" date="${date}"/>
----

[source,xml]
----
<g:formatDate date="${date}" type="datetime" style="MEDIUM"/>
----

[source,xml]
----
<g:formatDate date="${date}" type="datetime" style="LONG" timeStyle="SHORT"/>
----

[source,xml]
----
<g:formatDate date="${date}" type="time" style="SHORT"/>
----


=== Description


Attributes

WARNING: In Java 20+, https://cldr.unicode.org/downloads/cldr-42[Unicode CLDR42] was implemented which changed the space character preceding the period (AM or PM) in formatted date/time text from a standard space (" ") to a narrow non-breaking space (NNBSP: "\u202F").  Additionally, when using the LONG or FULL timeStyle with dateStyle, the date and time separator has changed from ' at ' to ', '.  IE. January 5, 1941, 8:00:00 AM UTC vs. January 5, 1941 at 8:00:00 AM UTC

* `date` (required) - The date object to format. It could be the instance of `java.util.Date`, `java.time.LocalDate`, `java.time.LocalDateTime`.
* `format` (optional) - The formatting pattern to use for the date, see {javase}java.base/java/text/SimpleDateFormat.html[SimpleDateFormat]
* `formatName` (optional) - Look up `format` from the default MessageSource / ResourceBundle (i18n/*.properties file) with this key. If `format` and `formatName` are empty, `format` is looked up with '`default.date.format`' key. Defaults to 'yyyy-MM-dd HH:mm:ss z' if the key not specified
* `type` (optional) - The type of format to use for the date / time. `format` or `formatName` aren't used when `type` is specified. Possible values: 'date' - shows only date part, 'time' - shows only time part, 'both'/'datetime' - shows date and time
* `timeZone` (optional) - Sets the time zone for formatting. See {javase}java.base/java/util/TimeZone.html[TimeZone] class.
* `locale` (optional) - Force the locale for formatting.
* `style` (optional) - Use default date/time formatting of the country specified by the locale. Possible values: SHORT (default), MEDIUM, LONG, FULL . See {javase}java.base/java/text/DateFormat.html[DateFormat] for explanation.
* `dateStyle` (optional) - Set separate `style` for the date part.
* `timeStyle` (optional) - Set separate `style` for the time part.

WARNING: While using `java.time.LocalDate` as the date value please specify the format attribute as the default (yyyy-MM-dd HH:mm:ss z) would fail to format because `java.time.LocalDate` does not have any time format.
