1.5.5 • Published 9 months ago

@openlettermarketing/olc-react-sdk v1.5.5

Weekly downloads
-
License
MIT
Repository
github
Last release
9 months ago

Integration Guide

OLC React SDK Integration Guide

Introduction

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.

1. Installation

Start by installing the OLC React SDK via NPM.

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.

Complete coverage usage:.

The following example shows the demo of all props minimalist usage, For the real case integration, see integration example.

import TemplateBuilder from '@openlettermarketing/olc-react-sdk';

const templateBuilderProps = {
  container: document.getElementById('element-id'),
  secretKey: 'your-secret-key',
  publicApiKey: 'your-api-key',
  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);

3. Configuration through Props

The SDK uses several properties to manage its behavior. Below is a breakdown of key props:

Prop nameTypeDescriptionRequiredExample / Usage
containerHTMLDivElementAn HTML DOM element to render the template builder component.document.getElementById('template-builder-container')
secretKeystringThat key is used to communicate Polotno Editor (Builder) with API requests.'your-secret-key'
publicApiKeystringpublicApiKey is used for basic authentication between the OLC and the client platform.'your-api-key'
platformNamestringThe name of your platform.'My App'
createTemplateRoutestringThe route/path for creating new templates. (begins with slash /)'/create-template'
templateBuilderRoutestringThe route/path for editing existing templates. (begins with slash /)'/edit-template'
olcTemplateobjectThe template object to be edited or used as a base.{ ... }
sandboxbooleanThe sandbox setting can be either true or false. Set to true for demo purposes and false for production.true
allowSenderFieldsbooleanThe allowSenderFields prop can be set to either true or false. When set to true, it makes the sender fields visible in the custom fields section.true
allowPropertyFieldsbooleanThe allowPropertyFields prop can be set to either true or false. When set to true, it makes the property fields visible in the custom fields section.true
excludedFieldsstring The excludedFields prop allows you to remove specific fields from the custom fields section by their key['{{C.EMAIL}}','{{SPF.LAST_NAME}}']
templateGalleryModalbooleanThe templateGalleryModal prop can be set to either true or false. When set to false, it disables the template gallery modal and activates the sidebar gallery in the template builder.true
onReturnAndNavigatefunctionAn event which triggers when a user navigates away.onReturnAndNavigate () { ... }
onGetOneTemplatefunctionAn event which triggers when fetching a specific template.onGetOneTemplate ( payload ) { ... }
onGetTemplatesfunctionAn event which triggers when fetching all templates.onGetTemplates ( payload ) { ... }
onGetCustomFieldsfunctionAn event which triggers when fetching custom fields for templates.onGetCustomFields () { ... }
onSubmitfunctionAn event which triggers upon template submission.onSubmit () { ... }
destroyfunctionAn event that destroys the template builder instance and cleans up all associated components and cache. Call this function when unmounting the template builder component to ensure proper cleanup and avoid memory leaks.templateBuilderInstance.destroy()
stylesobjectAn object of JSS 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:

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',
      publicApiKey: 'your-api-key',
      sandbox: false,
      async onSubmit (payload) {
        console.log('Template submitted:', payload);
        // Implement your submission logic here
      },
    });
  }, []);

  return (
    <>
      {/** ... */}
      <div id="template-builder-container" />
    </>
  );
}

export default App;
1.5.5

9 months ago

1.5.4

9 months ago

1.4.0

10 months ago

1.5.3

9 months ago

1.5.2

9 months ago

1.5.1

9 months ago

1.5.0

9 months ago

1.3.2

10 months ago

1.2.0

10 months ago

1.3.1

10 months ago

1.3.0

10 months ago

1.1.0

10 months ago

0.0.41

10 months ago

0.0.40

10 months ago

0.0.39

11 months ago

0.0.38

11 months ago

0.0.37

12 months ago

0.0.36

12 months ago

0.0.35

12 months ago

0.0.34

12 months ago

0.0.32

12 months ago

0.0.31

12 months ago

0.0.30

12 months ago

0.0.29

12 months ago

0.0.28

12 months ago

0.0.27

12 months ago

0.0.26

12 months ago

0.0.25

12 months ago

0.0.24

12 months ago

0.0.23

12 months ago

0.0.22

12 months ago

0.0.21

1 year ago

0.0.20

1 year ago

0.0.19

1 year ago

0.0.18

1 year ago

0.0.17

1 year ago

0.0.16

1 year ago

0.0.15

1 year ago

0.0.14

1 year ago

0.0.12

1 year ago

0.0.11

1 year ago

0.0.10

1 year ago

0.0.9

1 year ago

0.0.8

1 year ago

0.0.7

1 year ago

0.0.6

1 year ago

0.0.5

1 year ago

0.0.3

1 year ago

0.0.2

1 year ago

0.0.1

1 year ago

1.0.0

1 year ago

1.0.5

1 year ago