| Property | Description |
|---|---|
| largeView | string, Determines which view is displayed for screen widths greater 601px. Please refer to the fullcalendar docs linked above for an overview of applicable values. |
| smallView | string, Determines which view is displayed for screen widths smaller 601px. Please refer to the fullcalendar docs linked above for an overview of applicable values. |
| useCustomTimumCss | boolean, to increase responsiveness, timum overrides some fullcalendar css classes. Set this to false to gain total control over fullcalendar's css.
|
| Property | Description |
|---|---|
| ref | string/array, Reference of the resource to show the appointments of. Either this or tslRefs (see below) must be defined. Everything else is optional. Can also be a url parameter. You can also provide a list of string references. Booking.js will then allow your customer to choose for which resource appointments should be displayed. |
| tslRefs | string/array, Reference(s) of specific appointments. For when you only want to share a selection of a resource's appointments. Either this or refs (see above) must be defined. Everything else is optional. Can also be a url parameter. You can also provide a list of string references. Booking.js will then load all appointments and corresponding resource information. If they belong to different resources, then bookingjs allows your customer to choose for which resource appointments should be displayed. Note: If this and ref are defined in conjunction: The following behaviour is not yet set in stone and may change in the future. |
| prdRefs | string/array, Reference(s) of specific products. For when you only want your customer to choose from a subset of your otherwise fully available list of active products.
Note: If this and |
| allResourcesOption | boolean, This option determines whether the resource selection screen presents an "All" option for customers. When this flag is true, customers can choose to see and book from all available appointments across different resources in a single interface. If the customer selects the "All" option, the system displays all bookable appointments for each resource that match their selected time and product. To ensure good performance, the system will filter out duplicate appointments. For instance, if there are multiple appointments that start at the same time and offer the same service, only one of these will be shown, until booked at which point the next appointment in line will be loaded and displayed. This feature is particularly useful when it's more important for customers to secure an appointment rather than choosing a specific resource. It allows for greater flexibility and ease in booking, especially during peak times or when specific resources may be limited. |
| platform | string, A fully qualified reference (id@someUuid@platform) can be unwieldy especially if used as a url param. This prop allows you to hardcode the platform part.
Note that this prop is ignored if ref is both:
|
| prvUuid | string, A fully qualified reference (id@someUuid@platform) can be unwieldy especially if used as a url param. This prop allows you to hardcode the someUuid part. This part is only sometimes necessary to uniquely identify a resource in timum. Note that this prop is ignored if ref is both:
|
| height | string, Height of timum on your page. `500px` is standard. |
| host | string, to which server requests are send. Possible values are https://www.timum.de (production server) or https://staging.timum.de (test server) |
| allowCloseOnBooking | boolean, whether the confirmation view is closeable once the booking was successfull. |
| allowCloseOnCancel | boolean, whether the cancel view is closeable once it has been opened. If false, it only closes after previous appointment was cancelled. |
| constrainDialogsToContainer | boolean, controls where dialogs from BookingJs are rendered. When enabled, all dialogs are confined to the BookingJs' designated container and are clipped/positioned within its bounds, behaving as part of it.
When disabled, dialogs are rendered at the page level and overlay the entire site, behaving like native site modals.
Note: this setting is ignored for small screens |
| hideTimumFooter | boolean, whether 'powered by timum' can be hidden or not. Needs professional plan. |
| hiddenForAnonymous | boolean, whether bookingjs should hide itself when no customer identifying pData props can be read from the config or the url. Useful for when you only want explicitly invited customers to see the booking frontend. |
| sendCustomValuesInMessage | boolean, whether values of custom fields are concatenated and comma-separated into a single string which is then sent to the backend as message. If field message is defined its input is concatenated to the generated string as well. |
| channelKey | string, timum has, as of now, 4 different channels through which you can share your resource's appointments. You can find them in the timum frontend under <resource name> -> Calendar Sharing (Terminbuchung freigeben). Every channel has its own settings allowing you to control whom of your customers can see certain appointments, whether they book directly or create a request first and other settings. Valid values for this attribute are: - RESOURCE_PUBLIC referring to "Public Booking Link" (Öffentlicher Buchungs-Link) - RESOURCE_EXCLUSIVE referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) - RESOURCE_REFERENCE referring to "Embedded booking calendars" (Eingebettete Buchungskalender) - CALENDAR_PUBLIC referring to "In all Website Plugin Views and your General Calendar" (In Website-Plugin Ansichten sowie Ihrem Gesamtkalender) RESOURCE_PUBLIC is the default, used if you specify nothing else. Can also be a url parameter. |
| calendarFrontend | string, one of
fullCalendar, detailsFullCalendar (these are what `init`'s 3rd parameter is for),
pureListView, detailsListView,
monthView,
detailsMonthView,
condensedView,
detailsCondensedView
Note: the
|
| calendarFrontendOptions | object, Contains view-specific configuration options. Currently supports:
condensedView (object):
|
| culture | string, The localisation to use. If not specified the browser language is used. Can also be a url parameter. |
| pData | object, Data indentifying the customer, so that they don't have to input their data again. Works in conjunction with timum and select, supported plaforms like OnOffice, Immosolve etc. Properties: { platform: string, personId: string }
Can also be a url parameter. -> the params are named differently though: pDataPlatform, pDataId and pDataIdPropName which hold the name of the platform (e.g 'onoffice') the id value (e.g 27) and the name of the id property within the chosen platform: (e.g personId) Note: pData is ignored in favor of a timum auth cookie. Use incognito mode, another browser or sign out to circumvent this. |
| callbacks | object, may contain various functions which allow to to run custom code in reaction to certain events. See below for a guide on how to do this. |
| postMessageTarget |
string, URL of the parent site that receives callback events via the postMessage API. This property enables all callback events to be sent using the postMessage() method, which is particularly useful when using bookingjs within an iframe, as it restricts access to the parent site's JavaScript code.
The event.data object includes all parameters typically passed to callback functions, along with an origin field (always "bookingjs") and a type field that indicates the event's name. This type matches the name of the callback function you would use in a non-iframe scenario. Refer to the guide on callback functions for specifics on available event names.
Note: Setting this property overrides the
|
| fields | object, You can customise what information is demanded of your customers prior to booking. timum requires certain fields to work and has some optional fields it can parse. Fields other than those supported by timum can be evaluated in a callback (see the callback guide below for further info). All fields (yours too!) support localization and input validation.
Needs professional plan. |
| localization | object. Contains all localization variables and their standard texts. timum nativly supports English, German, French, Spanish and Italian. Use this to override the standard text and/or add translations for e.g your custom field labels and input validations (see the localisation guide for more info.)
Needs professional plan. |
firstName, lastName, email, and agbs. By default, timum also requests mobile and message fields, but you can add your own fields as well.
Fields, including custom ones, support validation and localization.
Validation is realized using the yup library, which is included with timum. You can import it using the following code:
```javascript
import { yup } from '@timum/booking';
```
Localization is achieved by using the title property in the field definition. You can specify a translation key and add the corresponding translation to the localization object. The same process can be applied to custom field validations.
The standard configuration can be overridden except for the aforementioned, required fields. The following is the standard configuration:
```javascript
fields: {
firstName: {
index: 0,
title: 'fields.firstName',
validation: yup.string().required('validation.field_required'), // <- compare with key in localisation
},
lastName: {
index: 1,
title: 'fields.lastName',
validation: yup.string().required('validation.field_required'),
},
email: {
index: 2,
title: 'fields.email',
format: 'email',
type: 'text',
validation: yup
.string()
.email('validation.email_field_must_be_valid')
.required('validation.field_required'),
},
mobile: {
index: 3,
title: 'fields.mobile',
type: 'phoneNumber',
isRequired: false,
defaultCountry: 'DE',
preferredCountries: ['DE', 'CH', 'AT'],
// validation: is in built and ignored
},
message: {
index: 7,
title: 'fields.message',
type: 'textarea',
validation: yup
.string()
.max(600),
limit: 600,
},
agbs: {
index: 8,
title: 'fields.accept_timum_privacy',
type: 'checkbox',
validation: yup
.boolean()
.required('validation.field_required')
.test(
'privacyAccepted',
'validation.privacy_field_required',
(value) => value === true,
),
},
locale: {
index: 9,
preventRendering: true,
},
},
```
##### Custom Fields
If the values retrieved via custom fields need to be transferred to timum backend as additional booking information, set the parameter `sendCustomValuesInMessage`. With this, the values of custom fields are attached to the customer message. They will be visible to the customer as well in booking confirmation mailings.
`sendCustomValuesInMessage: true, // necessary to transmit custom field values as part of the customer message`
Anatomy of a custom booking form field:
`
index: number, index defines the order in which the fields get displayed.
(If you want to reorder the default fields or
want to inject a custom field between them,
you must redefine them as custom fields and manually change their indexes.)
title: string or JSXElement;
validation: yup based validation. See yup docu. Re-exported and accessible via timum.yup
type: string; either 'text' (default), 'phoneNumber', 'textarea', 'checkbox' or 'select'. Depending on the chosen type additional properties are available. See below.
onChange: function, allows to execute code whenever the user changes the fields value. Gets 'value' as function parameter.
prefilled: string; value a field is initiated with.
Note that for fields of type 'select' you must use the 'key' of one of it's options.
preventRendering: boolean, default false;
if true the field is not visible to the user.
Useful in conjunction with sendCustomValuesInMessage allowing you to
enrich booked appointments with internal data
without the customer becoming aware of your internal processes.
preventRenderingFor: array, prevents rendering of the field on the set booking screens. Valid values are
'identifiedCustomers' or 'unknownCustomers', which prevents rendering on the booking
screen shown to identified/unidentified customers, respectively. If both
'identifiedCustomers' and 'unknownCustomers' are set the behaviour is equal to
preventRendering.
Note that fields hidden in this manner get their validation disabled. This
ensures that the booking doesn't fail with a validation error the end user is unable to fix.
`}`
Depending on the type there are additional properties you can/must specify:
- Type `text`:
- `format`: string; the native input field's 'type' (e.g. 'email', 'number', etc.).
- Type `phoneNumber`:
- does NOT support `validation`. Phone number validation is complex, so timum handles it for you.
This does mean that field validation localisation is currently not supported for fields of this type.
This will be fixed in a future update.
- isRequired: boolean; if true, this field must be filled with a valid number
- defaultCountry: string, denotes the country code which is preselected when first rendering the component. Default is 'DE',
- preferredCountries: list of strings; denotes which countries are displayed first in the country drop down. Defaults are ['DE', 'CH', 'AT'],
- Type `textArea`:
- limit: number; sets the maximum number of characters customers can enter. Standard is 600 characters. 1024 is maximum. But if fully used by the customer, this may lead to error in combination with sendCustomValuesInMessage. Sending any more characters to the backend leads to error.
- Type `checkbox`:
- no special properties.
- Type `select`:
- options: array of objects with structure { title: string, key: string }. The title is displayed and the key is passed in the data object to callbacks.
### Global config via `window.timumBookingConfig`
On top of the configs you pass directly to `init()` / `initialise()`, BookingJS also reads an optional global object from the host page: `window.timumBookingConfig`. This lets a page operator override BookingJS configuration without having to edit the script that initialises the widget — useful for environments where the embed code is generated by a CMS plugin or served by a backend snippet that you can't easily modify, but where you still control the surrounding HTML.
#### Cascade order
Configs are resolved in this order — later sources override earlier ones for the same key:
1. Built-in defaults from BookingJS
2. `appConfig` / `muiTheme` / `fcConfig` passed in to `init()` / `initialise()` directly
3. `window.timumBookingConfig.appConfig` / `.muiTheme` / `.fcConfig` — applied to **every** instance on the page
4. `window.timumBookingConfig[