> For the complete documentation index, see [llms.txt](https://help.pixfizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup.md).

# Calendar Setup

How calendar and planner products are built in Pixfizz: date sequences, date-bound design elements, and the transformations that change each month.

How calendar and planner products are built in Pixfizz: the date sequences in the template definition, the date panel in the design tool, and the calendar transformations that change what appears on each month.

## What applies to your setup

Most of building a calendar is platform work and applies to everyone.

* **The template definition, the design and the calendar transformations are platform-level.** They behave identically however the storefront is built: the Pixfizz CMS, Shopify + Pixfizz, or your own front end talking to the Pixfizz API. This is the bulk of the work and the bulk of these articles.
* **The start-date selector is storefront work.** The section on it below describes the Pixfizz CMS, and specifically the Shopper 24 template. If you run your own storefront or create projects through the API, you supply the start date yourself when the project is created, and none of the product-page settings in that section apply to you.

If you are building calendar designs for a site with its own front end, read everything except the start-date selector.

## Get AI help before you start

Calendars are the most repetitive product on the platform to build, and an AI assistant that knows Pixfizz removes most of that repetition. Setting one up takes about five minutes and is worth doing before you start a calendar range rather than after.

The guide is at [aisetup.pixfizz.com](https://aisetup.pixfizz.com/). It covers two things:

* **The Pixfizz knowledge base.** The public `pixfizz/pixfizz-knowledge` repository, added to a Claude project so the assistant answers from the Pixfizz manual instead of guessing.
* **The Pixfizz Storefront plugin.** Installed from the `pixfizz/claude-plugins` marketplace, it adds skills for specific jobs.

The skills that earn their keep on a calendar:

| Skill               | What it does for a calendar                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `xml-templates`     | The template definition documented across these articles: geometry, bleed, layers, output      |
| `photobook-layouts` | Generates the frame arrangements for the photo page that faces each month grid                 |
| `template-resize`   | Derives the same calendar at a second size, or a whole size range, with the geometry rewritten |
| `pricing-formulas`  | Per-page and quantity pricing, and the traps that make a price silently wrong                  |

Useful things to hand it: adapting one of the [example definitions](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md) to your page size, explaining what an unfamiliar date sequence does line by line, or generating the eleven or twelve near-identical transformation rules for a month-by-month change.

One limit worth knowing before you rely on it. It can see the knowledge base and your public storefront, nothing else. It cannot see your admin, your orders or your account, and it can be confidently wrong. Never paste a definition or a pricing formula into a live product on its word alone, test it first.

## Overview

A Pixfizz calendar is an ordinary design product with two extra ingredients.

1. **Date sequences** in the template definition. These tell the platform how many page sets to generate and which dates are available to fill the cells on each page.
2. **Date-aware elements** in the design. A text, image or group element can be bound to a date in a sequence, so the same page design produces a different page for every month.

A third, optional ingredient is **calendar transformations**: JSON rules that change, recolor or delete date elements when the project is built. Anything that varies month by month (a logo on December only, red Sundays, holiday captions, alternating artwork) is done with transformations rather than with twelve separate page designs.

Building a calendar from scratch is advanced work. Start from one of the ready-made definitions in [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md) and adapt it, rather than writing a definition from a blank page.

## How to build a calendar

1. Create the design product as usual under **Admin > Products**, and attach a template.
2. Paste a calendar definition into the template's **Definition** field. Start from [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md).
3. Open the design in the admin design tool and lay out the cover, the image page and the calendar grid page.
4. Bind the grid cells to dates using the **Dates** panel on each element. See [Build a 12-Month Wall Calendar](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/build-a-12-month-wall-calendar.md).
5. Add calendar transformations if the design changes from month to month. See [Calendar Transformations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-transformations.md).
6. Make sure the customer can choose a start date. On the Pixfizz CMS that means turning on the start-date selector; on your own storefront it means passing the start date when the project is created.
7. Test the full range before publishing, and check the generated PDF for every month, not just January.

The full walkthrough, in order, with what to check at each step, is in [Build a 12-Month Wall Calendar](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/build-a-12-month-wall-calendar.md).

## How it works

### Date sequences

Date sequences are defined at the top of the template definition inside `<dates name="...">` blocks, and are used in two places:

* On a `<set>` element, with `foreachdate`. The set repeats once for every date in the sequence. A 12-date sequence produces 12 copies of the set, which is how a 12-month calendar is generated.
* On a `<page>` element, with `dates`. The dates in that sequence become available to the page, so date-bound elements on the page can be filled. Pages can only use `dates` when they sit inside a `<set foreachdate="...">`.

Every sequence is built relative to an **input date**. For a sequence used in `foreachdate`, the input date is the start date chosen when the project is created, typically 1 January of the coming year. For a sequence used on a page, the input date is the date currently being looped over, so a page inside a by-month loop receives the first of that month.

The elements available inside `<dates>` are `<date>`, `<defdate>`, `<dategen>`, `<dateshift>` and `<datesfrom>`. The full reference is in [Date Sequences Reference](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/date-sequences-reference.md).

### Dates in the design

In the admin design tool, text, image and group elements have a third panel alongside **Standard** and **Admin**, called **Dates**. There you bind the element to a sequence and to a position in it.

* The **index** is the position of the date in the sequence, starting at 1. A 42-cell month grid uses indexes 1 to 42.
* For text elements you also choose **which part** of the date to print: day number, month name, weekday name, year, and so on.
* An element bound to a date that the sequence does not produce is deleted when the project is built. A cell with index 43 in a 42-date sequence simply disappears.

Month names, weekday names and other date words come from the platform's built-in translations, in the language the project is created in. You do not need to translate them yourself. See [Month Names and Translations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/month-names-and-translations.md).

### Calendar transformations

Calendar transformations are a JSON array on the design page in admin. Each rule has a **selector** that decides which date elements it matches, and an **action** that changes them: `delete`, `set-color`, `set-text` or `set-image-src`.

Because a selector can match on month, weekday, day, week number, tag, element name, date series or calendar caption, one page design can behave differently on every month of the year. See [Calendar Transformations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-transformations.md) for the full selector and action reference plus ready-made rule sets.

### The start-date selector (Pixfizz CMS only)

> This section applies only to storefronts running the Pixfizz CMS, and the settings named are those of the Shopper 24 template. On your own storefront or an API integration, the start date is supplied when the project is created and none of this applies.

The start date is the input date for the entire definition, so every calendar product needs one. It is switched on per product, not in the template.

**Turning it on.** Set the product custom field `select_date`. The Shopper product form renders the start-date selector only when that field is set; without it the calendar falls back to the current date, which is almost never what someone buying next year's calendar wants.

**What the customer sees.** A month selector and a year selector, which post as `book[start_month]` and `book[start_year]`.

**Year only.** Set the product custom field `hide_select_month` to hide the month selector and leave the customer choosing a year. Use it for calendars that always run January to December.

**The year range.** The year selector's `min` and `max` are offsets from the current year, not absolute years. The Shopper default is `min="0" max="3"`, so this year plus the next three.

**The default selection rolls over.** From September onwards the selector defaults to January of next year. Before September it defaults to the following month of the current year, so a customer in October is offered next year without touching anything.

**Making the customer confirm.** Set the site checklist key `admin/checklist/confirm-start-date` to `TRUE` to add a confirmation checkbox that keeps Add to Cart disabled until it is ticked. The wording comes from `admin/checklist/confirm_start_date_label`. Worth using on products where a wrong start year means a reprint.

**Customer and website calendars.** Two design custom fields feed dated captions into the project, and those captions are what the `calendar` transformation selector matches on:

* `personal_dates` offers signed-in customers their own saved life events.
* `holiday_dates` offers the website calendars created under **/calendars** in admin.

`select_date`, `hide_select_month`, `personal_dates` and `holiday_dates` are custom fields, so each one needs its definition created on the site before a value can be stored.

## Tips

* Always give the month-name text element a **name**, such as `month`. Transformations select on the element name, and nothing that changes month names, logos or artwork per month works without one.
* Tag the days that fall outside the displayed month `out-of-range` in the definition, then style them with a transformation. That keeps the greying decision in one place instead of in the artwork.
* Test the last month as well as the first. Sequence errors usually show up in December, not January.
* Editing a calendar element on an order that has already generated production files does not regenerate them. Delete the existing generated file and force a refulfil from the order page in admin, or the lab prints the version from before your edit.
* `autofill` and `reorder` appear in older calendar definitions. They no longer do anything and can be ignored.

## Related

* [Build a 12-Month Wall Calendar](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/build-a-12-month-wall-calendar.md)
* [Date Sequences Reference](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/date-sequences-reference.md)
* [Calendar Transformations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-transformations.md)
* [Month Names and Translations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/month-names-and-translations.md)
* [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md)
* [Calendar Troubleshooting](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-troubleshooting.md)
* [Calendar Week Starting with Monday](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-week-starting-with-monday)
* [Calendar Week Starting with Sunday](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-week-starting-with-sunday)
* [Pixfizz AI setup guide](https://aisetup.pixfizz.com/)
