Package org.apache.juneau.console.widgets

Class CalendarDef

java.lang.Object
org.apache.juneau.console.widgets.CalendarDef
All Implemented Interfaces:
Widget
public class CalendarDef extends Object implements Widget
A reusable month-calendar definition: month/year navigation, event categories, and a display-only legend (parent concept #10).

This is the Widget marker type — the juneau-console-widgets org.apache.juneau.console.widgets.Widget, not org.apache.juneau.marshall.html.HtmlWidget (the unrelated $W{...} HTML header-widget SPI). It is bean-only: the emitter (CalendarTable) and the juneau-calendar.js/.css runtime live in juneau-console-views, which composes this bean. Widgets keeps no dependency on views.

The server renders the initial month grid + legend and paints real seed chips into the day cells (progressive enhancement); the runtime then computes each month client-side and hydrates events from a same-origin, data-only per-month GET whose envelope is {contractVersion, year, month, events}. When endpoint is null the calendar is seed-only and month navigation is disabled.

Since:
10.0.0

  • Field Details

    • CONTRACT_VERSION

      public static final String CONTRACT_VERSION
      The frozen contract version for the per-month event GET envelope and the stamped data-juneau-calendar-contract attribute. Serialized as the JSON string "2" (a numeric 2 would fail the client's strict === handshake).

      Bumped from "1" to "2" for the end-becomes-layout-significant change even though the envelope gained no new required field (end was already carried for forward-compat). The bump is justified because this same constant is the stamped data-juneau-calendar-contract attribute: a v1 runtime paired with a v2 server would silently ignore end and paint a multi-day event as a single chip, so making the handshake fail loud is the point. Do not copy this as a general pattern — a wire contract that is not also a runtime-handshake stamp should not bump for a no-new-field change.

      See Also:

    • DEFAULT_MAX_PER_DAY

      public static final int DEFAULT_MAX_PER_DAY
      The default chip cap per day cell before collapsing into "+N more".
      See Also:

    • MAX_LANES_PER_WEEK

      public static final int MAX_LANES_PER_WEEK
      The hard internal ceiling on spanning-bar lanes in one week row.

      The lane budget is derived from effectiveMaxPerDay() and clamped here; it is deliberately not author-controllable (there is no maxLanesPerWeek bean field). Bars that would need a lane beyond the budget are collapsed into the day cells' "+N more" affordance instead of stacking a week row arbitrarily tall.

      See Also:

    • id

      public String id
      Required, non-blank instance id; charset [A-Za-z][A-Za-z0-9_-]*. Emitted as data-juneau-calendar.

    • endpoint

      public String endpoint
      Same-origin path template for the per-month event GET; must contain {year} and {month}. May be null: seed-only, with month navigation disabled.

    • categories

      public List<EventCategory> categories
      Declared event categories, in legend display order. A referenced categoryId must be declared here.

    • events

      public List<CalendarEvent> events
      Optional initial-month seed events, painted into the initial month server-side and embedded as the sidecar.

    • view

      public CalendarDef.CalendarView view
      Which view to render; v1 supports CalendarDef.CalendarView.MONTH only. Defaults to MONTH.

    • weekStart

      public CalendarDef.WeekStart weekStart
      First column of the week grid; defaults to CalendarDef.WeekStart.SUNDAY.

    • initialMonth

      public Integer initialMonth
      Optional 1-based initial month (1..12); paired with initialYear.

    • initialYear

      public Integer initialYear
      Optional initial year; paired with initialMonth.

    • maxPerDay

      public Integer maxPerDay
      Optional max chips per day before "+N more"; defaults to DEFAULT_MAX_PER_DAY.

  • Constructor Details

  • Method Details

    • create

      public static CalendarDef create()
      Creates an empty calendar definition.
      Returns:
      A new CalendarDef.

    • id

      public CalendarDef id(String value)
      Sets the instance id.
      Parameters:
      value - The id. Must match [A-Za-z][A-Za-z0-9_-]*.
      Returns:
      This object.

    • endpoint

      public CalendarDef endpoint(String value)
      Sets the per-month event GET template.
      Parameters:
      value - A same-origin path template containing {year} and {month}, or null for seed-only.
      Returns:
      This object.

    • categories

      public CalendarDef categories(EventCategory... value)
      Sets the declared categories, in legend order.
      Parameters:
      value - The categories.
      Returns:
      This object.

    • events

      public CalendarDef events(CalendarEvent... value)
      Sets the initial-month seed events.
      Parameters:
      value - The seed events.
      Returns:
      This object.

    • view

      public CalendarDef view(CalendarDef.CalendarView value)
      Sets the view.
      Parameters:
      value - The view.
      Returns:
      This object.

    • weekStart

      public CalendarDef weekStart(CalendarDef.WeekStart value)
      Sets the week start column.
      Parameters:
      value - The week start.
      Returns:
      This object.

    • initial

      public CalendarDef initial(int year, int month)
      Sets the initial year and 1-based month together.
      Parameters:
      year - The initial year.
      month - The 1-based initial month (1..12).
      Returns:
      This object.

    • maxPerDay

      public CalendarDef maxPerDay(int value)
      Sets the max chips per day before "+N more".
      Parameters:
      value - The cap; must be >= 1.
      Returns:
      This object.

    • effectiveView

      public CalendarDef.CalendarView effectiveView()
      The effective view — the declared view or CalendarDef.CalendarView.MONTH when unset.
      Returns:
      The effective view.

    • effectiveWeekStart

      public CalendarDef.WeekStart effectiveWeekStart()
      The effective week start — the declared weekStart or CalendarDef.WeekStart.SUNDAY when unset.
      Returns:
      The effective week start.

    • effectiveMaxPerDay

      public int effectiveMaxPerDay()
      The effective chip cap — the declared maxPerDay or DEFAULT_MAX_PER_DAY when unset.
      Returns:
      The effective chip cap.

    • effectiveLaneBudget

      public int effectiveLaneBudget()
      The per-week-row spanning-bar lane budget — effectiveMaxPerDay() clamped to MAX_LANES_PER_WEEK.

      Spanning bars occupy lanes counted against this budget; maxPerDay itself continues to cap the non-spanning chips (single-day all-day plus timed) inside a day cell. The two caps are separate on purpose: a bar crossing a cell does not consume that cell's chip budget, and a hidden chip does not consume a lane.

      Returns:
      The derived lane budget, at least 1 and at most MAX_LANES_PER_WEEK.

    • wellFormedEvents

      public List<CalendarEvent> wellFormedEvents()
      The seed events that are well-formed enough to paint — the malformed ones are dropped, exactly as a per-month GET handler drops them via CalendarEvent.retainWellFormed(Collection).
      Returns:
      A new mutable list of paintable seed events, in declaration order. Never null.

    • validate

      public void validate()
      Description copied from interface: Widget
      Fail-closed bean validation.
      Specified by:
      validate in interface Widget

    • validate

      public void validate(Integer effectiveYear, Integer effectiveMonth)
      Fail-closed bean validation against a resolved (year, month) window.

      When initialYear/initialMonth are unset, the emitter resolves the effective window from the injected clock and passes it here so seed events are still checked against the month actually rendered.

      Parameters:
      effectiveYear - The year the initial month is rendered for, or null to skip the off-month check.
      effectiveMonth - The 1-based month rendered, or null to skip the off-month check.
      Throws:
      IllegalArgumentException - If this definition is not well-formed.