> 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/calendar-transformations.md).

# Calendar Transformations

JSON rules that change, recolor or remove date elements while a calendar project is being built. This is how one page design produces twelve months.

JSON rules that change, recolor or remove date elements while a calendar project is being built. This is how one page design produces twelve different months.

## Overview

Calendar transformations live in a text area on the design page in admin. The value is a JSON array. Each rule in the array has a **selector**, which decides which elements it applies to, and an **action**, which decides what happens to them.

Rules run when the project is built, so nothing you see in the admin design tool reflects them. Always check the result in customer mode or in the generated PDF.

## How to add transformations

1. Go to **Admin > Products > Designs** and open the design.
2. Find the **Calendar Transformations** field.
3. Paste a JSON array. If you are combining several rule sets, merge them into one array rather than pasting several arrays.
4. Save, then create a test project and check the months the rules affect.

## Selectors

A selector is a JSON object and must contain at least one of these keys. When several keys are present, all of them must match.

| Key        | Matches                                                                |
| ---------- | ---------------------------------------------------------------------- |
| `series`   | Elements bound to this date series                                     |
| `name`     | Elements with this element name                                        |
| `tag`      | Elements whose date carries this tag, set with `tag` in the definition |
| `year`     | Elements whose date falls in this year (number)                        |
| `month`    | Elements whose date falls in this month (number, 1 to 12)              |
| `weekday`  | Elements whose date falls on this weekday (`MO` to `SU`)               |
| `day`      | Elements whose date falls on this day of the month (number)            |
| `week`     | Elements whose date falls in this week number of the year (number)     |
| `calendar` | Elements whose date has a caption in a calendar                        |

The `calendar` selector takes one of these values:

* `any` - any calendar used in the project has a caption for this date
* `user` - a customer-provided calendar has a caption for this date
* `website` - a calendar created under **/calendars** in admin has a caption for this date
* `website:<code>`, for example `website:holidays` - the website calendar with that code has a caption for this date

## Actions

| Action          | Requires a value          | Effect                                  |
| --------------- | ------------------------- | --------------------------------------- |
| `delete`        | No                        | Removes the element from the built page |
| `set-color`     | Yes, a hex color          | Recolors the element                    |
| `set-text`      | Yes, the replacement text | Replaces the text content               |
| `set-image-src` | Yes, an image reference   | Swaps the image                         |

## Recipes

### Grey the days from the previous and next month

The days outside the displayed month are tagged `out-of-range` by the month-grid sequence in the definition. One rule styles all of them.

```json
[
  { "selector": { "tag": "out-of-range" }, "action": "set-color", "value": "#b3b3b3" }
]
```

Replace `set-color` with `delete` to hide them entirely. Remove the rule altogether to print them in the same style as the rest of the month.

### Red Sundays and holidays

```json
[
  { "selector": { "weekday": "SU" }, "action": "set-color", "value": "#cc0000" },
  { "selector": { "calendar": "website:holidays" }, "action": "set-color", "value": "#cc0000" }
]
```

### A logo on December only

Name the logo element `brand-logo` in the design, then delete it on the other eleven months. One rule per month:

```json
[
  { "selector": { "name": "brand-logo", "month": 1 }, "action": "delete" },
  { "selector": { "name": "brand-logo", "month": 2 }, "action": "delete" }
]
```

Continue through month 11. There is no "all months except" selector, so every month that should not show the element needs its own rule. The complete eleven-rule version is in [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md).

### Alternating artwork on odd and even months

Put both versions of the artwork on the same page, named `art-odd` and `art-even`, then delete the one that does not apply. Twelve rules, one per month.

```json
[
  { "selector": { "name": "art-even", "month": 1 }, "action": "delete" },
  { "selector": { "name": "art-odd",  "month": 2 }, "action": "delete" }
]
```

This keeps the calendar in January-to-December order. Splitting the loop into odd and even date sequences also works, but it outputs all the odd months first and then all the even months, which is almost never what a calendar should do.

### Custom month names

```json
[
  { "selector": { "name": "month", "month": 1 }, "action": "set-text", "value": "JAN" }
]
```

Only use this when you want something other than the standard month name, such as an abbreviation or upper case. Standard month names are translated automatically. See [Month Names and Translations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/month-names-and-translations.md).

### A different background per season

```json
[
  { "selector": { "name": "season-bg", "month": 12 }, "action": "set-image-src", "value": "winter.jpg" }
]
```

### Combined example

Red Sundays, and no element at all on Friday the 13th.

```json
[
  { "selector": { "weekday": "SU" }, "action": "set-color", "value": "#ff0000" },
  { "selector": { "weekday": "FR", "day": 13 }, "action": "delete" }
]
```

## Tips

* A transformation can only find an element by name if the element has a name. Set it in the **Admin** panel on the element before writing rules.
* Rules that select on `name` alone apply to every month. Add `month` to scope them.
* If a transformation does nothing, check the element name for a typo and check that the element is actually bound to a date in the **Dates** panel. Elements with no date binding are not matched by date selectors.
* Ready-made rule sets for all of the above are in [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md).

## Related

* [Calendar Setup](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup.md)
* [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)
* [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md)
* [Month Names and Translations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/month-names-and-translations.md)
* [Calendar Troubleshooting](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-troubleshooting.md)
