@timum/booking 1.9.0 → 1.10.0

package/README.md

@@ -60,6 +60,9 @@ This documentation guides you through all the customization capabilities.
 
 <a name=”in-a-script-tag”></a>
 
+These are some minimal examples. BookingJs is highly customizable.
+An overview over all configuration options can be found in [Advanced Customisation](#advanced-usage)
+
 ### In a Script Tag
 
 Add the following code to your webpage:
@@ -109,6 +112,30 @@ init({ ref: 'booking-widget-demo-resource@timum' });
 
 A example project can be found [here](https://stackblitz.com/edit/react-8q6r8b?file=src/index.js)
 
+### As React component import
+
+1. Add timum booking to your project with
+   `yarn add @timum/booking`
+   or use npm with
+   `npm install @timum/booking`
+   <br>
+2. Add the following code anywhere in your jsx:
+
+```javascript
+import { TimumBooking } from '@timum/booking';
+
+// other code
+
+<TimumBooking
+  appConfig={{
+    ref: 'booking-widget-demo-resource@timum'
+    // other options
+  }}
+/>;
+
+// other code
+```
+
 <a name="entity-referencing"></a>
 
 ### Entity Referencing
@@ -335,10 +362,6 @@ This object's options directly affect timum's behaviour or allow you to react to
     <tr>
       <td>sendCustomValuesInMessage</td>
       <td>boolean, whether values of custom fields are concatenated and comma-separated into a single string which is then sent to the backend as <code>message</code>. If field <code>message</code> is defined its input is concatenated to the generated string as well.</td>
-   </tr>
-    <tr>
-      <td>gatherAddressData</td>
-      <td>boolean, adds the fields <code>street</code>, <code>zipCode</code> and <code>city</code> in their default configuration to the booking page. You may also redefine/override them in the <code>fields</code> object, which supersedes this setting (needs professional plan). timum handles address data in a best effort basis, meaning it tries to parse the data and sync it to connected CRM systems, if possible.</td>
    </tr>
    <tr>
       <td>channelKey</td>
@@ -351,7 +374,13 @@ This object's options directly affect timum's behaviour or allow you to react to
    </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>
+      <td>string, one of <code>fullCalendar</code>, <code>detailsFullCalendar</code> (these are what `init`'s 3rd parameter is for), <code>pureListView</code>, <code>detailsListView</code>, <code>condensedView</code> or <code>detailsCondensedView</code>
+      <br>
+      <br>
+       <blockquote>
+      Note: the <code>details</code> variants show details about the resource, like the description and the external url, as well as public information about the assigned consultant, if the channel allows that. 
+       </blockquote>   
+      </td>
    </tr>
    <tr>
       <td>culture</td>
@@ -672,8 +701,6 @@ localization: {
 
 You can customize the information you request from customers before booking by defining fields. The minimum required fields for timum are <code>firstName</code>, <code>lastName</code>, <code>email</code>, and <code>agbs</code>. By default, timum also requests <code>mobile</code> and <code>message</code> fields, but you can add your own fields as well.
 
-Supported, but not present by default are the fields <code>street</code>, <code>zipCode</code> and <code>city</code>. You can activate them setting <code>gatherAddressData</code>, or by redefining fields with the same name as custom fields (see below).
-
 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:
 
@@ -683,7 +710,7 @@ 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 fields. The following is the standard configuration:
+The standard configuration can be overridden except for the aforementioned, required fields. The following is the standard configuration:
 
 ```javascript
 fields: {
@@ -716,24 +743,6 @@ fields: {
     preferredCountries: ['DE', 'CH', 'AT'],
     // validation: is in built and ignored
   },
-  street: {
-    index: 4,
-    title: 'fields.street',
-    validation: yup.string().required('validation.field_required'),
-    ignore: true, // gets filtered by default. Set gatherAddressData: true to activate this field. Or just add it to your custom field config.
-  },
-  zipCode: {
-    index: 5,
-    title: 'fields.zipCode',
-    validation: yup.string().required('validation.field_required'),
-    ignore: true, // gets filtered by default. Set gatherAddressData: true to activate this field. Or just add it to your custom field config.
-  },
-  city: {
-    index: 6,
-    title: 'fields.city',
-    validation: yup.string().required('validation.field_required'),
-    ignore: true, // gets filtered by default. Set gatherAddressData: true to activate this field. Or just add it to your custom field config.
-  },
   message: {
     index: 7,
     title: 'fields.message',
@@ -779,25 +788,52 @@ If the values retrieved via custom fields need to be transferred to timum backen
 
 Anatomy of a custom booking form field:
 
-```
-  <fieldName> : {
-      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 https://github.com/jquense/yup. Re-exported and accessible via timum.yup
-      type: string; either 'text' (default), 'phoneNumber', 'textarea', 'checkbox' or 'select',
-      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.
-  }
-```
+`<fieldName> : {`
+
+  <blockquote>
+      <code>index</code>: 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.)
+  </blockquote>
+  <br>
+    <blockquote>
+    <code>title</code>: string or JSXElement;
+  validation: yup based validation. See <a href="https://github.com/jquense/yup">yup docu</a>. Re-exported and accessible via timum.yup
+
+  </blockquote>
+  <br>
+    <blockquote>
+    <code>type</code>: string; either 'text' (default), 'phoneNumber', 'textarea', 'checkbox' or 'select'. Depending on the chosen type additional properties are available. See below. 
+  </blockquote>
+  <br>
+    <blockquote>
+    <code>onChange</code>: function, allows to execute code whenever the user changes the fields value. Gets 'value' as function parameter.
+  </blockquote>
+  <br>
+    <blockquote>
+    <code>prefilled</code>: 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.
+  </blockquote>
+  <br>
+  <blockquote>
+    <code>preventRendering</code>: 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.
+  </blockquote>
+  <br>
+  <blockquote>
+    <code>preventRenderingFor</code>: 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.
+  </blockquote>
+`}`
 
 fieldName
 
@@ -807,23 +843,23 @@ 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.).
+- `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'],
+- 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.
+- limit: number; sets the maximum number of characters customers can enter.
 
 - Type `checkbox`:
-  - no special properties.
+- no special properties.
 
 Type `select`: