The Annual Calendar presents a complete 12-month event period on one page. Visitors can use a compact calendar grid for year-wide planning or switch to an agenda that lists the events month by month.
Create this page: in the Joomla administrator, create or edit a menu item and select JEM → Annual Calendar as the menu item type. A suggested menu alias is annual-calendar.
When to Use Annual Calendar
| View | Best use | Presentation |
|---|
| Monthly Calendar |
Detailed navigation through one month at a time. |
Larger day cells with event information for the selected month. |
| Annual Calendar |
Season planning, school years, cultural programmes, fiscal years and printable year posters. |
Twelve compact month grids or a month-by-month agenda on one page. |
Calendar and Agenda Modes
Visitors can switch between the two presentations without changing the Joomla menu item:
- Calendar: shows twelve compact month grids. Coloured markers identify days containing events, and a popover lists the events on a selected day.
- Agenda: groups days and events under each month. It can include or omit days and months without events.
The selected mode is preserved while moving to the previous or next 12-month period and while opening the normal or archived event context.
Period and Navigation Options
| Option | Default | Effect |
|---|
Start month
annual_start_month |
January |
Selects the first month of the 12-month period. January produces a natural year; another month can represent a school, cultural, sports or fiscal year. |
Markers per day
annual_marker_limit |
6 |
Shows between 1 and 12 event markers in each calendar day. When more events exist, the last position becomes a +N summary. |
Show event count per day
annual_show_day_event_count |
No |
Adds a compact event-count badge to days that contain events. |
Day click target
annual_day_link_target |
Default Day view |
Opens the selected date in the normal Day view, Day Timetable or Day Timeline. |
Show empty days in agenda
annual_agenda_show_empty_days |
No |
When disabled, the agenda lists only dates containing visible events. Enable it for a complete diary-style period. |
Show empty months in agenda
annual_agenda_show_empty_months |
Yes |
Keeps all twelve month headings in agenda mode even when a month has no visible events. |
How Frontend Navigation Works
- The previous and next controls move by one complete 12-month period.
- The heading displays one year for January–December or two years when the configured period crosses a year boundary.
- A month title opens the corresponding Monthly Calendar.
- A week number opens the corresponding Weekly Calendar.
- A day opens the Day, Timetable or Timeline view selected in Day click target.
- An event title in the popover or agenda opens its Event Detail page.
Event Filters
| Filter | Default | Behaviour |
|---|
Featured only
onlyfeatured |
No |
Limits the annual period to featured events. |
Category filter mode
categoryswitch |
Exclude |
Defines whether the categories selected below are included or excluded. |
Filter categories
categoryswitchcats |
None |
Category selection used by the include/exclude mode. |
Filter venues
timeline_filter_venues |
None |
Shows events assigned to the selected venues. |
Filter event types
timeline_filter_types |
None |
Shows events assigned to the selected event types. |
Filter countries
timeline_filter_countries |
None |
Shows events whose assigned venues belong to the selected countries. |
Top category
top_category |
All categories |
Limits the view to one category branch, including its accessible descendants. |
Show archived events
show_archived_events |
No |
Includes archived events in the normal annual display. The toolbar can also open the dedicated archive context. |
All filters remain subject to normal event, category and venue publication and access rules. A menu filter cannot expose content that the current visitor is not authorised to see.
Grid, Markers and Legends
| Option | Default | Effect |
|---|
Display legend
displayLegend |
Below |
Hides the event legend or places category and/or venue filters above or below the annual calendar. |
Show only start day
show_only_start |
No |
Shows a multi-day event only on its first date instead of every date it spans. |
First weekday
firstweekday |
Monday |
Starts each month grid on Monday or Sunday. |
Show Add Event icon
show_addevent_icon |
No |
Shows the add-event action when the visitor has permission to create an event in an available category. |
Category colour marker
categoryColorMarker |
Marker block |
Uses the category colour as a block or a top bar in the category legend. |
Use category colour
eventbg_usecatcolor |
No |
Uses an available category colour for event markers and legend presentation. |
Current day colour
currentdaycolor |
#CCCC99 |
Highlights today's date when it falls inside the displayed period. |
Marker shapes communicate event duration:
- Circle: one-day event.
- Square: event lasting two or three days.
- Triangle: event lasting four to six days.
- Diamond: event lasting seven or more days.
Special Days
Special Days can colour annual-calendar cells and add descriptive badges. They are independent from events and must first be enabled and configured in JEM Settings.
| Option | Default | Effect |
|---|
Show Types of Days legend
show_types_of_days_legend |
Yes |
Displays the Special Day/Type of Day legend for the selected annual period. |
Types of Days legend order
special_day_legend_order |
Ordering ascending |
Orders legend entries by ID, configured ordering, name, start date or end date. |
In agenda mode, a date containing only Special Day information is hidden when Show empty days in agenda is disabled, because there is no event entry for that date.
Multi-day Events, Dates and Timezones
- By default, a multi-day event is represented on every date that overlaps the displayed annual period.
- Enable Show only start day when a long exhibition, course or festival should produce only one marker.
- The annual grid is date-oriented. Event times appear in popovers and in agenda mode when a start or end time is available.
- The view uses the event dates and times prepared from that event's configured time reference.
- If an event uses Venue timezone, verify the timezone stored in its venue. Joomla publication start/end dates are a separate mechanism.
Toolbar, Export and PDF
Subject to the global JEM settings and the visitor's permissions, the toolbar can provide print, PDF, iCalendar, archive and add-event actions. Calendar/Agenda is an additional Annual Calendar layout toggle.
The annual PDF is configured globally under JEM Settings → PDF Settings, not in the Joomla menu item. Its dedicated settings include:
- Paper size: A4, A3, A2, A1 or Letter.
- Portrait or landscape orientation.
- Automatic or fixed month matrix from 1 × 12 to 12 × 1.
- Top, centre or bottom vertical alignment.
- Types of Days and category legends.
- Automatic, enabled or disabled event titles, with an event limit per day.
- Horizontal and vertical spacing between month blocks.
The iCalendar action exports events for the annual period up to the global iCal item limit. PDF and print output should be tested separately because the printable year has much less space than the interactive browser view.
Page Text
Show Introtext (showintrotext) and Introtext (introtext) add editorial content above the calendar. Show footer text (showfootertext) and Footer Text (footertext) add content below it. Both visibility options are disabled by default.
Practical Configurations
Public cultural year
- Start month: January
- Markers per day: 6
- Use category colour: Yes
- Day target: Default Day view
- Legend: Below
School or course year
- Start month: September
- Category mode: Include
- Select the training/course categories.
- Show event count: Yes
- Day target: Day Timetable
Printable event poster
- Keep marker and category colours concise.
- Configure A3 or larger landscape PDF output.
- Use an automatic or 3 × 4 month matrix.
- Enable category and Types of Days legends.
- Test event-title density with real data.
Annual venue programme
- Select one or more venues.
- Optionally select the venue country.
- Day target: Day Timeline
- Show empty months in agenda: Yes
- Verify each venue timezone.
Troubleshooting
| Problem | What to check |
|---|
| No events are displayed. |
Check the 12-month period, featured/category/venue/type/country filters, top category, publication state and access levels. |
| The calendar begins in the wrong year. |
Remember that yearID identifies the year containing the configured start month. A September period can therefore display September 2026 through August 2027. |
| Only some events are visible on a busy day. |
Increase Markers per day or open the day/popover. The +N marker indicates additional events. |
| A multi-day event fills many dates. |
Enable Show only start day if only the starting date should carry a marker. |
| Agenda months or days disappear. |
Enable the corresponding Show empty days/months in agenda options. |
| Special Day colours or legend are missing. |
Enable Special Days globally, verify their date ranges and Types of Days, and enable the Types of Days legend. |
| The PDF is too dense. |
Use a larger paper size, change the month matrix, reduce titles per day or hide event titles and unnecessary legends. |
| An event appears at an unexpected time. |
Review the event time reference and its Joomla, venue or custom timezone; do not correct it by changing calendar filters. |
Before Publishing
- Test the first and last months of the configured 12-month period.
- Check one-day, multi-day, open-time and timed events.
- Verify previous/next navigation and Calendar/Agenda switching.
- Open a month, week, day and event from the annual grid.
- Test days with more events than the marker limit.
- Check category colours, Special Days and both legends.
- Test as a guest and as a user with restricted content access.
- Verify print, PDF and iCalendar output when those actions are enabled.
- Test desktop and mobile widths with a full year of realistic data.
Related Documentation
Configuration and content
Development References
