Calendar

<bk-calendar></bk-calendar>

The Calendar is designed to manage a dataset that represents appointments.

Each entry of the dataset should include the following three fields:

• startDate: represents the start date of the appointment
• endDate: represents the end date of the appointment
• title: represents the title of the appointment

At mounting time, the Calendar parses the URL for parameters date and view, which uses to initialize its state. If not present, the Calendar initializes its state to default values.

Interaction with the Calendar is possible:

• clicking an appointment triggers the request to allow editing of the associated data item. To do so, the Calendar emits a selected-data event
• clicking on an empty time-slot triggers the request to allow creation of the associated data item. To do so, the Calendar emits an add-new event
• drag-n-drop of appointments is possible. Dropping an appointment to a new slot notifies that fields startDate and endDate of the associated item should be edited. To do so, the Calendar emits an update-data event
• changing the current view or the displayed time span triggers a request to change data retrieval, adding filters that enable the visualization of data items that are relevant to the newly selected time span. To do so, the Calendar emits add-filter event.

How to configure

The Calendar does not require any particular configuration for its basic usage:

{
  "tag": "bk-calendar"
}

View

Property view allows to configure the default view of the Calendar.

Three types of view are supported:

• day
• week
• month

If not specified, month view is used.

Rename date filters

Changing the current view or the displayed time span triggers a request to change data retrieval, adding filters that enable the visualization of data items that are relevant to the newly selected time span.

Modifying the current view or adjusting the displayed time span initiates a request to modify data retrieval. This process involves requesting to add filters that allow the visualization of data items whose startDate and endDate fall within the selected time frame.

Property filtersName allows to specify a label to be applied to such filters, as shows in the following example. Default filters names are:

• bk-calendar-start-date-filter
• bk-calendar-end-date-filter

{
  "name": ..., // value of property `filtersName.start`, or "bk-calendar-start-date-filter"
  "operator": "lessEqual",
  "property": "startDate",
  "value": "2021-09-20T00:00:00.000Z"
},
{
  "name": ..., // value of property `filtersName.end`, or "bk-calendar-end-date-filter"
  "operator": "greaterEqual",
  "property": "endDate",
  "value": "2021-09-13T00:00:00.000Z"
}

Hide date filters (with Filters Manager)

The Calendar requires a component like the Filters Manager to be included in the page, as it makes use of the add-filter event for data filtering.

Filters on startDate and endDate properties can be hidden by the Filters Manager leveraging filters-options in the data-schema of the Filters Manager, as shows in the relative example.

Additional creation data

Property additionalCreatePayload allows to specify extra data that should be added to the request that the Calendar emits when clicking on an empty time-slot.

Dynamic configurations are available in additionalCreatePayload configuration, providing access via handlebars to:

• the information of the currently logged user, via currentUser
• information about the pathname of the current URL, via pathnameParams.\ pathnameParams.params includes the result of the match between the urlMask property and the pathname of the URL, while pathnameParams.path holds the full pathname. This requires property urlMask to be defined.
• information about the query parameters of the current URL, via searchParams.\ searchParams.params includes the result of the match between the urlMask property and the query of the URL, while searchParams.path holds the full query as a string. This requires property urlMask to be defined.

This is shown in the examples Additional Creation Data and Additional Creation Data With Info From Url.

Locale

The texts of the Calendar can be customized through the property customLocale, which accepts an object shaped like the following:

type Locale = {
  date: LocalizedText
  time: LocalizedText
  event: LocalizedText
  allDay: LocalizedText
  week: LocalizedText
  work_week: LocalizedText
  day: LocalizedText
  month: LocalizedText
  previous: LocalizedText
  next: LocalizedText
  yesterday: LocalizedText
  tomorrow: LocalizedText
  today: LocalizedText
  agenda: LocalizedText
  noEventsInRange: LocalizedText
  showMore: LocalizedText
}

where LocalizedText is either a string or an object mapping language acronyms to strings.

Examples

Example: Hide date filters with Filters Manager

The Calendar requires a component like the Filters Manager to be included in the page, as it makes use of the add-filter event for data filtering. Filters on startDate and endDate properties can be hidden by the Filters Manager leveraging filters-options in the data-schema of the Filters Manager.

{
  "tag": "bk-calendar"
},
{
  "tag": "bk-filters-manager",
  "properties": {
    "dataSchema": {
      "title": {"type": "string"},
      "startDate": {
        "type": "string",
        "format": "data-time",
        "filtersOptions": {
          "hidden": true
        }
      },
      "endDate": {
        "type": "string",
        "format": "data-time",
        "filtersOptions": {
          "hidden": true
        }
      }
    }
  }
}

Example: Rename date filters

Property filtersName allows to specify a label to be applied to the emitted filters that request the visualization of data items that fall in the calendar current time-span.

A Calendar with a configuration like:

{
  "tag": "bk-calendar",
  "properties": {
    "filtersName": {
      "start": "Start filter",
      "end": "End filter"
    },
  }
}

emits add-filter events with payload:

{
  "name": "Start filter",
  "operator": "lessEqual",
  "property": "startDate",
  "value": "2021-09-20T00:00:00.000Z"
},
{
  "name": "End filter",
  "operator": "greaterEqual",
  "property": "endDate",
  "value": "2021-09-13T00:00:00.000Z"
}

where the value keys are set based on the visualized date and the selected view.

Example: Additional creation data

Property additionalCreatePayload allows to specify a extra data to be included in the request to create a new data element that the Calendar sends whenever an empty time-slot is clicked.

Assuming the current user information to be representable with an object like:

{
  "role": "Admin",
  "name": "Steven",
  "email": "steven@test.com"
}

a Calendar configured like:

{
  "tag": "bk-calendar",
  "properties": {
    "additionalCreatePayload": {
      "price": 120,
      "email": "{{currentUser.email}}"
    }
  }
}

emits add-new events with payload:

{
  "email": "steven@test.com",
  "price": 120
}

Example: Additional creation data with info from URL

Property additionalCreatePayload allows to specify a extra data to be included in the request to create a new data element that the Calendar sends whenever an empty time-slot is clicked. Property urlMask provides the possibility to use data extraced from the URL in the configuration of additionalCreatePayload.

With a URL having pathname:

/orders/id-1

a Calendar configured like:

{
  "tag": "bk-calendar",
  "properties": {
    "urlMask": "/orders/:id",
    "additionalCreatePayload": {
      "userId": "{{pathnameParams.params.id}}"
    }
  }
}

emits add-new events with payload:

{
  "userId": "id-1"
}

API

Properties & Attributes

property	attribute	type	default	description
additionalCreatePayload	-	{[x: string]: any}	{}	extra data to be passed in the payload of add-new events
date	-	Date	new Date()	current date of the calendar
height	height	string	-	css-height of the calendar
view	-	"agenda" | "day" | "month" | "week"	'month'	current view of the calendar
filtersName	-	FiltersName	{start:"bk-calendar-start-date-filter",end:"bk-calendar-end-date-filter"}	names of date filters
urlMask	url-mask	UrlMask	-	url mask to apply to the current path to extract dynamic parameters

FiltersName

type FiltersName = {
  start?: LocalizedText
  end?: LocalizedText
}

where LocalizedText is either a string or an object mapping language acronyms to strings.

Listens to

event	action
loading-data	sets internal loading state
display-data	receives data to display

Emits

event	description
add-filter	requests data to be filtered to only show items that fall in currently visualized span of time
add-new	triggers the creation of a new event with the selected start and end
selected-data	notifies about the click on an event
update-data	triggers the update of the start and end of an event