# Calendar data sources

A calendar data source can be used to generate a calendar or to group data in other data sources, such as all the transactions in a month. This type of data source contains objects based on time periods between two dates. For example, 12 objects for all of the months in a year or 168 objects for all of the hours in a week.

Calendar data sources are generated at runtime. The feature specific set of [object properties](#data-source-object-properties) to extract date information from each time period object. The values in these properties reflect the calendar locale for the active language as specified under [Internationalization](/reference/resources/internationalization.md).

## Usage

To add a calendar data source to an app:

* Open the app and navigate to **Data**.
* In the **App Data panel**, click the down arrow icon.
* Select **Add Calendar Data Source**.

To configure the data source you must specify a **From** datetime value, a **To** datetime value, and select a **Resolution**. The from and to dates specify the boundaries of the calendar. The resolution is the time periods that the data source will be broken into and each time period will be represented by an object. 

For general information about working with dates, see [Date and time](/reference/platform-concepts/date-and-time.md).

<details>

<summary>Example: Yearly calendar of transactions</summary>

You have a data source `Transactions` with a property `Transaction Date`. You want to create a view where you can navigate between years and see all transactions for that year.

First, you should create a [Custom app variable](/reference/apps/data/app-variables.md#custom-app-variables) called `Active year` with data type Datetime. The **Value on Create** can be `Date Now`.

Then, add a calendar data source called `Monthly Calendar` and set the following properties:

* **From**: `Active year` (data bound to the app variable you just created), with a [Value processor](/reference/platform-concepts/value-processor.md) operation `Go to start of year`.&#x20;
* **To**: `Active year`, with a Value processor operation `Go to end of year`.
* **Resolution**: `Month`

When the app is loaded the calendar data source will generate 12 objects, one for each month of the active year. In your UI, you can use iterating containers to loop through each `Monthly Calendar`. Inside that iteration, you can use another set of iterating containers to loop through `Transactions` with a [filter](/reference/platform-concepts/filters.md) expression `Transaction Date >= Monthly Calendar.DateTime Value AND Transaction Date <= Monthly Calendar.Period End`. This will filter the data to all transactions in the given month and you can display them.

To navigate between years, you would need to add a UI element that triggers an update to the `Active year` variable. The calendar data source will refresh automatically. Note that you should also have in a filter on the `Transactions` data source to only read in transactions for the active year.

</details>

<details>

<summary>Example: Hourly calendar for appointments</summary>

You want to create a visual interface for scheduling appointments in one hour blocks for the current week.

Add a calendar data source and set the following properties:

* **From**: `Date Now`, with a [Value processor](/reference/platform-concepts/value-processor.md) operation `Go to start of week (mo-su)`.
* **To**: `Date Now`, with a Value processor operation `Go to end of week (mo-su)`.
* **Resolution**: `Hour`

When the app is loaded the calendar data source will generate 168 objects, one for each hour of the week. In your UI, you can use iterating containers to visualise the weekly calendar and show an appointment for a given block.

</details>

{% hint style="info" %}
A calendar data source example is available in our [Showroom.](https://showroom-dev.appfarm.app/use-cases/calendar) You can view a demo, as well as access the setup in Appfarm Create. Don't have access? [Register](https://showroom.appfarm.app/sign-up).
{% endhint %}

## General properties

<table><thead><tr><th width="207">Property</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>A descriptive name for the data source.</td></tr><tr><td><strong>Object Class</strong></td><td><em>Read only</em><br>Always <code>Calendar</code>.</td></tr><tr><td><strong>Cardinality</strong></td><td><em>Read only</em><br>Always <code>Many</code>.</td></tr><tr><td><strong>From</strong></td><td>The start date of the calendar.</td></tr><tr><td><strong>To</strong></td><td>The end date of the calendar.</td></tr><tr><td><strong>Resolution</strong></td><td><p>The time periods the calendar should be split into. The options are:</p><ul><li><code>Year</code></li><li><code>Quarter</code></li><li><code>Month</code></li><li><code>Week</code></li><li><code>Day</code></li><li><code>Hour</code></li></ul></td></tr><tr><td><strong>Description</strong></td><td>A longer description of the data source. For your own reference.</td></tr></tbody></table>

## Runtime properties

Runtime properties for calendars function in the same way as for [object class data sources](/reference/apps/data/data-sources.md#runtime-properties).

## Data source object properties

**Data source object properties** are built-in properties available for each [object](/reference/platform-concepts/objects.md) in the data source. Each time period is represented by an object. The values reflect the calendar locale for the active language as specified under [Internationalization](/reference/resources/internationalization.md#calendar-locale).&#x20;

<table><thead><tr><th width="236">Property</th><th width="132.33333333333331">Data type</th><th>Description</th></tr></thead><tbody><tr><td><strong>DateTime Value</strong></td><td>Datetime</td><td>The start of the time period.</td></tr><tr><td><strong>Day</strong></td><td>String</td><td>The day of the week of <strong>DateTime Value</strong>.</td></tr><tr><td><strong>Day of Month (1–31)</strong></td><td>Integer</td><td>The day of the month of <strong>DateTime Value</strong>.</td></tr><tr><td><strong>Day of Week (ISO, 1–7)</strong></td><td>Integer</td><td>The day of the week of <strong>DateTime Value</strong>, in accordance with the <a href="https://en.wikipedia.org/wiki/ISO_week_date">ISO 8601 standard</a>. 1 = Monday and 7 = Sunday.</td></tr><tr><td><strong>Hour (0-23)</strong></td><td>Integer</td><td>The hour, using the 24-hour clock, of <strong>DateTime Value</strong>. This will always be <code>0</code> except when <strong>Resolution</strong> is <code>Hour</code>.</td></tr><tr><td><strong>Is Not Selected</strong></td><td>Boolean</td><td>The object is not <a href="/pages/-MiR92uc7YpwXZWPxMI1#object-selection">selected</a>.</td></tr><tr><td><strong>Is Selected</strong></td><td>Boolean</td><td>The object is <a href="/pages/-MiR92uc7YpwXZWPxMI1#object-selection">selected</a>.</td></tr><tr><td><strong>Month (1–12)</strong></td><td>Integer</td><td>The month number of <strong>DateTime Value</strong>.</td></tr><tr><td><strong>Month Name</strong></td><td>String</td><td>The month name of <strong>DateTime Value</strong>.</td></tr><tr><td><strong>Period End</strong></td><td>Datetime</td><td>The end of the time period.</td></tr><tr><td><strong>Week Number (ISO)</strong></td><td>Integer</td><td>The week number of <strong>DateTime Value</strong>, in accordance with the <a href="https://en.wikipedia.org/wiki/ISO_week_date">ISO 8601 standard</a>.</td></tr><tr><td><strong>Year</strong></td><td>Integer</td><td>The four-digit year of <strong>DateTime Value</strong>.</td></tr></tbody></table>

## Data source attributes

Data source attributes for calendars are the same as for [object class data sources](/reference/apps/data/data-sources.md#data-source-attributes) except that **Disabled**, **Limit**, **Skip**, **Subscribe To Updates**, and **Total Object Count** are not available.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appfarm.io/reference/apps/data/calendar-data-sources.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.