Merge pull request #23 from Ortovoxx/main

jekuer · web-flow · commit e78c980897df · 2022-02-03T15:06:22.000+01:00
Improved documentation for React
diff --git a/README.md b/README.md
@@ -2,14 +2,14 @@
 ![Add-to-Calendar Button](https://github.com/jekuer/add-to-calendar-button/blob/main/repo_image.png?raw=true)
 
 _A convenient JavaScript snippet, which lets you create beautiful buttons, where people can add events to their calendars._
- 
+
 
 ## Use case // Who this is for
 
 This is for everybody, who wants to include a button at his/her website or app, which enables users to easily add a specific event to their calendars.
 It's main goal is to keep this process as easy as possible. Simply define your button configuration via JSON and everything else is automatically generated by the script.
 It is for this simple use case. No strings attached.
- 
+
 
 ## Background // Why this repo exists
 
@@ -23,12 +23,12 @@ The problems with AddEvent.com:
 * it brings some data privacy issues, since you basically send your users to their service.
 * the UX/UI is not ideal (imho).
 *Bottom line:* Pay for features, which I do not need - at additional privacy "cost" - that made me create this solution (for you).
- 
+
 
 ## DEMO
 
 See [jekuer.github.io/add-to-calendar-button](https://jekuer.github.io/add-to-calendar-button/) for a live demo.
- 
+
 
 ## Features
 
@@ -45,12 +45,12 @@ See [jekuer.github.io/add-to-calendar-button](https://jekuer.github.io/add-to-ca
 * Well documented code, to easily understand the processes.
 
 ![Demo Screenshot](https://github.com/jekuer/add-to-calendar-button/blob/main/demo.gif?raw=true)
- 
+
 
 ## Setup
- 
+
 ### Option 1: simple
- 
+
 1. Simply **download** the code from GitHub **or clone** the git repository.
 2. Copy the css (atcb.min.css) and js (atcb.min.js) files from the assets (not the "npm_dist"!) folders into your project (the **.min.** files are required, but it is recommended to also copy the raw and map files).
 3. Include those files in your project. As usual, the css goes into the <head> (`<link rel="stylesheet" href="./assets/css/atcb.min.css">`), the js into the <body> footer (`<script src="./assets/js/atcb.min.js" defer></script>`). You can also combine them with other files, if you want to.
@@ -63,23 +63,23 @@ See [jekuer.github.io/add-to-calendar-button](https://jekuer.github.io/add-to-ca
 2. Run **`npm install add-to-calendar-button`**.
 3. Import the module into your project/component. For example with Angular/React: `import { atcb_init } from 'add-to-calendar-button';`.
 4. Init the js after the DOM has been loaded. To determine the right moment and execute, ...
-  1. with Angular, you would use `ngAfterViewInit()` with `atcb_init();` (mind that, depending on your app, other hooks might be better); 
-  2. with React, you might want to include an event listener like `document.addEventListener('DOMContentLoaded', atcb_init, false);`.
+  1. with Angular, you would use `ngAfterViewInit()` with `atcb_init();` (mind that, depending on your app, other hooks might be better);
+  2. with React, you might want to include an event listener like `document.addEventListener('DOMContentLoaded', atcb_init, false);` or using hooks in a functional component like `useEffect(() => atcb_init());`
 5. Include the css. For example with Angular or React, add the following to the global style.css: `@import 'add-to-calendar-button/assets/css/atcb.min'`;
 6. Create your button as can be seen in the "Configuration" section below.
 7. That is it. The script takes care of all the rest. :)
- 
+
 
 ## Configuration
 
-A button can be easily created by placing a respective placeholder, wherever you want the button to appear. 
+A button can be easily created by placing a respective placeholder, wherever you want the button to appear.
 (The `style="display:none;"` theoretically is not necessary, but should be used for better compatibility.)
 ```html
 <div class="atcb" style="display:none;">
   (...)
 </div>
 ```
-Within this placeholder, you can easily configure the button, by placing a respective JSON structure. 
+Within this placeholder, you can easily configure the button, by placing a respective JSON structure.
 Mind that with Angular, you might need to escape the { with `{{ '{' }}` and } with `{{ '}' }}`; with React it would be `{ '{' }` and `{ '}' }`.
 
 ### Minimal structure (required)
@@ -160,7 +160,28 @@ You can use startTime and endTime in the event block, but it is recommended to r
   </script>
 </div>
 ```
- 
+
+### React example
+
+A simpler method uses `JSON.stringify()` where you define your config in an external file or variable and then
+convert it to a string to be passed into the div.
+
+```js
+const AddToCalendar = () => {
+
+    useEffect(() => atcb_init());
+
+    const event = { /* Event data */}
+
+    return (
+        <div className='atcb'>
+            <script type="application/ld+json">
+                {JSON.stringify(event)}
+            </script>
+        </div>
+    );
+}
+```
 
 ### Important information and hidden features
 
@@ -181,7 +202,7 @@ You can use startTime and endTime in the event block, but it is recommended to r
 * If you want to define a specific name for any generated ics file (iCal), you can specify it via the "iCalFileName" option. The default would be "event-to-save-in-my-calendar".
 * You can use the option "inline":true in order to make the button appear with inline-block instead of block style.
 * If you require line breaks within the description, use `\n` or `<br>`.
- 
+
 
 ## Contributing
 
@@ -192,12 +213,12 @@ Anyone is welcome to contribute, but mind the [guidelines](.github/CONTRIBUTING.
 * [Pull requests](.github/CONTRIBUTING.md#pull-requests)
 
 IMPORTANT NOTE: Run `npm install` and `npm run build` to create the minified js and css file, its sourcemap files as well as the npm_dist/ folder and content!
- 
+
 
 ## License
 
 The code is available under the [MIT license (with “Commons Clause” License Condition v1.0)](LICENSE.txt).
- 
+
 
 ## Changelog (without bug fixes)
 
@@ -206,7 +227,7 @@ The code is available under the [MIT license (with “Commons Clause” License
 * v1.2 : inline and line break support
 * v1.1 : npm functionality
 * v1.0 : initial release
- 
+
 
 ## Kudos go to
 * [github.com/dudewheresmycode](https://github.com/dudewheresmycodee)
