# Add to Calendar (`core/button` variation `calendar-button`)

> A core/button that adds the current event to the visitor's calendar, using the event's dates from Fair Events.

- **Supplied by:** fair-events (see `block-docs/index.json` for the release version)
- **Status:** authoring
- **Registration:** post-type — Fair Events adds the isCalendarButton attribute to core/button on every site. The editor offers the variation only while editing a post type enabled for events (fair_event by default).

## Purpose

An "Add to Calendar" button for event pages that needs no date entry: it is a
regular `core/button` marked with `isCalendarButton`, and Fair Events fills in
the event's start, end, all-day flag, recurrence rule, title, permalink,
excerpt, and venue (or address) when the page is rendered. Clicking it opens
the same calendar-service menu as Fair Calendar Button.

This is an extension of a core block, not a separate block type: it never
appears in `/wp/v2/block-types` under a Fair namespace. Discover it through
`variations` in Fair Events' `block-docs/index.json`.

## Composition

Use it like any button: inside `core/buttons`. Text, colors, and styles are
the button's own. Its `url` is ignored.

## Attributes

- `isCalendarButton` — `true` turns a `core/button` into a calendar button.
  Fair Events registers this attribute on `core/button` for every post type;
  the inserter variation is only offered on event post types.

## Prerequisites

- The post being rendered must be of a post type enabled for events and have
  a Fair Events event date. Otherwise the button renders as a plain link-less
  button.
- `?event_date=<YYYY-MM-DD>` selects one occurrence of a recurring event.
- Fair Calendar Button does **not** need to be active; Fair Events ships its
  own frontend script for this variation. When Fair Calendar Button is
  active, its block can be transformed into this variation.

## Rendering

The button's `a.wp-block-button__link` receives `data-calendar-button="true"`
plus `data-start`, `data-end`, `data-all-day`, `data-title`, `data-url`,
`data-location`, `data-description`, `data-recurring`, and `data-rrule`, and
the calendar menu script is enqueued.

Only an all-day event or one with both a start and an end time is exported;
a missing time is never guessed. When the shown date can't be exported, the
link gets `data-calendar-available="false"` and `aria-disabled="true"`
instead of event data, loses any `href`, and clicking it does nothing. A
visible `p.fair-events-calendar-unavailable` note after the link, referenced
by its `aria-describedby`, explains that both start and end times are
required. On a recurring event's
overview, `data-rrule` is only set when every date of the series can be
exported. Otherwise the button exports the next date that can be, on its
own, and `data-url` links to that date.

## Technical reference

A variation of `core/button` named `calendar-button`, registered in the editor by `src/blocks/calendar-button`. It is active when the block's attributes match `{"isCalendarButton":true}`.

| Attribute | Type | Default | Allowed values |
| --- | --- | --- | --- |
| `isCalendarButton` | boolean | `false` | — |

## Examples

### Calendar button on an event post (`examples/minimal.html`)

A Buttons block holding one calendar button. Dates, title, link, and location come from the event.

Insert into: an event post (a post with a Fair Events event date). Renders `a.wp-block-button__link[data-calendar-button='true']` when its prerequisites are met.

```html
<!-- wp:buttons -->
<div class="wp-block-buttons"><!-- wp:button {"isCalendarButton":true} -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Add to Calendar</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons -->
```