@openlettermarketing/olc-react-sdk 0.0.39 → 0.0.41
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -20
- package/build/index.js +99 -78
- package/build/index.js.map +1 -1
- package/build/types/App.d.ts +1 -0
- package/build/types/components/SidePanel/index.d.ts +1 -0
- package/build/types/components/TemplateBuilder/index.d.ts +1 -0
- package/build/types/index.d.ts +3 -1
- package/build/types/utils/constants.d.ts +2 -1
- package/build/types/utils/customStyles.d.ts +1 -0
- package/build/types/utils/helper.d.ts +3 -0
- package/package.json +2 -1
- /package/build/types/components/SidePanel/{customFields → CustomFields}/customFieldSection.d.ts +0 -0
- /package/build/types/components/SidePanel/{templates → Templates}/customTemplateSection.d.ts +0 -0
package/README.md
CHANGED
|
@@ -1,30 +1,125 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Integration Guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## OLC React SDK Integration Guide
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### Introduction
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
|
|
7
|
+
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.
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
### 1. Installation
|
|
11
10
|
|
|
12
|
-
|
|
11
|
+
Start by installing the OLC React SDK via [NPM](https://www.npmjs.com/package/@openlettermarketing/olc-react-sdk).
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
```Shell
|
|
14
|
+
npm install @openlettermarketing/olc-react-sdk
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
### 2. Importing and Initializing the SDK
|
|
18
|
+
|
|
19
|
+
After installation, import the SDK into your React application and configure the required properties to initialize the `TemplateBuilder` component.
|
|
15
20
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
### Complete coverage usage:.
|
|
22
|
+
The following example shows the demo of all props minimalist usage, For the real case integration, see [integration example](#6-real-case-of-usage).
|
|
23
|
+
|
|
24
|
+
```Javascript
|
|
25
|
+
import TemplateBuilder from '@openlettermarketing/olc-react-sdk';
|
|
26
|
+
|
|
27
|
+
const templateBuilderProps = {
|
|
28
|
+
container: document.getElementById('element-id'),
|
|
29
|
+
secretKey: 'your-secret-key',
|
|
30
|
+
basicAuthUsername: 'your-username',
|
|
31
|
+
basicAuthPassword: 'your-password',
|
|
32
|
+
platformName: 'Your Platform Name',
|
|
33
|
+
createTemplateRoute: '/create-template',
|
|
34
|
+
templateBuilderRoute: '/edit-template',
|
|
35
|
+
olcTemplate: yourTemplateObject,
|
|
36
|
+
sandbox: true,
|
|
37
|
+
onReturnAndNavigate () {
|
|
38
|
+
// TODO: Define what happens when the user returns and navigates.
|
|
24
39
|
},
|
|
25
|
-
|
|
40
|
+
async onGetOneTemplate (payload) => {
|
|
41
|
+
// TODO: Fetch a specific template.
|
|
42
|
+
},
|
|
43
|
+
async onGetTemplates (payload) => {
|
|
44
|
+
// TODO: Fetch all templates.
|
|
45
|
+
},
|
|
46
|
+
async onGetCustomFields () => {
|
|
47
|
+
// TODO: Fetch custom fields for the templates.
|
|
48
|
+
},
|
|
49
|
+
async onSubmit (payload) => {
|
|
50
|
+
// TODO: Handle the submission of a template.
|
|
51
|
+
},
|
|
52
|
+
styles: {
|
|
53
|
+
root: {
|
|
54
|
+
// Custom CSS properties for the root element.
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
TemplateBuilder(templateBuilderProps);
|
|
26
60
|
```
|
|
27
61
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
62
|
+
### 3. Configuration through Props
|
|
63
|
+
The SDK uses several properties to manage its behavior. Below is a breakdown of key props:
|
|
64
|
+
|
|
65
|
+
| Prop name | Type | Description | Required | Example / Usage |
|
|
66
|
+
|------------------------|:-----------------|----------------------------------------------------------------------------------------------------------------|----------|:-----------------------------------------------------------|
|
|
67
|
+
| `container` | _HTMLDivElement_ | An HTML DOM element to render the template builder component. | ✓ | `document.getElementById('template-builder-container')` |
|
|
68
|
+
| `secretKey` | _string_ | That key is used to communicate _Polotno_ Editor (Builder) with API requests. | ✓ | `'your-secret-key'` |
|
|
69
|
+
| `basicAuthUsername` | _string_ | _Username_ for basic authentication. | ✓ | `'your-username'` |
|
|
70
|
+
| `basicAuthPassword` | _string_ | _Password_ for basic authentication. | ✓ | `'your-password'` |
|
|
71
|
+
| `platformName` | _string_ | The name of your platform. | ⤫ | `'My App'` |
|
|
72
|
+
| `createTemplateRoute` | _string_ | The route/path for creating new templates. _(begins with slash `/`)_ | ⤫ | `'/create-template'` |
|
|
73
|
+
| `templateBuilderRoute` | _string_ | The route/path for editing existing templates. _(begins with slash `/`)_ | ⤫ | `'/edit-template'` |
|
|
74
|
+
| `olcTemplate` | _object_ | The template object to be edited or used as a base. | ⤫ | `{ ... }` |
|
|
75
|
+
| `sandbox` | _boolean_ | The sandbox setting can be either true or false. Set to true for demo purposes and false for production. | ⤫ | `true` |
|
|
76
|
+
| `onReturnAndNavigate` | _function_ | An event which triggers when a user navigates away. | ⤫ | `onReturnAndNavigate () { ... }` |
|
|
77
|
+
| `onGetOneTemplate` | _function_ | An event which triggers when fetching a specific template. | ⤫ | `onGetOneTemplate ( payload ) { ... }` |
|
|
78
|
+
| `onGetTemplates` | _function_ | An event which triggers when fetching all templates. | ⤫ | `onGetTemplates ( payload ) { ... }` |
|
|
79
|
+
| `onGetCustomFields` | _function_ | An event which triggers when fetching custom fields for templates. | ⤫ | `onGetCustomFields () { ... }` |
|
|
80
|
+
| `onSubmit` | _function_ | An event which triggers upon template submission. | ⤫ | `onSubmit () { ... }` |
|
|
81
|
+
| `styles` | _object_ | An object of [JSS](https://reactjs.org/docs/faq-styling.html) props for customize styling of template builder. | ⤫ | `{ root: { ... } }` |
|
|
82
|
+
|
|
83
|
+
### 4. API Integration
|
|
84
|
+
To integrate the SDK’s API, ensure that your backend securely communicates with the OLC _Backend_, returning the necessary data to the SDK frontend.
|
|
85
|
+
|
|
86
|
+
### 5. Customization and Styling
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
### 6. Real-case of usage
|
|
90
|
+
Below is an example of how to use the SDK within a React component:
|
|
91
|
+
|
|
92
|
+
```Typescript
|
|
93
|
+
import { useEffect } from 'react';
|
|
94
|
+
|
|
95
|
+
// SDKs
|
|
96
|
+
import TemplateBuilder from '@openlettermarketing/olc-react-sdk';
|
|
97
|
+
|
|
98
|
+
// styles
|
|
99
|
+
import '@blueprintjs/core/lib/css/blueprint.css';
|
|
100
|
+
|
|
101
|
+
const App = () => {
|
|
102
|
+
useEffect(() => {
|
|
103
|
+
TemplateBuilder({
|
|
104
|
+
container: document.getElementById('template-builder-container'),
|
|
105
|
+
secretKey: 'your-secret-key',
|
|
106
|
+
basicAuthUsername: 'your-username',
|
|
107
|
+
basicAuthPassword: 'your-password',
|
|
108
|
+
sandbox: false,
|
|
109
|
+
async onSubmit (payload) {
|
|
110
|
+
console.log('Template submitted:', payload);
|
|
111
|
+
// Implement your submission logic here
|
|
112
|
+
},
|
|
113
|
+
});
|
|
114
|
+
}, []);
|
|
115
|
+
|
|
116
|
+
return (
|
|
117
|
+
<>
|
|
118
|
+
{/** ... */}
|
|
119
|
+
<div id="template-builder-container" />
|
|
120
|
+
</>
|
|
121
|
+
);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export default App;
|
|
125
|
+
```
|