YearPlanner
Widget

A calendar view which represents a full year of events as a series of month rows with weeks aligned in columns. Each row displays one month with days aligned vertically across all months for easy comparison.

This type of view is specifically designed for larger displays and is not recommended to be offered on tablet or phone devices.

Usage as a Calendar Mode

This is normally used as the 'yearplanner'mode of a Calendar:

const calendar = new Calendar({
    modes : {
        yearplanner : {
            // YearPlanner-specific config
            eventHeight : 18,
            dayNameFormat : 'd1'
        }
    },
    mode : 'yearplanner',
    date : new Date(2024, 0, 1)
});

Standalone Usage

It may also be used standalone as a regular Widget:

const yearPlanner = new YearPlanner({
    appendTo : 'container',
    date     : new Date(2024, 0, 1),
    year     : 2024,

    eventStore : new EventStore({
        data : [{
            id         : 1,
            name       : 'Company Meeting',
            startDate  : '2024-03-15',
            endDate    : '2024-03-15'
        }]
    })
});

As a standalone widget, it will lack the capabilities of the Calendar class, such as keyboard-based event to event navigation.

Month Filtering

The YearPlanner includes a built-in toolbar with a month filter combo that allows users to show/hide specific months:

const yearPlanner = new YearPlanner({
    tbar : {
        items : {
            monthFilter : {
                // Start with only Q1 months visible
                value : [0, 1, 2]  // January, February, March
            }
        }
    }
});

Users can select/deselect months in the filter to dynamically adjust which months are displayed. This is useful for focusing on specific time periods or comparing seasonal patterns.

Key Features

Week Alignment: Days are aligned vertically across all months for easy visual comparison
Month Filtering: Built-in combo to show/hide specific months
Expandable Rows: Click month row header to expand and see all events when overflow occurs
Responsive: Automatically adjusts day name format based on available width
Custom Styling: Each month row can be styled individually using CSS

Useful configs

Config	Description
year	The year to display
eventHeight	Height of event bars in pixels
view	Config for child month row views
dayNameFormat	Format for day name column headers
monthNameFormat	Format for month name row headers

Configs

Configs are options you supply in a configuration object when creating an instance of this class

date : Date

A date which specifies the year to display. All types of calendar view have a date config which they use to set their visible date range according to their configuration and type.
dayNameFormat : 'ddd'/'dd'/'d1'/Stringddd
The DateHelper format string for day names in the column headers. The day names are displayed at the top of the year planner, above all month rows.

Common formats:
- 'ddd' - Short day names (Mon, Tue, Wed, ...)
- 'dd' - Minimal day names (Mo, Tu, We, ...)
- 'd1' - Single letter (M, T, W, ...)
The format automatically responds to the Calendar's responsive breakpoints.
eventHeight : Number/String20

The height of event bars in this view. This can be a numeric value in pixels or a CSS unit measure such as '2em'.
monthNameFormat : 'MMMM'/'MMM'/'MM'/StringMMMM
The DateHelper format string for month names in the row headers. Each month row displays its month name on the left side using this format.

Common formats:
- 'MMMM' - Full month name (January, February, ...)
- 'MMM' - Short month name (Jan, Feb, ...)
- 'MM' - Numeric month (01, 02, ...)
tbar : ToolbarConfig/null
The toolbar configuration for the YearPlanner. By default, includes a month filtering UI consisting of a group of toggleable buttons representing each month. Pressed buttons indicate visible months.

The default toolbar contains:
- monthButtons: A group of toggleable buttons representing each month. Pressed buttons indicate visible months. By default, all months are shown.
You can customize the toolbar by providing your own configuration:
```
tbar : {
    items : {
        monthFilter : {
            // Start with only Q1 visible
            value : [0, 1, 2]
        },
        customButton : {
            type : 'button',
            text : 'Export',
            onAction : 'up.onExport'
        }
    }
}
```
Or disable the toolbar entirely:
```
tbar : null
```
view : CalendarRowConfig
A config object used to configure all child month row views. Each of the 12 month rows in the YearPlanner is an instance of CalendarRow (specifically, the internal YearPlannerRow subclass).

The default type is 'yearplannerrow'. Properties defined here are applied to all month rows:
```
view : {
    // Apply to all month rows
    eventHeight : 18,
    autoHeight : false,
    defaultEventRowCount : 2,
    overflowClickAction : 'expand'
}
```
Any config valid for CalendarRow can be specified here and will be inherited by all month rows.

Has a corresponding runtime view property.
year : Number

The year to display.

Properties

Properties are getters/setters or publicly accessible variables on this class

isYearPlanner : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of YearPlanner class, or subclass thereof.

view : CalendarRow

After instantiation, while in use, changes to the view property, will be propagated to all child views.

This property may be used to adjust properties of every child month row view in one statement.

Has a corresponding view config.
isYearPlanner : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of YearPlanner class, or subclass thereof.

Functions

Functions are methods available for calling on the class

eachView( fn, args, thisObj )

Executes the passed function for each child calendar view in modes
next( )

Navigates to the next year by incrementing the year. Updates the date to one year later, which triggers a refresh of all month rows to display the new year.
onMonthButtonsChange( event )

private

Handles changes to the month button group, showing/hiding month rows based on pressed buttons.

When users toggle month buttons in the toolbar button group, this method updates the visibility of the corresponding month rows. Each month row's hidden property is set based on whether its index is included in the pressed button values.
previous( )

Navigates to the previous year by decrementing the year. Updates the date to one year earlier, which triggers a refresh of all month rows to display the new year.
renderDayCell( dayEvents, domConfig )

private

Renders a day cell by calling the configured dayCellRenderer and applying additional YearPlanner-specific styling.

Adds the b-other-month CSS class to cells that display dates from adjacent months (dates before the first or after the last day of the month).
renderHeaderCell( headerDomConfig, cellData )

private

Renders a day header cell by calling the configured dayHeaderRenderer and applying additional YearPlanner-specific styling.

Adds the b-other-month CSS class to header cells that display dates from adjacent months.
renderRowHeader( prefixDomConfig, calendarRow )

private
Renders the row header content for each month row in the year planner. Displays the month name and an expand/collapse button.

This method is configured as the rowHeaderRenderer for all month rows in the YearPlanner. It populates the prefix element with:
- Month name: A button (if MonthView is available) or div showing the month name
- Row expander: A button to expand/collapse the month row when it has overflow
The month name button, when clicked (if MonthView mode is available in the parent Calendar), can be used to navigate to that month in MonthView.

This method ensures that the tooltip for the expand/collapse button is updated based on the current state of the month row (expanded or collapsed).

CSS variables

CSS variables that can be set to adjust appearance

Name	Description
--b-year-planner-background	Background color for the year planner.
--b-year-planner-border-color	Border color used for year planner grid borders.
--b-year-planner-day-header-background	Background color for the shared day header.
--b-year-planner-day-header-color	Color for the shared day header.
--b-year-planner-day-header-font-size	Font size for the shared day header.
--b-year-planner-month-label-background	Background color for the month labels.
--b-year-planner-month-label-color	Color for the month labels.
--b-year-planner-month-label-font-size	Font size for the month labels.
--b-year-planner-other-month-background-color	Background color for days that are outside the current month.
--b-year-planner-other-month-border-color	Border color for days that are outside the current month. Set to transparent by default.
--b-year-planner-row-gap	Gap between month rows in the year planner.
--b-year-planner-weekend-background-color	Background color for weekends
--year-planner-header-border-bottom-width	Border bottom width for the day header cells. There is no bottom border by default, but this can be set to e.g. "1px" to visually separate the day header from the month rows.

YearPlanner
Widget

Usage as a Calendar Mode

Standalone Usage

Month Filtering

Key Features

Useful configs

See also

Configs

Properties

Functions

CSS variables

Source path

Inheritance tree5

Mixins8

Contents

YearPlanner Widget

Usage as a Calendar Mode

Standalone Usage

Month Filtering

Key Features

Useful configs

See also

Configs

Properties

Functions

CSS variables

Source path

Inheritance tree5

Mixins8

Contents

YearPlanner
Widget