Calendar Setup
This is for advanced users only - we recommend asking Pixfizz support for an example template definition to build a calendar.
Template Definition
The first step when setting up calendar templates is defining at least two sequences of dates:
The sequence of dates that we want to loop over when a new user project is generated. The number of elements in this sequence will typically correspond to the number of dynamically generated page sets. For a standard monthly calendar, there will always be exactly 12 dates in this set -- one for each month. With weekly and daily calendars things are not as simple since not all years contain the same number of weeks and leap years contain 366 rather than 365 days.
The sequence(s) of dates that are used in page templates to dynamically fill available date cells on the page. On a basic daily calendar the sequence will contain a single date (the “current” day) and a basic weekly calendar will contain a sequence of 7 days. Monthly calendars are more complicated since the number of days in a month is not fixed and you might want to display some dates from previous and next month in addition to current month to be able to fit the calendars in a nice weekly grid.
The <dates> element
Date sequences are defined with <dates name=”my-date-sequence”>…</dates> blocks. Each date sequence must have a unique name. Dates sequences can be used in two places:
On <set> elements using the foreachdate attribute: <set foreachdate=”my-date-sequence”>…</set> will repeat the one time for each date in the “my-date-sequence” sequence. This is similar to <set grow=”true” ...> in the sense that it can output more than one copy of the set.
On <page> elements using the dates attribute: <page dates=”my-other-date-sequence” … /> will make dates defined in “my-other-date-sequence” available to the page. These can only be used by pages inside a <set foreachdate=”…”> element.
The <dates> element defines a sequence of dates in relation to an “input” date. The input date for date sequences used in <set foreachdate=”…”> is the start date that is chosen by the user when building the calendar. This is typically Jan 1st of the current or upcoming year. If no start date is provided it defaults to the current date.When a sequence of dates is used in <page dates=”…” … />, the input date is the date corresponding to the current element of the sequence of dates being looped over to build page sets. For example when building a daily calendar, the sequence being used in <set foreachdate=”my-sequence”> will be a sequence of all days in the year and pages inside that set will receive that date as their input. The <dates> element can have the following children:
<date>
<defdate>
<dategen>
<dateshift>
The <date> element
The <date> element in its simplest form simply adds the input date to the sequence. If the input date is Jan 1st, <date/> simply adds Jan 1st to the sequence.The <date> element supports the following attributes:
year
month
day
weekday
The “year”, “month”, and “day” attributes take numeric values and add a date that’s “shifted” from the input date in some way. Examples:
<date day=”3”/>: generates a date with the date component set to three; Jan 1st → Jan 3rd, Jan 30th → Jan 3rd
<date day=”+5”/>: generates a date by shifting the input date five days forward; Jan 1st → Jan 5th, Jan 30th → Feb 4th
<date day=”-1”/>: generates a date by shifting the input date one day back: Jan 1st → Dec 31st of previous year, Jan 30th → Jan 29th
year and month work in exactly the same way.
The weekday attribute takes one of these values: “MO”, “TU”, “WE”, “TH”, “FR”, “SA”, “SU” and shifts the input date to the specified weekday in the same calendar week. We use the convention where a week starts with Monday and ends with Sunday. Example:
<date weekday=”TU”/>: Jan 1st 2020 → Dec 31st 2019 because 2020 started on a Wednesday.
More than one of these attributes can be used at the same time. The order in which the date shifts are performed is defined to go from the highest to the lowest component: year → month → weekday → day. The <date> element can also contain a “tag” attribute which lets you add custom tags to the generated date in the sequence. The tags can be used for transformations when building the book (more info below).
The <defdate> element
The <defdate name=”my-named-date”> element works in exactly the same way as the <date> element, except that it does not add the generated date to the output date sequence and instead only stores it under a name so that it can be referenced with <dategen> or <dateshift> elements (see below). Example: <defdate weekday=”SU” name=”last-day-of-week”/> stores the last day of the input week under “last-day-of-the-week”.
The <dategen> element
freq
interval
count
until
wkst
byday
bymonth
bymonthday
The <dateshift> element
Works very similarly to the <date> element except that it doesn’t add anything to the output date sequence and instead provides a new scope for its children where the input date is modified.
Examples:Let’s say the input date is Jan 1st. The following will generate a sequence of two dates: Jan 1st (from the <date/> element outside <dateshift>) and Feb 1st (from the <date/> element inside <dateshift>).
<date/><dateshift month=”+1”> <date/></dateshift>
Previous example would be equivalent to:<date/><date month="1"/>
In this example we use <dategen> together with <dateshift> to generate the first three Fridays in March:<dateshift month="+3"> <dategen freq="weekly" count="3" byday="FR"/></dateshift>
The <datesfrom> element
This tag is useful when you want to reuse some date construction logic in multiple places. It accepts and requires a single “name” attribute, which is the name of the <dates> element which we want to use as a template.For example if you have to define a list of Mondays for each month:
<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"> <dates from="mondays"/> </dateshift></dates><dates name="february-months"> <dateshift month="2" day="1"> <datesfrom name="mondays"/> </dateshift></dates><dates name="march-months"> <dateshift month="3" day="1"> <datesfrom name="mondays"/> </dateshift></dates><!-- ... etc ... -->
Without the help of the <datesfrom> tag you would have to repeat the contents of the <dates name=”modays”> tag inside the <dates> block for every month.
The output date sequence
The dates defined inside a <dates> element are always returned ordered and with duplicates removed.
Example with input date Jan 1st:<dates name="my-dates"> <date /> <date /></dates>This will return a sequence with length one, containing a single date (Jan 1st) rather than two duplicate dates.
The following sequence will return Jan 1st, Jan 2nd even though Jan 2nd is technically defined first inside <dates>:<dates name="my-dates"> <date day="+1"/> <date /></dates>
Design
There are two places where dates are used in designs:
In page templates (required)
In calendar transformations json rules (optional)
Dates in page templates
In the admin editor, text, image, and group elements now have a third editor panel in addition to “Standard” and “Admin” called “Dates”. Inside that panel you can mark each text element as corresponding to a date from a date sequence defined in the template definition.You’ll have to enter the index of the date in the sequence that the element corresponds to. The first date in the sequence has index 1, the second has index 2, etc. Think of this as similar to the “%dnn%” placeholders used in the old calendar implementation.For text elements you can also chose which part of the date (day number, month name, …) to fill the text box with if the text box gets matched to a date.Any element that is marked as a date but is not matched with a date from the corresponding sequence when building the book will get deleted. This can happen if for example you define a text box with a date index of 8 and the date sequence only generates 7 dates.
Calendar Transformations
There’s a new text area on admin design page that lets you input a JSON array representation of rules and transformations that you can use to modify certain date elements within pages.Each transformation in the array needs to have at least two items: “selector” and “action”. The selector is a JSON object that defines which elements should match the transformation rule. It must contain at least one of the following:
series: only match elements from this date series
name: only match elements with this name
tag: only match elements corresponding to dates tagged with the given tag in the template definition
year: only match elements corresponding to the given year (number)
month: only match elements corresponding to the given month (number)
weekday: only match elements corresponding to the given weekday (two-character code: MO, SU, …)
day: only match elements corresponding to this day (number)
calendar: only match elements that match dates which have captions assigned to them. The value can be one of:
any - matches if any calendars that were used in the project contains a caption for this element
user - matches if any user-provided calendar contains a caption for this element.
website - matches if any website-provided calendar (created under /calendars in the admin) contains a caption for this element
website:<code> (for example “website:holidays”) - matches if the website-provided calendar with this particular code contains a caption for the date. Useful for example to color all dates that are holidays red.
The action tag can be one of:
delete
set-color
set-text
set-image-src
When the action is “delete” no other entries are required in JSON rule definition, but with other entries, a “value” must be given. This example will change the color of all text elements corresponding to a Sunday to red, and delete any element corresponding to a Friday 13th:
CMS Tags
<px:theme:start:dates />
This tag now has additional options:
day_select: When set to ‘true’ or ‘daily’ let’s the user select any day from the selected month. When set to ‘weekly’ let’s the users select any starting weekday in the month (for example all Mondays in March)
weekstart: Value should be one of MO, TU, WE, TH, FR, SA, SU. It defaults to MO. Only makes sense when used together with day_select=”weekly”.
start_year and end_year now also accept relative numbers (example: start_year=”-2”, end_year=”+1”) in addition to absolute year numbers.
FOR RADIUS ONLY <px:theme:start:calendars />
This tag renders when calendars with captions exist. Without any attributes it will look for all calendars defined on the current website that do not belong to a specific user AND the calendars that belong to current user. You can limit that with the ‘type’ attribute: type=”user” will only return calendars that belong to the current user while type=”website” will only return website’s “global” calendars that don’t belong to any specific user. You can you the code=”somecode,othercode” attribute to filter calendars by code. Inside <px:theme:start:calendars> tag you can use <px:theme:calendars:checkboxes /> to render checkboxes for the available calendars. Captions from calendars that the user selects will be used when building the project.
Last updated