@openlettermarketing/olc-react-sdk 0.0.39 → 0.0.41

package/README.md

@@ -1,30 +1,125 @@
-# React + TypeScript + Vite
+# Integration Guide
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+## OLC React SDK Integration Guide
 
-Currently, two official plugins are available:
+### Introduction
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+The OLC React SDK allows developers to integrate a customizable template builder into their applications. This guide provides step-by-step instructions to help you install, configure, and use the SDK.
 
-## Expanding the ESLint configuration
+### 1. Installation
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+Start by installing the OLC React SDK via [NPM](https://www.npmjs.com/package/@openlettermarketing/olc-react-sdk).
 
-- Configure the top-level `parserOptions` property like this:
+```Shell
+npm install @openlettermarketing/olc-react-sdk
+```
+
+### 2. Importing and Initializing the SDK
+
+After installation, import the SDK into your React application and configure the required properties to initialize the `TemplateBuilder` component.
 
-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
+### Complete coverage usage:.
+The following example shows the demo of all props minimalist usage, For the real case integration, see [integration example](#6-real-case-of-usage).
+
+```Javascript
+import TemplateBuilder from '@openlettermarketing/olc-react-sdk';
+
+const templateBuilderProps = {
+  container: document.getElementById('element-id'),
+  secretKey: 'your-secret-key',
+  basicAuthUsername: 'your-username',
+  basicAuthPassword: 'your-password',
+  platformName: 'Your Platform Name',
+  createTemplateRoute: '/create-template',
+  templateBuilderRoute: '/edit-template',
+  olcTemplate: yourTemplateObject,
+  sandbox: true,
+  onReturnAndNavigate () {
+    // TODO: Define what happens when the user returns and navigates.
   },
-}
+  async onGetOneTemplate (payload) => {
+    // TODO: Fetch a specific template.
+  },
+  async onGetTemplates (payload) => {
+    // TODO: Fetch all templates.
+  },
+  async onGetCustomFields () => {
+    // TODO: Fetch custom fields for the templates.
+  },
+  async onSubmit (payload) => {
+    // TODO: Handle the submission of a template.
+  },
+  styles: {
+    root: {
+      // Custom CSS properties for the root element.
+    },
+  },
+};
+
+TemplateBuilder(templateBuilderProps);
 ```
 
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+### 3. Configuration through Props
+The SDK uses several properties to manage its behavior. Below is a breakdown of key props:
+
+| Prop name              | Type             | Description                                                                                                    | Required | Example / Usage                                            |
+|------------------------|:-----------------|----------------------------------------------------------------------------------------------------------------|----------|:-----------------------------------------------------------|
+| `container`            | _HTMLDivElement_ | An HTML DOM element to render the template builder component.                                                  | ✓ | `document.getElementById('template-builder-container')` |
+| `secretKey`            | _string_         | That key is used to communicate _Polotno_ Editor (Builder) with API requests.                                  | ✓ | `'your-secret-key'`                                        |
+| `basicAuthUsername`    | _string_         | _Username_ for basic authentication.                                                                           | ✓ | `'your-username'`                                          |
+| `basicAuthPassword`    | _string_         | _Password_ for basic authentication.                                                                           | ✓ | `'your-password'`                                          |
+| `platformName`         | _string_         | The name of your platform.                                                                                     | ⤫ | `'My App'`                                                 |
+| `createTemplateRoute`  | _string_         | The route/path for creating new templates. _(begins with slash `/`)_                                           | ⤫ | `'/create-template'`                                       |
+| `templateBuilderRoute` | _string_         | The route/path for editing existing templates. _(begins with slash `/`)_                                       | ⤫ | `'/edit-template'`                                         |
+| `olcTemplate`          | _object_         | The template object to be edited or used as a base.                                                            | ⤫ | `{ ... }`                                                  |
+| `sandbox`          | _boolean_         | The sandbox setting can be either true or false. Set to true for demo purposes and false for production.                                                            | ⤫ | `true`                                                  |
+| `onReturnAndNavigate`  | _function_       | An event which triggers when a user navigates away.                                                            | ⤫ | `onReturnAndNavigate () { ... }`                           |
+| `onGetOneTemplate`     | _function_       | An event which triggers when fetching a specific template.                                                     | ⤫ | `onGetOneTemplate ( payload ) { ... }`                     |
+| `onGetTemplates`       | _function_       | An event which triggers when fetching all templates.                                                           | ⤫ | `onGetTemplates ( payload ) { ... }`                       |
+| `onGetCustomFields`    | _function_       | An event which triggers when fetching custom fields for templates.                                             | ⤫ | `onGetCustomFields () { ... }`                             |
+| `onSubmit`             | _function_       | An event which triggers upon template submission.                                                              | ⤫ | `onSubmit () { ... }`                                      |
+| `styles`               | _object_         | An object of [JSS](https://reactjs.org/docs/faq-styling.html) props for customize styling of template builder. | ⤫ | `{ root: { ... } }`                                        |
+
+### 4. API Integration
+To integrate the SDK’s API, ensure that your backend securely communicates with the OLC _Backend_, returning the necessary data to the SDK frontend.
+
+### 5. Customization and Styling
+The SDK allows for extensive customization of the template builder’s appearance. Use the `styles` prop to apply custom CSS properties and match the look and feel of your application.
+
+### 6. Real-case of usage
+Below is an example of how to use the SDK within a React component:
+
+```Typescript
+import { useEffect } from 'react';
+
+// SDKs
+import TemplateBuilder from '@openlettermarketing/olc-react-sdk';
+
+// styles
+import '@blueprintjs/core/lib/css/blueprint.css';
+
+const App = () => {
+  useEffect(() => {
+    TemplateBuilder({
+      container: document.getElementById('template-builder-container'),
+      secretKey: 'your-secret-key',
+      basicAuthUsername: 'your-username',
+      basicAuthPassword: 'your-password',
+      sandbox: false,
+      async onSubmit (payload) {
+        console.log('Template submitted:', payload);
+        // Implement your submission logic here
+      },
+    });
+  }, []);
+
+  return (
+    <>
+      {/** ... */}
+      <div id="template-builder-container" />
+    </>
+  );
+}
+
+export default App;
+```