Cldr Calendars Format

v0.4.0

Cldr Calendars Format

Cldr Calendar Formatting

ex_cldr_calendars_format provides a framework for formatting calendars for output. It includes example formatters for HTML (Cldr.Calendar.Formatter.HTML.Basic), HTML for week-based calendars (Cldr.Calendar.Formatter.HTML.Week) and Markdown (Cldr.Calendar.Formatter.Markdown).

These examples may be used as-is but supporting the development of formatters that meet specific requirements is a design objective which is implemented via the Cldr.Calendar.Formatter behaviour.

Getting Started

A formatted calendar is generated via Cldr.Calendar.Format.year/2 or Cldr.Calendar.Format.month/3. For example, to generate a simple HTML calendar for April 2019:

iex> Cldr.Calendar.Format.month 2019, 4
"<table class=\"cldr_calendar\">\n  <caption>April 2019</caption\n  <th>\n    <td class=\"day_name, weekday\">Mon</td>\n    <td class=\"day_name, weekday\">Tue</td>\n    <td class=\"day_name, weekday\">Wed</td>\n...."

From this example we can deduce that:

Formatting a week-based calendar

Week-based calendars, like ISO Week and National Retail Federation, don't have months in the traditional sense however they can be formatted in a month-like fashion. The formatter Cldr.Calendar.Formatter.HTML.Week is different from Cldr.Calendar.Formatter.HTML.Basic in that is includes the week number as well as the dates. It also converts each date into the Cldr.Calendar.Gregorian calendar for familiar formatting. For example:

iex> Cldr.Calendar.Format.month 2019, 4, calendar: Cldr.Calendar.NRF, formatter: Cldr.Calendar.Formatter.HTML.Week
"<table class=\"cldr_calendar\">\n  <caption>April 2019</caption\n  <th>\n    <td> </td>\n    <td class=\"day_name, weekend\">Sun</td>\n    <td class=\"day_name, weekday\">Mon</td>\n    <td class=\"day_name, weekday\">Tue</td>\n    <td class=\"day_name, weekday\">Wed</td>\n    <td class=\"day_name, weekday\">Thu</td>\n    <td class=\"day_name, weekday\">Fri</td>\n    <td class=\"day_name, weekend\">Sat</td>\n\n  </th>\n  <tr>\n    <td class=\"week\">W14</td>\n ... "

This example shows that the first day of the week for the Cldr.Calendar.NRF calendar is Sunday and that the week number is included.

Formatting Markdown

The Cldr.Calendar.Formatter.Markdown formatter is a simple formatter. Using the simple example for April 2019 the example shows:

iex> Cldr.Calendar.Format.month 2019, 4, formatter: Cldr.Calendar.Formatter.Markdown
"### April 2019\n\nMon | Tue | Wed | Thu | Fri | Sat | Sun\n :---:  |  :---:  |  :---:  |  :---:  |  :---:  |  :---:  |  :---: \n**1** | **2** | **3** | **4** | **5** | **6** | **7**\n**8** | **9** | **10** | **11** | **12** | **13** | **14**\n**15** | **16** | **17** | **18** | **19** | **20** | **21**\n**22** | **23** | **24** | **25** | **26** | **27** | **28**\n**29** | **30** | 1 | 2 | 3 | 4 | 5\n6 | 7 | 8 | 9 | 10 | 11 | 12\n"

Which renders as (heading omitted):

MonTueWedThuFriSatSun
1234567
891011121314
15161718192021
22232425262728
293012345
6789101112

Calendar localization

Since ex_cldr_calendars_format is built upon ex_cldr, calendars can be localised. Localised formatting understands the weekend and weekdays for a given locale or territory and can use the default of native number system (which may use localised characters for numbers). For example, using the locale for Saudi Arabia we can see:

iex> markdown = Cldr.Calendar.Format.month 2019, 4, formatter: Cldr.Calendar.Formatter.Markdown, locale: "ar-SA"
"### أبريل ٢٠١٩\n\nالاثنين | الثلاثاء | الأربعاء | الخميس | الجمعة | السبت | الأحد\n :---:  |  :---:  |  :---:  |  :---:  |  :---:  |  :---:  |  :---: \n**١** | **٢** | **٣** | **٤** | **٥** | **٦** | **٧**\n**٨** | **٩** | **١٠** | **١١** | **١٢** | **١٣** | **١٤**\n**١٥** | **١٦** | **١٧** | **١٨** | **١٩** | **٢٠** | **٢١**\n**٢٢** | **٢٣** | **٢٤** | **٢٥** | **٢٦** | **٢٧** | **٢٨**\n**٢٩** | **٣٠** | ١ | ٢ | ٣ | ٤ | ٥\n٦ | ٧ | ٨ | ٩ | ١٠ | ١١ | ١٢\n"

Which renders as (heading omitted):

الاثنينالثلاثاءالأربعاءالخميسالجمعةالسبتالأحد
١٢٣٤٥٦٧
٨٩١٠١١١٢١٣١٤
١٥١٦١٧١٨١٩٢٠٢١
٢٢٢٣٢٤٢٥٢٦٢٧٢٨
٢٩٣٠١٢٣٤٥
٦٧٨٩١٠١١١٢

Configuring a Cldr backend for localization

In order to localize date parts abackend module must be defined. This is a module which hosts the CLDR data for a set of locales. The detailed information for configuring a backend is documented here.

For a simple configuration the following steps may be used:

  1. Create a backend module.

Note that the provider Cldr.Number must be configured since it supports localisation of number formatting.

defmodule MyApp.Cldr do
  use Cldr,
    locales: ["en", "fr", "jp", "ar"],
    providers: [Cldr.Number]

end
  1. Optionally configure this backend as the system default in your config.exs. 
config :ex_cldr,
  default_backend: MyApp.Cldr

Installation

This package can be installed by adding ex_cldr_calendars_format to your list of dependencies in mix.exs:

def deps do
  [
    ...
    {:ex_cldr_calendars_format, "~> 0.1.0"}
  ]
end

Documentation can be found at https://hexdocs.pm/ex_cldr_calendars_format.