> 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/date-sequences-reference.md).

# Date Sequences Reference

The XML vocabulary used to define date sequences in a calendar or planner template definition.

The XML vocabulary used to define date sequences in a calendar or planner template definition.

## Overview

Every calendar template defines at least two kinds of sequence:

* **The loop sequence.** The dates a page set repeats over, used with `foreachdate`. A standard monthly calendar has exactly 12 dates here, one per month. Weekly and daily calendars are less predictable: not every year has the same number of weeks, and leap years have 366 days.
* **The cell sequence.** The dates available to a page, used with the `dates` attribute, that fill the date cells in the design. A daily calendar needs a single date. A weekly calendar needs seven. A monthly grid needs 42, because the number of days in a month varies and the grid usually shows a few days from the previous and next month to fill the weeks.

Sequences are declared with `<dates name="my-sequence"> ... </dates>`. Every sequence needs a unique name.

## How sequences are used

* `<set foreachdate="my-sequence"> ... </set>` repeats the set once for every date in the sequence, in the same way `<set grow="true">` can output more than one copy.
* `<page dates="my-other-sequence" ... />` makes the dates in that sequence available to the page. This only works on pages inside a `<set foreachdate="...">`.

Each sequence is built relative to an **input date**:

* For a sequence used in `foreachdate`, the input date is the start date the customer chooses, typically 1 January of the current or coming year. With no start date it defaults to today.
* For a sequence used on a page, the input date is the date currently being looped over.

The output of a `<dates>` block is always sorted and de-duplicated. Two `<date/>` elements with the same result produce one date, and dates come out in calendar order regardless of the order they were declared.

## The elements

### `<date>`

Adds a date to the sequence. With no attributes it adds the input date unchanged.

| Attribute              | Behavior                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `year`, `month`, `day` | A plain number sets that component. A signed number shifts it.                        |
| `weekday`              | `MO` to `SU`. Moves to that weekday within the same week. Weeks run Monday to Sunday. |
| `tag`                  | Adds a custom tag to the generated date, for later use in transformations.            |

Examples, with 1 January as the input date:

* `<date day="3"/>` sets the day to the 3rd. 1 Jan becomes 3 Jan; 30 Jan also becomes 3 Jan.
* `<date day="+5"/>` shifts five days forward. 1 Jan becomes 6 Jan; 30 Jan becomes 4 Feb.
* `<date day="-1"/>` shifts one day back. 1 Jan becomes 31 Dec of the previous year.
* `<date weekday="TU"/>` on 1 January 2020 gives 31 December 2019, because 2020 began on a Wednesday.

When several attributes are combined the shifts are applied from the largest component to the smallest: year, then month, then weekday, then day.

### `<defdate>`

Works exactly like `<date>` but does not add anything to the sequence. It stores the result under a name so `<dategen>` and `<dateshift>` can refer to it.

```xml
<defdate weekday="SU" name="last-day-of-week"/>
```

### `<dategen>`

Generates a run of dates. It follows the iCal RRULE standard, with the input date as DTSTART. Supported attributes: `freq`, `interval`, `count`, `until`, `wkst`, `byday`, `bymonth`, `bymonthday`, plus `tag`.

`until` takes the name of a date previously stored with `<defdate>`.

```xml
<dategen freq="daily" count="42"/>
<dategen freq="weekly" count="3" byday="FR"/>
```

### `<dateshift>`

Takes the same attributes as `<date>`, adds nothing to the sequence, and instead gives its children a new input date. Use it to build a run of dates relative to somewhere other than the input date.

These two are equivalent:

```xml
<date/>
<dateshift month="+1">
  <date/>
</dateshift>
```

```xml
<date/>
<date month="1"/>
```

And this generates the first three Fridays in March:

```xml
<dateshift month="+3">
  <dategen freq="weekly" count="3" byday="FR"/>
</dateshift>
```

### `<datesfrom>`

Reuses another named sequence, so the same logic does not have to be repeated. It takes a single `name` attribute: the name of the `<dates>` block to reuse.

```xml
<dates name="mondays">
  <defdate name="last-day-of-month" month="+1" day="-1"/>
  <dateshift weekday="MO">
    <dategen freq="weekly" until="last-day-of-month"/>
  </dateshift>
</dates>

<dates name="january-mondays">
  <dateshift month="1" day="1">
    <datesfrom name="mondays"/>
  </dateshift>
</dates>

<dates name="february-mondays">
  <dateshift month="2" day="1">
    <datesfrom name="mondays"/>
  </dateshift>
</dates>
```

## Common patterns

### Twelve-month loop

```xml
<dates name="by-month">
  <dateshift day="1">
    <dategen freq="monthly" count="12"/>
  </dateshift>
</dates>
```

### Month grid

Six weeks of cells with the surrounding days tagged, so they can be greyed or hidden later. Full versions for both week starts are in [Calendar Week Starting with Monday](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-week-starting-with-monday) and [Calendar Week Starting with Sunday](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-week-starting-with-sunday).

### Odd and even months

Two loop sequences, each producing six dates:

```xml
<dates name="by-odd-month">
  <dateshift day="1">
    <dategen freq="monthly" count="6" interval="2"/>
  </dateshift>
</dates>

<dates name="by-even-month">
  <dateshift month="+1" day="1">
    <dategen freq="monthly" count="6" interval="2"/>
  </dateshift>
</dates>
```

Note the page-order consequence: two separate sets output all six odd months first and then all six even months. For a calendar that must run January to December in order, alternate the artwork with calendar transformations on a single set instead. See [Calendar Transformations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-transformations.md).

## Tips

* The [rrule.js demo page](https://jakubroztocil.github.io/rrule/) is a quick way to check what a `<dategen>` rule will produce before putting it in a definition.
* Tag anything you may want to style or remove later. Tags cost nothing and are the cleanest selector to write a transformation against.
* `autofill` and `reorder` are legacy attributes. They no longer do anything.

## Related

* [Calendar Setup](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup.md)
* [Calendar Transformations](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/calendar-transformations.md)
* [Example Calendar Templates](https://help.pixfizz.com/products-and-design/how-to-create-templates/calendar-setup/example-calendar-templates.md)
* [XML Definition Parameters](https://help.pixfizz.com/products-and-design/how-to-create-templates/xml-definition-parameters)
* [XML Set Parameters](https://help.pixfizz.com/products-and-design/how-to-create-templates/xml-set-parameters)
* [XML Page Parameters](https://help.pixfizz.com/products-and-design/how-to-create-templates/xml-page-parameters)
