Advanced Usage

Built-in options

It seems obvious, but sometimes people jump directly into the ugly stuff, while there is a lot you can do with the included easy-to-use features.

Check the "Configuration" page for all available settings and functionalities.

The following examples use some of them to showcase the variety of the included styles.

Override styles

Generally, it is not possible to directly override the CSS style, since the button sits in its own ShadowDOM.
What you can do, however, is overriding some CSS variables, which are bound to the host (= the <add-to-calendar-button> tag).
You can simply provide the default ones via the "styleLight" attribute and the "dark mode" overrides via an additional "styleDark" attribute.

The available variables differ per selected button style. Check the respective css file in the repository (have a look at the "Global colors and shadows" section).

Mind that this is not working with the "none" button style or the atcb_action approach (see #10).

Load an external CSS file

Another approach you can use, would be to load an external CSS file. Provide the file with the "customCss" option and set the button style to "custom".
This file could, of course, also be within your application, but should not be bundled with other css. Additionally, it is not allowed to use a url path with "../" syntax due to security reasons. Absolute urls would be recommended.

Mind that in this case, you need to take care of all (!) elements.
It is recommended to copy a provided stylesheet from the repository and change what you want to change.

For this approach, you also need to make sure that your system allows to load external stylesheets (e.g. no blocking Content-Security-Policy rules).

In our example here, we keep it basic and only change the color again.

Target elements via ::part

You can use the css ::part selector to directly style pre-selected elements from your regular css code.

The following elements are available for this approach:

• atcb-button-wrapper
• atcb-button
• atcb-button-icon
• atcb-button-text
• atcb-list-wrapper
• atcb-list
• atcb-list-item
• atcb-list-item-close
• atcb-list-icon
• atcb-list-text
• atcb-modal-box

Use a custom object as button

Last but not least, you could also stick to a provided style, but use your own triggering object.
Check the "10. Bring your own button" example at the bottom of this page for more details.

The event description does not need to be simple plain text!
You can use HTML special characters as well as specific formatting rules.

Those rules are set up as HTML pseudo tags, which get transformed automatically.
(If you are using the WordPress Plugin Shortcode, ']' would break your code. Instead of [*], you could also use {*} here.)
(Apple, Yahoo, and Microsoft Teams are not fully supported and automatically transformed to plain text, supporting only line breaks and hyperlinks.)

You can also offer your users the option to subscribe to a calendar, instead of only saving static events.

To get this to work, you would simply need to set the public address (an .ics file) of the calendar as the "icsFile" option and set the "subscribe" option to true.

"name" is still required, but every other event parameter can be skipped in this case.
For Microsoft services, the "name" will be used as name for the calendar.
Mind that there won't be rich data for the subscribe option.
(If the user's browser does not recognize any installed calendar app, this might lead to a blank screen. The PRO version mitigates this with some explenatory middleware screen.)

You can change any text blocks.

For the button label you can simply specify the "label" option.

For all other text blocks (like the "Close" at the modal list type), you can specify the "customLabels" option.
There, you need to specify a JSON structure and define any text you want to override.
Check the atcb-i18n.js file at the repository for the available keys/options.
Any custom label will also override any translation.

(In case you are only looking for translating labels, check the "language" option instead!)

If you feel confident enough to mess with the rather unusual iCal settings, you can use the options "uid", "sequence", "created", "updated", "attendee", and "status" (TENTATIVE, CONFIRMED, CANCELLED).
They basically override the respective default values.

Mind that those options are only supported by the iCal and Apple calendar links!

To update an existing event (e.g. changing its status) by changing those properties, you would need to have a growing sequence number, newer "updated" date, same "created" date, the same "uid", and also the organizer field (name and email) set.

Some calendars only work with the "attendee" to be specified as well. And if your "update" to the event is not a status change to "CANCELLED", it is mandatory in all cases!
The attendee needs to be the person saving the event. If you know this, you can make use of this functionality. If not, we would not recommend it.

A generated button gets an ID assigned. This ID follows the scheme "atcb-btn-X", where "X" will be an ascending number.
The individual calendar links then get the button ID plus the calendar type assigned - like "atcb-btn-5-google".

You can override the automatically defined "X" at the button ID by defining a distinctive one with the "identifier" option.
This might help you to track any user interaction more precisely.

Mind that this ID needs to be unique and may not be used at any other element!

It behaves a little different, if you are using the custom atcb_action function, where the script might take the triggering element's id first, before falling back to the described scheme.

We keep track of any action happening with a button.
You can read this data in 2 ways.

1. Observe the atcb-last-event attribute, which gets added to every button. It holds the last event and respective trigger (schema: "EVENT:TRIGGER"; example: "openList:atcb-btn-1").
2. Access the Data Layer.

We are pushing the events directly into the Data Layer, which can be read, for example, with the Google Tag Manager and Google Analytics.

There are some really rare cases where you might not have an event with a specific place and time, but rather a time bound to the user's individual time zone.
For example offering an event, which should remind the users at 8am to brush their teeth.

In those cases, you could set the "timeZone" option to "currentBrowser".
The event's time will then be automatically adjusted for each user based on the individual time zone.

On mobile devices, applications, which are using the "WebView", have problems with how we generate and deliver the .ics files on the fly.
Therefore, we catch those cases, copy the data url to the user's clipboard, and show a short guide on how to proceed.

Since this is the best practice for all websites and web apps, it might not be, if you are building your own native/hybrid app where you have control over the WebView settings.

While this would still break the dynamic generation of the .ics file, you could at least deliver existing external ics files directly.
In this case, you could deactivate the described workaround with the "bypassWebViewCheck" option.

Please make sure that the following applys to your project!

• You are developing your own native/hybrid app.
• You are opening the device's default browser instead of using any in-app WebView.
• You have a distinctive .ics file on some server and can refer to it via the "icsFile" option.

For those who want to go fuc**** crazy custom, we also provide the option to trigger the calendar links list manually.
This provides you with the option to use anything as your button or even trigger it programmatically.

Theoretically, you do not need to provide a button element. However, it is recommended to do so, since it will optimize the user experience a lot (like focusing the element on closing the modal, etc.).
If you do not provide a specific button, the list will automatically show as modal. If provided, you can opt for the overlay-dropdown list style via the listStyle option (mind that all other options are not supported in the atcb_action case). The modal style is strongly recommended.

Step 1: Import

If you use the script via CDN, you can skip this step.
If you use the script as npm package, you would first need to import the "atcb_action" functionality. Simply change the import statement to the following:

Step 2: Config and trigger

Secondly, you would need to define the config and the trigger.
This might differ a lot based on your environment. You are the expert there.

In the example we use a quite simple button for the demonstration.

First things first:
Wherever possible, we load the script asynchronously, so it will not block the rendering of your page.
However, if you include it as a ES module, this behavior usually changes.
Besides some JavaScript frameworks offering other tricks to load components asynchronously, you can try the following to optimize the loading behavior and bundle size.

Unfortunately, we cannot offer any easy tree-shaking solution, as this contradicts the way we are building the script - being a flexible web component, which can adapt on runtime.

The ES package comes in 4 flavors:

1. Default: Includes everything and therefore reduces the risk of failure.
2. no-pro: This is basically the default, if you are not using the PRO version of the script.
3. unstyle: This is the default, but without integrated css (style).
4. no-pro-unstyle: No integrated css, no PRO functionalities.

To reduce the bundle size, you can use the unstyle version with

import 'add-to-calendar-button/unstyle'