Marten Calendar

Marten Calendar is a Marten extension that provides the foundation for calendar- and scheduling-related features such as navigation between months, localized rendering, and (soon) event decoration. It is designed to get a production-ready month calendar on the screen quickly while still giving you hooks to extend templates or replace rendering logic entirely.

Note: This shard is currently being bootstrapped. Documentation, features, and usage examples will continue to evolve as the implementation is built out.

Checklist

• Current calendar rendering functionality
• Localized labels and weekday/month translations
• Month calendar event support
• Ready to use CSS Styling

Installation

Add the following dependency to your project's shard.yml:

dependencies:
  marten_calendar:
    github: treagod/marten-calendar

Then run shards install.

Require the shard from your project's src/project.cr file:

require "marten_calendar"

Finally register the application in your Marten configuration:

config.installed_apps = [
  # …
  MartenCalendar::App
]

Usage

Template tag

This shard registers a calendar template tag. It renders a month grid that handles navigation helpers, optional min/max date constraints, and localized parsing for strings. By default the tag renders the templates that ship in MartenCalendar::App, but you can point it to custom templates via settings:

Marten.settings.calendar.template_path = "calendar/month_calendar.html"
Marten.settings.calendar.cell_template_path = "calendar/month_calendar_cell.html"

In a template you can invoke it as follows:

{% calendar %}

Supported kwargs include:

Internationalization

Marten Calendar integrates with Marten’s I18n system out of the box. Month names, weekday headings, and navigation labels are rendered using the currently active locale, so the same templates work across multiple languages without additional logic in your handlers.

The shard ships with src/marten_calendar/locales/en.yml, which defines keys under marten_calendar.calendar.* (month names, weekday headers, navigation labels). Override or extend these translations from your own application by adding matching keys to your app’s locale YAML files, for example:

en:
  marten_calendar:
    calendar:
      label: "Calendar"
      prev_label: "«"
      next_label: "»"
      month_names:
        january: "January"
        february: "February"
         # ...
      weekday_names:
        monday: "Mon"
        tuesday: "Tue"
        # ...

This allows you to keep your calendar UI fully translated alongside the rest of your Marten application while still using the generic calendar template tag shown above.

Rendering from a handler

The shard is focused on the template tag only. If you want to preview the calendar while developing or use it inside a page, wire a handler in your project and feed the context the tag expects. The quick-start below renders the calendar inside /calendar/:

class CalendarPage < Marten::Handlers::Template
  template_name "calendar/page.html"
end

Add the route in config/routes.cr:

routes.draw do
  get "/calendar/", CalendarPage
end

Create templates/calendar/page.html:

{% extends "base.html" %}
{% block content %}
  <h1>Team calendar</h1>
  {% calendar %}
{% endblock %}

Once this is wired up, restart your Marten server and load /calendar/ to verify the tag renders.

Development

shards install
crystal spec

CI also runs bin/qa before every release. Please run both commands locally and open a PR with a short description of the change plus any screenshots of new UI states. If you plan to add a new feature, propose it in Discussions or open an issue so we can align on API design first.