Merge pull request #64 from unit214/documentation-updates

Update documentation, update Sample App

.gitignore

@@ -14,4 +14,5 @@ resources/.arch-internal-preview.css
 .arch-internal-preview.css
 node_modules/
 dist/
-yarn.lock
+yarn.lock
+.idea

CONTRIBUTE.md

@@ -0,0 +1,115 @@
+# Contribute to react-tag-commander
+
+We're delighted that you're interested in contributing to react-tag-commander! This document is intended to outline the process and guidelines for contributing to this repository. We want to make contributing to this project as easy and transparent as possible.
+
+## Getting Started
+
+1. **Fork the repository**
+
+Start by forking the repository on GitHub. This will create a personal copy for you to work on.
+
+2. **Clone your fork**
+
+Clone your fork to your local machine. Replace `your-username` with your GitHub username.
+
+```bash
+git clone https://github.com/your-username/react-tag-commander.git
+```
+
+3. **Set up remote upstream**
+
+Add the original repository as an upstream remote to your local repository.
+
+```bash
+git remote add upstream https://github.com/CommandersAct/react-tag-commander.git
+```
+
+4. **Install dependencies**
+
+Navigate to the project directory and install its dependencies.
+
+```bash
+cd react-tag-commander
+npm install
+```
+
+## Making Changes
+
+1. **Create a branch**
+
+Create a new branch for your changes.
+
+```bash
+git checkout -b feature/my-new-feature
+```
+
+2. **Make your changes**
+
+Edit, add, or delete files as necessary for your contribution.
+
+3. **Follow the coding standards**
+
+Ensure your code adheres to the coding standards used throughout the project.
+
+4. **Write tests**
+
+If you're adding new functionality, please write tests to accompany it.
+
+5. **Run the tests**
+
+Ensure all tests pass before submitting your changes.
+
+```bash
+npm run test
+```
+
+6. **Document your changes**
+
+Update the documentation to reflect any changes you have made.
+
+7. **Update the Sample App**
+
+Update the `tag-commander-sample-app` to reflect any changes you have made. Ensure that it is still running and add new examples if possible to illustrate your changes.
+
+
+## Submitting Changes
+
+1. **Commit your changes**
+
+Commit your changes with a clear and descriptive commit message.
+
+```bash
+git commit -m "Add a brief description of your changes"
+```
+
+2. **Fetch upstream changes**
+
+Fetch any recent changes from the upstream master branch.
+
+```bash
+git fetch upstream
+```
+
+3. **Rebase your branch**
+
+Rebase your branch on top of the upstream master.
+
+```bash
+git rebase upstream/master
+```
+
+4. **Push your changes**
+
+Push your changes to your fork.
+
+```bash
+git push origin feature/my-new-feature
+```
+
+5. **Create a pull request**
+
+Go to your fork on GitHub and create a pull request against the [CommandersAct/react-tag-commander](https://github.com/CommandersAct/react-tag-commander) 's master branch.
+
+## Reporting Issues
+
+If you find any bugs or have a feature request, please create an issue on GitHub using the issue tracker.

README.md

@@ -1,9 +1,8 @@
-# React-Tag-Commander Documentation
+# react-tag-commander
 
-Integrate Tag Commander with your React applications seamlessly using the `react-tag-commander` wrapper.
+Integrate CommandersAct's tag container with your React applications seamlessly using the `react-tag-commander` wrapper.
 
-- [Official Tag Commander website](https://www.commandersact.com/fr/produits/tagcommander/)
-- **Note**: Familiarize yourself with [Tag Commander's primary documentation](https://community.commandersact.com/tagcommander/) before proceeding.
+- **Note**: Familiarize yourself with [CommandersAct's tag container's primary documentation](https://doc.commandersact.com/features/sources/sources-catalog/web/containers) before proceeding.
 
 ## Table of Contents
 - [Features](#features)
@@ -12,18 +11,20 @@ Integrate Tag Commander with your React applications seamlessly using the `react
   - [Container Management](#container-management)
   - [Variable Management](#variable-management)
   - [Events](#events)
-- [Reloading Containers](#reloading-containers)
+  - [Reloading Containers](#reloading-containers)
+- [Server-side Rendering (SSR)](#server-side-rendering)
 - [Sample App](#sample-app)
 - [License](#license)
 - [Development](#development)
+- [Contribute](#contribute)
 
-## Features
+## Features <a name="features"></a>
 
 - Automatic page tracking
 - Event triggering
 - Supports multiple containers
 
-## Installation and Quick Start
+## Installation and Quick Start <a name="installation-and-quick-start"></a>
 
 ### Installation
 
@@ -69,75 +70,90 @@ Integrate Tag Commander with your React applications seamlessly using the `react
 import React from "react";
 import TC_Wrapper from "react-tag-commander";
 
-const wrapper = TC_Wrapper.getInstance();
-
 function App() {
+    const [tcReady, setTcReady] = useState(false);
+    
+    useEffect(() => {
+        const wrapper = TC_Wrapper.getInstance();
+        Promise.all([
+            wrapper.addContainer('container_head', '/tag-commander-head.js', 'head'), 
+            wrapper.addContainer('container_body', '/tag-commander-body.js', 'body')
+        ]).then(() => {
+            setIsReady(true);
+        });
+    }, []);
+    
+    return ( tcReady ? <div>Containers loaded</div> : <div>Now loading</div> );
+}
+```
+## Methods <a name="methods"></a>
 
-  const [tcReady, setTcReady] = useState(false);
+Many methods are asynchronous. If you want to ensure that a method has been executed before continuing, you can use the `await` keyword. Please check the function definition to see if it is asynchronous.
 
-  useEffect(() => {
-    Promise.all([
-      wrapper.addContainer('container_head', '/tag-commander-head.js', 'head'),
-      wrapper.addContainer('container_body', '/tag-commander-body.js', 'body')
-    ]).then(() => {
-      setIsReady(true);
-    });
-  }, []);
+### Container Management <a name="container-management"></a>
 
+```js
+// Adding a container
+await wrapper.addContainer('my-custom-id', '/url/to/container.js', 'head');
 
-  return ( tcReady ? <div>Containers loaded</div> : <div>Now loading</div> );
-}
+// Removing a container
+wrapper.removeContainer('my-custom-id');
 ```
-# Methods
-
-Many methods are asynchronous. If you want to ensure that a method has been executed before continuing, you can use the `await` keyword. Please check the function definition to see if it is asynchronous.
 
-## Container Management
-   ```js
-   // Adding a container
-   await wrapper.addContainer('my-custom-id', '/url/to/container.js', 'head');
+### Variable Management <a name="variable-management"></a>
 
-   // Removing a container
-   wrapper.removeContainer('my-custom-id');
-   ```
+```js
+// Set variables
+await wrapper.setTcVars({ env_template : "shop", ... });
 
-## Variable Management
-   ```js
-   // Set variables
-   await wrapper.setTcVars({ env_template : "shop", ... });
+// Update a single variable
+await wrapper.setTcVar('env_template', 'super_shop');
 
-   // Update a single variable
-   await wrapper.setTcVar('env_template', 'super_shop');
+// Get a variable
+const myVar = wrapper.getTcVar('VarKey');
 
-   // Get a variable
-   const myVar = wrapper.getTcVar('VarKey');
+// Remove a variable
+wrapper.removeTcVar('VarKey');
+```
 
-   // Remove a variable
-   wrapper.removeTcVar('VarKey');
-   ```
+### Events <a name="events"></a>
 
-## Events
-- Refer to the [base documentation on events](https://community.commandersact.com/tagcommander/user-manual/container-management/events) for an understanding of events in general. 
+- Refer to the [base documentation on events](https://doc.commandersact.com/features/sources/sources-catalog/web/containers/user-guides-for-browser-side-platform/tags/rules/triggers) for an understanding of events in general. 
 - The method "triggerEvent" is the new name of the old method "captureEvent"; an alias has been added to ensure backward compatibility.
 
+```js
+// Triggering an event
+// eventLabel: Name of the event as defined in the container
+// htmlElement: Calling context. Usually the HTML element on which the event is triggered, but it can be the component.
+// data: event variables
+await wrapper.triggerEvent(eventLabel, htmlElement, data);
+```
 
-  ```js
-  // Triggering an event
-  // eventLabel: Name of the event as defined in the container
-  // htmlElement: Calling context. Usually the HTML element on which the event is triggered, but it can be the component.
-  // data: event variables
-  await wrapper.triggerEvent(eventLabel, htmlElement, data);
-  ```
-
-## Reloading Containers
+### Reloading Containers <a name="reloading-containers"></a>
 
-1. **Manual Reload**: Update your container after any variable change.
-   ```js
-   await wrapper.reloadContainer(siteId, containerId, options);
-   ```
+#### Manual Reload
+Update your container after any variable change.
+```js
+await wrapper.reloadContainer(siteId, containerId, options);
+```
 
-2. **On Route Change**: Utilize the `trackPageLoad` function for updating on route changes.
+#### Exclusions
+You can state an exclusion array to your options object like below.
+```typescript
+const options = {
+        exclusions: [
+            'datastorage',
+            'deduplication',
+            'internalvars',
+            'privacy'
+        ]
+    };
+await wrapper.reloadContainer(siteId, containerId, options);
+```
+Please see the [container's documentation](https://doc.commandersact.com/features/sources/sources-catalog/web/containers/setup-guides-for-developers/spa-implementation-guide#id-2.how-to-implement-tagcommander-in-an-spa-environment) for other options.
 
+#### On Route Change
+Utilize the `trackPageLoad` function for updating on route changes.
 ```js
 function SampleView() {
 
@@ -152,7 +168,43 @@ function SampleView() {
 }
 ```
 
-## Sample App
+## Server-side Rendering (SSR) <a name="server-side-rendering"></a>
+
+`react-tag-commander` works seamlessly with frameworks utilizing Server-side Rendering (SSR) (for example [Next.js](https://nextjs.org/)).
+However, the wrapper is interacting with the DOM objects `document` and `window`, which are not available on the server.
+Therefore, you have to make sure that wrapper methods are only executed on the client-side.
+This can be achieved by using hooks like `useEffect`, `useCallback` or `useState` or, executing it in a callback function that doesn't run on the server, for example the `submit` function of a form.
+
+Examples:
+```js
+// Throws an 'window is not defined' error, as the code is executed on the server and trackPageLoad interacts with the window object.
+function SampleView() {
+    const wrapper = TC_Wrapper.getInstance();
+    wrapper.trackPageLoad({tcVars: {page: 'home'}})
+}
+```
+```js
+// Works as the code is executed on the client only
+function SampleView() {
+    useEffect(() => {
+        const wrapper = TC_Wrapper.getInstance();
+        wrapper.trackPageLoad({tcVars: {page: 'home'}})
+    }, []);
+}
+```
+
+Another option is to check whether `window` is defined before executing a method.
+```js
+function SampleView() {
+    if (typeof window !== 'undefined') {
+        // client-side-only code
+        const wrapper = TC_Wrapper.getInstance();
+        wrapper.trackPageLoad({tcVars: {page: 'home'}})
+    }
+}
+```
+
+## Sample App <a name="sample-app"></a>
 
 To help you with your implementation we provided a sample application. To run it clone the repo then run:
 ```bash
@@ -161,15 +213,25 @@ yarn start
 ```
 Then, visit [http://localhost:3000](http://localhost:3000).
 
-## License
-This module uses the [MIT License](http://revolunet.mit-license.org). Contributions are welcome.
 
-## Development
+# Development <a name="development"></a>
 
 After forking, set up your environment:
 
-1. ```npm install```
+```bash
+npm install
+```
 
 Commands available:
 
-1. ```gulp```
+```bash
+gulp
+```
+
+# Contribute <a name="contribute"></a>
+
+To contribute to this project, please read the [CONTRIBUTE.md](CONTRIBUTE.md) file.
+
+## License <a name="license"></a>
+
+This module uses the [MIT License](http://revolunet.mit-license.org). Contributions are welcome.

package.json

@@ -2,8 +2,8 @@
   "name": "react-tag-commander",
   "version": "2.2.0",
   "main": "./src/index.js",
-  "repository": "https://github.com/TagCommander/react-tag-commander.git",
-  "author": "Lenoir jérémie",
+  "repository": "https://github.com/commandersact/react-tag-commander",
+  "author": "CommandersAct",
   "license": "MIT",
   "devDependencies": {
     "@babel/cli": "^7.22.9",