@timum/booking 0.8.1 → 0.8.2

package/README.md

@@ -1,12 +1,25 @@
 # timum booking
 
+## Introduction
+
+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.
+This documentation guides you through all the customization capabilities.
+
 ## Content
 
 - [Features](#features)
-- [Basic Usage](#basic_usage)
+- [How to Integrate](#how_to_integrate)
   - [In a Script Tag](#in_a_script_tag)
   - [As ESM import](#as_esm_import)
-- [Advanced Usage](#advanced_usage)
+  - [Entity Referencing](#entity_referencing)
+    - [Channel Reference](#channel_reference)
+    - [Resource Reference](#resource_reference)
+    - [Resource Reference + `channelKey`](#channel_reference_channel_key)
+      - [Example](#example)
+    - [Customer pre-identification](#customer_pre_identification)
+      - [Identification via pData](#identification_via_pdata)
+      - [Identification via logged-in User](#identification_via_logged_in_user)
+- [Advanced Customisation](#advanced_usage)
   - [muiTheme](#mui_theme)
   - [fcConfig](#fc_config)
   - [appConfig](#app_config)
@@ -23,11 +36,6 @@
 
 <a name=”features”></a>
 
-## Introduction
-
-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.
-This documentation guides you through all the customization capabilities.
-
 ## Features
 
 - Real time availability and booking
@@ -46,9 +54,9 @@ This documentation guides you through all the customization capabilities.
 - Support for multiple languages (English and German included) - add your own language
 - Callbacks for custom code execution and event response (e.g. booking created, appointments loaded, booking canceled)
 
-<a name=”basic_usage”></a>
+<a name=”how_to_integrate”></a>
 
-## Basic Usage
+## How to Integrate
 
 <a name=”in_a_script_tag”></a>
 
@@ -101,6 +109,83 @@ init({ ref: 'booking-widget-demo-resource@timum' });
 
 A example project can be found [here](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js)
 
+<a name="entity_referencing"></a>
+
+### Entity Referencing
+
+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.
+
+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.
+
+<a name="channel_reference"></a>
+
+#### Channel Reference
+
+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.
+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.
+
+<a name="resource_reference"></a>
+
+#### Resource Reference
+
+A reference that refers to a plain resource, where the channel is unknown. The default channel (and its corresponding configuration) is used instead.
+
+<a name="channel_reference_channel_key"></a>
+
+#### Resource Reference + `ChannelKey`
+
+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.
+
+The following table gives an overview of the different permutations and how bookingjs behaves when encountering each of them:
+
+| url RESref OR CHref | timum.init RESref OR CHref | timum.init chKey |          show OR hide          |
+| :-----------------: | :------------------------: | :--------------: | :----------------------------: |
+|          -          |             -              |     ignored      |            **HIDE**            |
+|  ResourceReference  |          ignored           |       YES        | **show widget for channelKey** |
+|  ResourceReference  |          ignored           |        -         |    **show default Channel**    |
+|          -          |     ResourceReference      |        -         |    **show default Channel**    |
+|          -          |     ResourceReference      |       YES        | **show widget for channelKey** |
+|  ChannelReference   |          ignored           |     ignored      |        **show Channel**        |
+|          -          |      ChannelReference      |     ignored      |        **show Channel**        |
+
+- RESref: short for resource reference.
+- CHref: short for channel reference.
+
+<a name="example"></a>
+
+##### Example
+
+- 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.
+
+- 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.
+
+- 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`.
+
+<a name="customer_pre_identification"></a>
+
+#### Customer pre-identification
+
+BookingJs can identify customers automatically if configured correctly.
+This means they don't need to input their personal data prior to booking.
+
+<a name="identification_via_pdata"></a>
+
+##### Identification via pDataId (personId)
+
+Detection method: Is there a valid pDataId paired with a supported pDataPlatform (platform) in parent url matching an entity (contact, customer) in given CRM?
+<em>
+General behaviour: If there is, then visitor is pre identified. If not: provide standard booking dialog.
+</em>
+See [appConfig](#appconfig) for more information about pData.
+
+<a name="identification_via_logged_in_user"></a>
+
+##### Identification via Logged-in User
+
+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.
+
+> 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.
+
 ---
 
 <a name=”advanced_usage”></a>
@@ -127,6 +212,8 @@ See [here](https://mui.com/) for a general overview. <br> See [here](https://mui
 
 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.
 
+Needs premium plan.
+
 <a name=”fc_config”></a>
 
 ### fcConfig
@@ -143,53 +230,72 @@ See [here](https://fullcalendar.io/docs#toc) for a full list of configuration op
 This object's options directly affect timum's behaviour or allow you to react to it.
 
 <table>
-<tr>
-<th>Property</th>
-<th>Description</th>
-</tr>
-<tr>
-<td>ref</td>
-<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>
-</tr>
-<tr>
-<td>height</td>
-<td>  string, Height of timum on your page. `500px` is standard.</td>
-</tr>
-<tr>
-<td>channelKey</td>
-<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> 
-- RESOURCE_PUBLIC <br> referring to "Public Booking Link" (Öffentlicher Buchungs-Link) <br> 
-- RESOURCE_EXCLUSIVE <br> referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) <br> 
-- RESOURCE_REFERENCE <br> referring to "Embedded booking calendars" (Eingebettete Buchungskalender) <br>
-- 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>
-</tr>
-<tr>
-<td>calendarFrontend</td>
-<td>string, one of `fullCalendar` (that's what `init`'s 3rd parameter is for), `pureListView` or `detailsListView`</td>
-</tr>
-<tr>
-<td>culture</td>
-<td>string, The localisation to use. If not specified the browser language is used. Can also be a url parameter.</td>
-</tr>
-<tr>
-<td>pData</td>
-<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> 
-<code>{ platform: string, personId: string }</code> 
-<br> Can also be a url parameter. -&gt; the params are named differently though: pDataPlatform, pDataId</td>
-</tr>
-<tr>
-<td>callbacks</td>
-<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>
-</tr>
-<tr>
-<td>fields</td>
-<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>
-</tr>
-<tr>
-<td>localization</td>
-<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>
-</tr>
+   <tr>
+      <th>Property</th>
+      <th>Description</th>
+   </tr>
+   <tr>
+      <td>ref</td>
+      <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>
+   </tr>
+   <tr>
+      <td>height</td>
+      <td>  string, Height of timum on your page. `500px` is standard.</td>
+   </tr>
+    <tr>
+      <td>allowCloseOnBooking</td>
+      <td>boolean, whether the confirmation view is closeable once the booking was successfull.</td>
+   </tr>
+    <tr>
+      <td>hideTimumFooter</td>
+      <td>boolean, whether 'powered by timum' can be hidden or not. Needs premium plan.</td>
+   </tr>
+   <tr>
+      <td>channelKey</td>
+      <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> 
+         - RESOURCE_PUBLIC <br> referring to "Public Booking Link" (Öffentlicher Buchungs-Link) <br> 
+         - RESOURCE_EXCLUSIVE <br> referring to "Exclusive Booking Access" (Exklusiver Buchungs-Zugang) <br> 
+         - RESOURCE_REFERENCE <br> referring to "Embedded booking calendars" (Eingebettete Buchungskalender) <br>
+         - 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>
+   </tr>
+   <tr>
+      <td>calendarFrontend</td>
+      <td>string, one of <code>fullCalendar</code> (that's what `init`'s 3rd parameter is for), <code>pureListView</code> or <code>detailsListView</code></td>
+   </tr>
+   <tr>
+      <td>culture</td>
+      <td>string, The localisation to use. If not specified the browser language is used. Can also be a url parameter.</td>
+   </tr>
+   <tr>
+      <td>pData</td>
+      <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> 
+         <code>{ platform: string, personId: string }</code> 
+         <br> Can also be a url parameter. -&gt; the params are named differently though: pDataPlatform, pDataId
+      <blockquote>
+      Note: pData is ignored in favor of a timum auth cookie.
+      Use incognito mode, another browser or sign out to circumvent this.
+       </blockquote>   
+      </td>
+   </tr>
+   <tr>
+      <td>callbacks</td>
+      <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>
+   </tr>
+   <tr>
+      <td>fields</td>
+      <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. 
+      <br>
+      Needs premium plan. 
+      </td>
+   </tr>
+   <tr>
+      <td>localization</td>
+      <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.)
+      <br>
+      Needs premium plan. 
+      </td>
+   </tr>
 </table>
 
 <a name=”how_to_use_callbacks”></a>

package/build/{index-cbd0a1b2.js → index-16bddaba.js}

@@ -1,4 +1,4 @@
-import { b as a, B as e, g as l } from "./index-553c5952.js";
+import { b as a, B as e, g as l } from "./index-f01854a3.js";
 export {
   a as buttonClasses,
   e as default,

package/build/{index-c8837ddb.js → index-21fc58fc.js}

@@ -1,4 +1,4 @@
-import { D as e, F as l, E as t } from "./index-553c5952.js";
+import { D as e, F as l, E as t } from "./index-f01854a3.js";
 export {
   e as default,
   l as getTableRowUtilityClass,

package/build/{index-afebd373.js → index-2b2afb5d.js}

@@ -1,4 +1,4 @@
-import { k as e, n as l, m as t } from "./index-553c5952.js";
+import { k as e, n as l, m as t } from "./index-f01854a3.js";
 export {
   e as default,
   l as getTableBodyUtilityClass,

package/build/{index-7ab8be5b.js → index-43723220.js}

@@ -1,4 +1,4 @@
-import { h as e, j as l, i as t } from "./index-553c5952.js";
+import { h as e, j as l, i as t } from "./index-f01854a3.js";
 export {
   e as default,
   l as getTableUtilityClass,

package/build/{index-43f4920d.js → index-8a846f8e.js}

@@ -1,4 +1,4 @@
-import { L as l, a as t, l as e } from "./index-553c5952.js";
+import { L as l, a as t, l as e } from "./index-f01854a3.js";
 export {
   l as default,
   t as getLinkUtilityClass,

package/build/{index-1b10e9aa.js → index-c23c879e.js}

@@ -1,4 +1,4 @@
-import { c as e, e as a, d as l } from "./index-553c5952.js";
+import { c as e, e as a, d as l } from "./index-f01854a3.js";
 export {
   e as default,
   a as getListItemTextUtilityClass,

package/build/{index-0480e070.js → index-eb6e32c7.js}

@@ -1,4 +1,4 @@
-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-553c5952.js";
+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";
 function y(o) {
   return b("MuiTableFooter", o);
 }

package/build/{index-404c5e68.js → index-eddc9c92.js}

@@ -1,4 +1,4 @@
-import { o as e, q as s, p as t } from "./index-553c5952.js";
+import { o as e, q as s, p as t } from "./index-f01854a3.js";
 export {
   e as default,
   s as getTableCellUtilityClass,

package/build/{index-87eebe34.js → index-eec841ad.js}

@@ -1,4 +1,4 @@
-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-553c5952.js";
+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";
 function x(e) {
   return p("MuiTableHead", e);
 }