@timum/booking 0.7.5 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,25 @@
1
1
  # timum booking
2
2
 
3
+ ## Introduction
4
+
5
+ timum BookingJs is a fully customizable appointment booking frontend app, intended to be integrated into every web page or web app or mobile app. It is ready to use out-of-the-box. And it provides the ability to customize it.
6
+ This documentation guides you through all the customization capabilities.
7
+
3
8
  ## Content
4
9
 
5
10
  - [Features](#features)
6
- - [Basic Usage](#basic_usage)
11
+ - [How to Integrate](#how_to_integrate)
7
12
  - [In a Script Tag](#in_a_script_tag)
8
13
  - [As ESM import](#as_esm_import)
9
- - [Advanced Usage](#advanced_usage)
14
+ - [Entity Referencing](#entity_referencing)
15
+ - [Channel Reference](#channel_reference)
16
+ - [Resource Reference](#resource_reference)
17
+ - [Resource Reference + `channelKey`](#channel_reference_channel_key)
18
+ - [Example](#example)
19
+ - [Customer pre-identification](#customer_pre_identification)
20
+ - [Identification via pData](#identification_via_pdata)
21
+ - [Identification via logged-in User](#identification_via_logged_in_user)
22
+ - [Advanced Customisation](#advanced_usage)
10
23
  - [muiTheme](#mui_theme)
11
24
  - [fcConfig](#fc_config)
12
25
  - [appConfig](#app_config)
@@ -25,21 +38,25 @@
25
38
 
26
39
  ## Features
27
40
 
28
- - Direct booking or appointment requests for public appointments
29
- - Approval required for requested appointments
30
- - Option to show/hide fully booked appointments
31
- - Option to prevent booking if appointment is too close to current time
32
- - Customer ability to cancel appointments with proper authentication
33
- - Customizable wording across languages
34
- - Support for multiple languages (English and German included)
35
- - Callbacks for custom code execution and event response (e.g. booking created, appointments loaded, booking canceled)
36
- - Customizable look and feel with mui theming (available with professional plan)
37
- - Dynamic definition of input fields with localized labels and validation
41
+ - Real time availability and booking
42
+ - Booking requests for public appointments - approval required
43
+ - Multiple participant appointments
44
+ - Visitor ligitimation - only invited visitors see the booking widget on public pages, listings, exposés
45
+ - Visitor identification - via customer ID from CRM
46
+ - Show/hide fully booked appointments option
47
+ - Prebooking period option - prevents booking if appointment is too soon from now
48
+ - Double booking prevention
49
+ - Cancelling appointment by customer with proper authentication
50
+ - Fully customizable look and feel with mui theming (available with premium plans)
51
+ - Customizable wording across languages (availabe with premium plans)
52
+ - Dynamic definition of input fields with localized labels and validation (available with premium plans)
38
53
  - Therefore, ability to request additional information from customers during booking process
54
+ - Support for multiple languages (English and German included) - add your own language
55
+ - Callbacks for custom code execution and event response (e.g. booking created, appointments loaded, booking canceled)
39
56
 
40
- <a name=”basic_usage”></a>
57
+ <a name=”how_to_integrate”></a>
41
58
 
42
- ## Basic Usage
59
+ ## How to Integrate
43
60
 
44
61
  <a name=”in_a_script_tag”></a>
45
62
 
@@ -50,7 +67,7 @@ Add the following code to your webpage:
50
67
  ```html
51
68
  <div id="bookingjs" style="margin: 32px"></div>
52
69
  <script type="module">
53
- import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.7.4/build/timum-booking.js';
70
+ import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.8.0/build/timum-booking.js';
54
71
 
55
72
  timum.init({ ref: 'booking-widget-demo-resource@timum' });
56
73
  </script>
@@ -65,7 +82,7 @@ Alternatively, you can add `ref` to your url as a parameter. This allows you to
65
82
  ```html
66
83
  <div id="bookingjs" style="margin: 32px"></div>
67
84
  <script type="module">
68
- import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.7.4/build/timum-booking.js';
85
+ import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.8.0/build/timum-booking.js';
69
86
 
70
87
  timum.init(); //<- no need for the reference here
71
88
  </script>
@@ -92,6 +109,83 @@ init({ ref: 'booking-widget-demo-resource@timum' });
92
109
 
93
110
  A example project can be found [here](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js)
94
111
 
112
+ <a name="entity_referencing"></a>
113
+
114
+ ### Entity Referencing
115
+
116
+ As shown in [How to Integrate](#how_to_integrate), there are two ways in which to provide bookingjs with the necessary references to retrieve public appointments from the backend.
117
+
118
+ Additionally, there are three different kinds of references you can provide, each having their own implications concerning the delivered appointments or whether the booking frontend is shown at all.
119
+
120
+ <a name="channel_reference"></a>
121
+
122
+ #### Channel Reference
123
+
124
+ Resource channels are entities in Timum, each storing a configuration that changes the booking experience for customers. Each individual resource has four channels that users can distribute to their customers through a link.
125
+ To use these channels in an embed scenario, provide a channel reference in the ref property (either in the URL or as part of the config). In this case, nothing else is required.
126
+
127
+ <a name="resource_reference"></a>
128
+
129
+ #### Resource Reference
130
+
131
+ A reference that refers to a plain resource, where the channel is unknown. The default channel (and its corresponding configuration) is used instead.
132
+
133
+ <a name="channel_reference_channel_key"></a>
134
+
135
+ #### Resource Reference + `ChannelKey`
136
+
137
+ If you don't have a channel reference but still want to use a different channel than the default one, you can provide a combination of resource reference and `channelKey` to uniquely identify the channel (and resource) to be used.
138
+
139
+ The following table gives an overview of the different permutations and how bookingjs behaves when encountering each of them:
140
+
141
+ | url RESref OR CHref | timum.init RESref OR CHref | timum.init chKey | show OR hide |
142
+ | :-----------------: | :------------------------: | :--------------: | :----------------------------: |
143
+ | - | - | ignored | **HIDE** |
144
+ | ResourceReference | ignored | YES | **show widget for channelKey** |
145
+ | ResourceReference | ignored | - | **show default Channel** |
146
+ | - | ResourceReference | - | **show default Channel** |
147
+ | - | ResourceReference | YES | **show widget for channelKey** |
148
+ | ChannelReference | ignored | ignored | **show Channel** |
149
+ | - | ChannelReference | ignored | **show Channel** |
150
+
151
+ - RESref: short for resource reference.
152
+ - CHref: short for channel reference.
153
+
154
+ <a name="example"></a>
155
+
156
+ ##### Example
157
+
158
+ - First row: If neither a resource reference nor a channel reference is provided, not in the URL nor in the config object, any given channel key is ignored, and bookingjs is hidden.
159
+
160
+ - Third row: If a resource reference is given in the URL and in the config object, and no channelKey is provided, the ref in the URL takes priority. Since it is a resource reference and no channel key is provided, the default channel is used.
161
+
162
+ - Fifth row: If a resource reference and a `channelKey` are provided in the config object, and there is nothing in the URL, the config object is used. BookingJs gets displayed using the channel uniquely identified by the resource reference and the `channelKey`.
163
+
164
+ <a name="customer_pre_identification"></a>
165
+
166
+ #### Customer pre-identification
167
+
168
+ BookingJs can identify customers automatically if configured correctly.
169
+ This means they don't need to input their personal data prior to booking.
170
+
171
+ <a name="identification_via_pdata"></a>
172
+
173
+ ##### Identification via pDataId (personId)
174
+
175
+ Detection method: Is there a valid pDataId paired with a supported pDataPlatform (platform) in parent url matching an entity (contact, customer) in given CRM?
176
+ <em>
177
+ General behaviour: If there is, then visitor is pre identified. If not: provide standard booking dialog.
178
+ </em>
179
+ See [appConfig](#appconfig) for more information about pData.
180
+
181
+ <a name="identification_via_logged_in_user"></a>
182
+
183
+ ##### Identification via Logged-in User
184
+
185
+ Even customers can register at timum and become registered and logged-in users. If the booking system identifies a logged-in user, the booking dialog does not provide personal data input fields but informs the visitor that they are identified.
186
+
187
+ > Note that if the customer is logged in to timum and there is a pData config/url param as well then the auth cookie takes priority.
188
+
95
189
  ---
96
190
 
97
191
  <a name=”advanced_usage”></a>
@@ -118,6 +212,8 @@ See [here](https://mui.com/) for a general overview. <br> See [here](https://mui
118
212
 
119
213
  When you open the file `config.js` in [this](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js) example, you can find an elaborate custom configuration which includes a redesign of the standard timum theme.
120
214
 
215
+ Needs premium plan.
216
+
121
217
  <a name=”fc_config”></a>
122
218
 
123
219
  ### fcConfig
@@ -134,53 +230,72 @@ See [here](https://fullcalendar.io/docs#toc) for a full list of configuration op
134
230
  This object's options directly affect timum's behaviour or allow you to react to it.
135
231
 
136
232
  <table>
137
- <tr>
138
- <th>Property</th>
139
- <th>Description</th>
140
- </tr>
141
- <tr>
142
- <td>ref</td>
143
- <td>string, Reference of the resource to show the appointments of. <br><em> This is the only prop that is mandatory.</em><br> Everything else is optional. <br>Can also be a url parameter.
144
- </td>
145
- </tr>
146
- <tr>
147
- <td>height</td>
148
- <td> string, Height of timum on your page. `500px` is standard.</td>
149
- </tr>
150
- <tr>
151
- <td>channelKey</td>
152
- <td>string, timum has, as of now, 4 different channels through which you can share your resource's appointments. <br> You can find them in the timum frontend under &lt;resource name&gt; -&gt; Calendar Sharing (Terminbuchung freigeben). <br> 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. <br> Valid values for this attribute are: <br>
153
- - RESOURCE_PUBLIC <br> referring to "Public Booking Link" (Öffentlicher Buchungs-Link) <br>
154
- - RESOURCE_EXCLUSIVE <br> referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) <br>
155
- - RESOURCE_REFERENCE <br> referring to "Embedded booking calendars" (Eingebettete Buchungskalender) <br>
156
- - CALENDAR_PUBLIC <br> referring to "In all Website Plugin Views and your General Calendar" (In Website-Plugin Ansichten sowie Ihrem Gesamtkalender) <br>RESOURCE_PUBLIC is the default, used if you specify nothing else. <br><br>Can also be a url parameter. </td>
157
- </tr>
158
- <tr>
159
- <td>calendarFrontend</td>
160
- <td>string, one of `fullCalendar` (that's what `init`'s 3rd parameter is for), `pureListView` or `detailsListView`</td>
161
- </tr>
162
- <tr>
163
- <td>culture</td>
164
- <td>string, The localisation to use. If not specified the browser language is used. Can also be a url parameter.</td>
165
- </tr>
166
- <tr>
167
- <td>pData</td>
168
- <td>object, <br> Data indentifying the customer, so that they don't have to input their data again. <br> Works in conjunction with timum and select, supported plaforms like OnOffice, Immosolve etc. <br> Properties: <br>
169
- <code>{ platform: string, personId: string }</code>
170
- <br> Can also be a url parameter. -&gt; the params are named differently though: pDataPlatform, pDataId</td>
171
- </tr>
172
- <tr>
173
- <td>callbacks</td>
174
- <td>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. </td>
175
- </tr>
176
- <tr>
177
- <td>fields</td>
178
- <td>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. </td>
179
- </tr>
180
- <tr>
181
- <td>localization</td>
182
- <td>object. Contains all localization variables and their standard texts. timum nativly supports English and German. Use this to override the standard text and/or add translations for your custom field labels and input validations (see the localisation guide for mor info.)</td>
183
- </tr>
233
+ <tr>
234
+ <th>Property</th>
235
+ <th>Description</th>
236
+ </tr>
237
+ <tr>
238
+ <td>ref</td>
239
+ <td>string, Reference of the resource to show the appointments of. <br><em> This is the only prop that is mandatory.</em><br> Everything else is optional. <br>Can also be a url parameter.</td>
240
+ </tr>
241
+ <tr>
242
+ <td>height</td>
243
+ <td> string, Height of timum on your page. `500px` is standard.</td>
244
+ </tr>
245
+ <tr>
246
+ <td>allowCloseOnBooking</td>
247
+ <td>boolean, whether the confirmation view is closeable once the booking was successfull.</td>
248
+ </tr>
249
+ <tr>
250
+ <td>hideTimumFooter</td>
251
+ <td>boolean, whether 'powered by timum' can be hidden or not. Needs premium plan.</td>
252
+ </tr>
253
+ <tr>
254
+ <td>channelKey</td>
255
+ <td>string, timum has, as of now, 4 different channels through which you can share your resource's appointments. <br> You can find them in the timum frontend under &lt;resource name&gt; -&gt; Calendar Sharing (Terminbuchung freigeben). <br> 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. <br> Valid values for this attribute are: <br>
256
+ - RESOURCE_PUBLIC <br> referring to "Public Booking Link" (Öffentlicher Buchungs-Link) <br>
257
+ - RESOURCE_EXCLUSIVE <br> referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) <br>
258
+ - RESOURCE_REFERENCE <br> referring to "Embedded booking calendars" (Eingebettete Buchungskalender) <br>
259
+ - CALENDAR_PUBLIC <br> referring to "In all Website Plugin Views and your General Calendar" (In Website-Plugin Ansichten sowie Ihrem Gesamtkalender) <br>RESOURCE_PUBLIC is the default, used if you specify nothing else. <br><br>Can also be a url parameter.
260
+ </td>
261
+ </tr>
262
+ <tr>
263
+ <td>calendarFrontend</td>
264
+ <td>string, one of <code>fullCalendar</code> (that's what `init`'s 3rd parameter is for), <code>pureListView</code> or <code>detailsListView</code></td>
265
+ </tr>
266
+ <tr>
267
+ <td>culture</td>
268
+ <td>string, The localisation to use. If not specified the browser language is used. Can also be a url parameter.</td>
269
+ </tr>
270
+ <tr>
271
+ <td>pData</td>
272
+ <td>object, <br> Data indentifying the customer, so that they don't have to input their data again. <br> Works in conjunction with timum and select, supported plaforms like OnOffice, Immosolve etc. <br> Properties: <br>
273
+ <code>{ platform: string, personId: string }</code>
274
+ <br> Can also be a url parameter. -&gt; the params are named differently though: pDataPlatform, pDataId
275
+ <blockquote>
276
+ Note: pData is ignored in favor of a timum auth cookie.
277
+ Use incognito mode, another browser or sign out to circumvent this.
278
+ </blockquote>
279
+ </td>
280
+ </tr>
281
+ <tr>
282
+ <td>callbacks</td>
283
+ <td>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. </td>
284
+ </tr>
285
+ <tr>
286
+ <td>fields</td>
287
+ <td>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.
288
+ <br>
289
+ Needs premium plan.
290
+ </td>
291
+ </tr>
292
+ <tr>
293
+ <td>localization</td>
294
+ <td>object. Contains all localization variables and their standard texts. timum nativly supports English and German. Use this to override the standard text and/or add translations for your custom field labels and input validations (see the localisation guide for mor info.)
295
+ <br>
296
+ Needs premium plan.
297
+ </td>
298
+ </tr>
184
299
  </table>
185
300
 
186
301
  <a name=”how_to_use_callbacks”></a>
@@ -269,7 +384,9 @@ In order to display public appointments, resource and calendar information timum
269
384
  provider: {
270
385
  name: 'string',
271
386
  description: 'string',
272
- isBrandingAllowed: 'boolean',
387
+ isThemingAllowed: 'boolean',
388
+ isLocalisationAllowed: 'boolean',
389
+ areCustomFieldsAllowed: 'boolean'
273
390
  },
274
391
  channel: {
275
392
  bookingProcess: 'string' // One of 'IMMEDIATE' or 'REQUESTED',
@@ -372,7 +489,7 @@ localization: {
372
489
  'Sie müssen die Datenschutzbestimmungen akzeptieren bevor Sie buchen können.',
373
490
  email_field_must_be_valid: 'Geben Sie eine valide E-Mail Adresse ein',
374
491
  },
375
- fields: {
492
+ fields: { // field labels are markdown capable. That's why you can use basic html as well.
376
493
  firstName: 'Vorname',
377
494
  lastName: 'Nachname',
378
495
  name: 'Name',
@@ -380,7 +497,8 @@ localization: {
380
497
  mobile: 'Mobil',
381
498
  message: 'Ihre Nachricht',
382
499
  accept_timum_privacy:
383
- 'Datenschutzbestimmungen gelesen und akzeptiert',
500
+ '<a href="https://info.timum.de/datenschutz" target="_blank">Datenschutzbestimmungen</a> gelesen und akzeptiert',
501
+
384
502
  },
385
503
  },
386
504
  // the same for english.
@@ -422,14 +540,16 @@ localization: {
422
540
  'You must accept the privacy policy prior to booking.',
423
541
  email_field_must_be_valid: 'Enter a valid email address',
424
542
  },
425
- fields: {
543
+ fields: { // field labels are markdown capable. That's why you can use basic html as well.
426
544
  firstName: 'First name',
427
545
  lastName: 'Last name',
428
546
  name: 'name',
429
547
  email: 'E-mail',
430
548
  mobile: 'Mobile',
431
549
  message: 'Your Message',
432
- accept_timum_privacy: '<0>Privacy policy</0> read and accepted.',
550
+ accept_timum_privacy:
551
+ '<a href="https://info.timum.de/datenschutz" target="_blank">Privacy policy</a> read and accepted.',
552
+
433
553
  },
434
554
  },
435
555
  },
@@ -439,7 +559,7 @@ localization: {
439
559
 
440
560
  #### How to define fields
441
561
 
442
- You can customize the information required from customers before booking by defining fields. The minimum required fields for timum are firstName, lastName, email, and agbs. By default, timum also requests mobile and message fields, but you can add your own fields as well.
562
+ You can customize the information you request from customers before booking by defining fields. The minimum required fields for timum are firstName, lastName, email, and agbs. By default, timum also requests mobile and message fields, but you can add your own fields as well.
443
563
 
444
564
  Fields, including custom ones, support validation and localization.
445
565
  Validation is realized using the yup library, which is included with timum. You can import it using the following code:
@@ -539,16 +659,14 @@ Type `select`:
539
659
 
540
660
  ### An Example
541
661
 
542
- Here is an example Tying all of the aforementioned concepts together.
662
+ Here is an example tying all of the aforementioned concepts together.
663
+ And [here](https://jsfiddle.net/timum/wov6pLk7/) is a fiddle containing the very example detailed in this chapter.
543
664
 
544
665
  <a name=”the_scenario”></a>
545
666
 
546
667
  #### The Scenario
547
668
 
548
- For whatever reason it is important to know the gender of customers.
549
- On the other side the optional fields `mobile` and `message` aren't important for you and you wish to remove them.
550
- This new gender field must be filled, therefore a validation is required.
551
- Both the title of the field and it's validations must be localized.
669
+ It is necessary to determine the gender of customers for a specific purpose. The `mobile` and `message` fields are not necessary and will be removed. The new `gender` field must be filled, therefore a validation check is required to ensure it is completed. Both the name of the `gender` field and the validation messages must be translated into different languages.
552
670
 
553
671
  <a name=”the_implementation”></a>
554
672
 
@@ -559,7 +677,7 @@ This is the base configuration. As it is it uses the standard field configuratio
559
677
  ```html
560
678
  <div id="bookingjs" style="margin: 32px"></div>
561
679
  <script type="module">
562
- import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.7.4/build/timum-booking.js';
680
+ import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.8.0/build/timum-booking.js';
563
681
 
564
682
  timum.init({ ref: 'booking-widget-demo-resource@timum' });
565
683
  </script>
@@ -570,7 +688,7 @@ Let's add the necessary changes:
570
688
  ```html
571
689
  <div id="bookingjs" style="margin: 32px"></div>
572
690
  <script type="module">
573
- import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.7.4/build/timum-booking.js';
691
+ import * as timum from 'https://cdn.jsdelivr.net/npm/@timum/booking@0.8.0/build/timum-booking.js';
574
692
 
575
693
  timum.init(
576
694
  {
@@ -1,4 +1,4 @@
1
- import { b as a, B as e, g as l } from "./index-e0658644.js";
1
+ import { b as a, B as e, g as l } from "./index-f01854a3.js";
2
2
  export {
3
3
  a as buttonClasses,
4
4
  e as default,
@@ -1,4 +1,4 @@
1
- import { D as e, F as l, E as t } from "./index-e0658644.js";
1
+ import { D as e, F as l, E as t } from "./index-f01854a3.js";
2
2
  export {
3
3
  e as default,
4
4
  l as getTableRowUtilityClass,
@@ -1,4 +1,4 @@
1
- import { k as e, n as l, m as t } from "./index-e0658644.js";
1
+ import { k as e, n as l, m as t } from "./index-f01854a3.js";
2
2
  export {
3
3
  e as default,
4
4
  l as getTableBodyUtilityClass,
@@ -1,4 +1,4 @@
1
- import { h as e, j as l, i as t } from "./index-e0658644.js";
1
+ import { h as e, j as l, i as t } from "./index-f01854a3.js";
2
2
  export {
3
3
  e as default,
4
4
  l as getTableUtilityClass,
@@ -1,4 +1,4 @@
1
- import { L as l, a as t, l as e } from "./index-e0658644.js";
1
+ import { L as l, a as t, l as e } from "./index-f01854a3.js";
2
2
  export {
3
3
  l as default,
4
4
  t as getLinkUtilityClass,
@@ -1,4 +1,4 @@
1
- import { c as e, e as a, d as l } from "./index-e0658644.js";
1
+ import { c as e, e as a, d as l } from "./index-f01854a3.js";
2
2
  export {
3
3
  e as default,
4
4
  a as getListItemTextUtilityClass,
@@ -1,4 +1,4 @@
1
- import { r as b, s as f, u as m, v as F, w as d, _ as C, x as l, y as n, z as T, A as v, C as x } from "./index-e0658644.js";
1
+ import { r as b, s as f, u as m, v as F, w as d, _ as C, x as l, y as n, z as T, A as v, C as x } from "./index-f01854a3.js";
2
2
  function y(o) {
3
3
  return b("MuiTableFooter", o);
4
4
  }
@@ -1,4 +1,4 @@
1
- import { o as e, q as s, p as t } from "./index-e0658644.js";
1
+ import { o as e, q as s, p as t } from "./index-f01854a3.js";
2
2
  export {
3
3
  e as default,
4
4
  s as getTableCellUtilityClass,
@@ -1,4 +1,4 @@
1
- import { r as p, s as b, u as m, v as H, w as C, _ as T, x as r, y as n, z as f, A as h, C as v } from "./index-e0658644.js";
1
+ import { r as p, s as b, u as m, v as H, w as C, _ as T, x as r, y as n, z as f, A as h, C as v } from "./index-f01854a3.js";
2
2
  function x(e) {
3
3
  return p("MuiTableHead", e);
4
4
  }