@bigbinary/neeto-message-templates-frontend

neeto-message-templates-nano

The neeto-message-templates-nano manages message templates across the neeto products. As of now, it supports the creation of SMS, Email and Whatsapp templates. The nano exports the @bigbinary/neeto-message-templates-frontend NPM package and neeto-message-templates-engine Rails engine for development.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Components
2. Instructions for Publishing

Development with Host Application

Engine

The engine is used to manage message templates across neeto products.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-message-templates-engine'
   end

2. And then execute:

   bundle install

3. Add this line to your application's config/routes.rb file:

   mount NeetoMessageTemplatesEngine::Engine, at: "/neeto_message_templates"

4. Run the following command to copy the migrations from the engine to the host application:

   bundle exec rails neeto_message_templates_engine:install:migrations

5. Add the migrations to the database:

   bundle exec rails db:migrate

6. Create file neeto-message-templates.rb under config/initializers to provide the owner_class information

   NeetoFormEngine.owner_class = "Organization"

7. Add the permission neeto_message_templates_engine.manage_message_templates to your permissions.yml file.

8. Configure the owner model in the host application.

   has_many :message_templates, as: :owner, class_name: "NeetoMessageTemplatesEngine::MessageTemplate", dependent: :destroy

Usage

You can learn more about usage here:

1. Models

Frontend package

Installation

1. Install the latest neeto-message-templates-nano package using the below command:

   yarn add @bigbinary/neeto-message-templates-frontend

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Components

MessageTemplates (source code)

This component is used to manage message templates in your web application. It provides a user-friendly interface for viewing, adding, and editing templates, along with filtering and search capabilities.

Props

• shouldIncludeTestTemplate: A boolean indicating whether the test message template option should be included.
• handleSubmitTestTemplate: The function in the host app responsible for submitting values to send test templates for email and SMS.
• isTestMessageLoading: A boolean indicating whether the test template handle submit is in a loading state.
• type: Represents the type of message, with accepted values of email, sms, or whatsapp.

Optional Props

• templateVariables: (optional) To add dynamic variables to form body field.
• ownerId: (optional) To provide the ID of the owner if it is not an Organization model. If the owner is an Organization, this prop can be left unspecified.
• breadcrumbs: An array of objects that specify breadcrumbs for navigation.
• isTestingTemplateDisabled: A boolean indicating whether the test template button should be enabled or not.
• manageTemplatesPaneCustomFields: To add custom components to the manage templates pane.
• customFieldsBelowBody: Adds a custom field component to the manage templates pane and renders it below the body.
• customFieldsInitialValues: To provide initial values for the custom fields.
• customFieldsValidationSchema: To provide validation schema for the custom fields.
• onMutationSuccess: The callback function which is triggered on the success of mutation functions(create, update & delete).
• paneSize: Determines the size of the pane. Defaults to "large". Accepted values are "small", "large", or "extraLarge".
• helpPopoverProps: To add help popover for the component. Refer HelpPopover component doc. NOTE: href from helpLinkProps will be used for displaying the help doc link in NoData component. Header title will be used as the help popover title if no title is provided.
• allowAddingImagesToEmailTemplate:A boolean indicating whether images can be added to the message body for email templates.

Usage

import React from "react";

import { MessageTemplates } from "@bigbinary/neeto-message-templates-frontend";

const App = () => {
  const queryClient = useQueryClient();

  const breadcrumbs = [
    {
      link: "/settings",
      text: "Settings",
    },
  ];
  const handleSubmit = () => {
    //api call
  };

  const TEMPLATE_VARIABLES = [
    {
      key: "name",
      label: "Name",
    },
  ];
  const customFieldsBelowBody = () => (
    <Typography>This will render below body</Typography>
  );

  const manageTemplatesPaneCustomFields = () => (
    <Callout icon={Warning} style="warning">
      Twilio integration is required for sending SMS. Please connect your Twilio
      account.
    </Callout>
  );

  return (
    <MessageTemplates
      allowAddingImagesToEmailTemplate
      shouldIncludeTestTemplate
      breadcrumbs={breadcrumbs}
      handleSubmitTestTemplate={handleSubmit}
      isTestMessageLoading={isTestMessageLoading}
      templateVariables={TEMPLATE_VARIABLES}
      type={type}
      customFieldsBelowBody={customFieldsBelowBody()}
      isTestingTemplateDisabled={isTestingTemplateDisabled}
      manageTemplatesPaneCustomFields={manageTemplatesPaneCustomFields()}
      onMutationSuccess={() =>
        queryClient.invalidateQueries({
          queryKey: ["rules"],
        })
      }
    />
  );
};

SendMessagePane (source code)

This component provides a pane where users can select a template and add content to compose and send messages.

Props

• isOpen: A boolean determining whether the side pane is open.
• onClose: The function to execute when closing.
• handleSubmit: The function within the host app used to send SMS and email.
• type: Represents the type of message, with accepted values of email, sms, or whatsapp.
• paneSize: Determines the size of the pane. Defaults to "large". Accepted values are "small", "large", or "extraLarge".

Optional Props

• customFields: To add custom field component to the pane.
• customFieldsBelowBody: Adds a custom field component to the pane and renders it below the body in EmailAndSms.
• customFieldsInitialValues: To provide initial values for the custom fields.
• customFieldsValidationSchema: To provide validation schema for the custom fields.
• templateVariables: To add dynamic variables to form body field.
• ownerId: To provide the ID of the owner if it is not an Organization model. If the owner is an Organization, this prop can be left unspecified.
• isSaveAsTemplateEnabled - To allow users to save the contents of current message as a new template.
• canManageTemplates - When this is set to false, save as template option won't be displayed to users.
• helpPopoverProps: Props to display HelpPopover next to input fields in EmailAndSms.
• allowAddingImagesToEmail: A boolean indicating whether images can be added to the message body for emails.

Usage

import React, { useState } from "react";

import { SendMessagePane } from "@bigbinary/neeto-message-templates-frontend";

import { EMAIL_SUBJECT_HELP_DOC_URL, SMS_TEMPLATE_HELP_DOC_URL }

const App = () => {
  const [isPaneOpen, setIsPaneOpen] = useState(false);

  const handleSubmit = () => {
    //api call
  };

  const customFields = () => (
    <div className="space-y-4">
      <Input required label="To" name="to" />
      <Input required label="From" name="from" />
    </div>
  );

  const customFieldsBelowBody = () => (
    <div className="space-y-4">
      <Input label="CC" name="cc" placeholder="Enter CC email" />
      <Input label="BCC" name="bcc" placeholder="Enter BCC email" />
      <Input label="Reply To" name="replyTo" placeholder="Enter reply-to email" />
    </div>
  );

  const customFieldsInitialValues = {
    to: "",
    from: "",
    cc: "",
    bcc: "",
    replyTo: "",
  };

  const customFieldsSchema = yup.object().shape({
    to: yup.string().trim().required("To address is required").email("invalid"),
    from: yup
      .string()
      .trim()
      .required("From address is required")
      .email("invalid"),
    cc: yup.string().trim().email("Invalid email"),
    bcc: yup.string().trim().email("Invalid email"),
    replyTo: yup.string().trim().email("Invalid email"),
  });

  const helpPopoverProps = {
    email: {
      subject: {
        helpIconProps: {
          popoverProps: {
            title: "subject",
            helpLinkProps: {
              href: EMAIL_SUBJECT_HELP_DOC_URL,
              label: t("View help article"),
            },
          },
        },
      },
    },
    sms: {
      template: {
        helpIconProps: {
          popoverProps: {
            title: "SMS Templates",
            helpLinkProps: {
              href: SMS_TEMPLATE_HELP_DOC_URL,
              label: t("View help article"),
            },
          },
        },
      },
    },
  };

  return (
    <SendMessagePane
      allowAddingImagesToEmail
      handleSubmit={handleSubmit}
      isOpen={isPaneOpen}
      paneSize="extraLarge"
      type={type}
      onClose={() => setIsPaneOpen(false)}
      customFields={customFields()}
      customFieldsBelowBody={customFieldsBelowBody()}
      customFieldsInitialValues={customFieldsInitialValues}
      customFieldsValidationSchema={customFieldsSchema}
      helpPopoverProps={helpPopoverProps}
    />
  );
};

ApiTemplates (source code)

This component is used to manage the API templates in your application. It provides the interface to add, delete, and edit API templates, along with filtering and search capabilities.

Props

• ownerId: To provide the ID of the owner to which the API templates belongs to.

Optional props

• breadcrumbs: An array of objects that specify breadcrumbs for navigation.

• onMutationSuccess: The callback function which is triggered on the success of mutation functions(create, update & delete).

• initialPayload: To specify the initial value of the body as an object.

• templateVariables: To add dynamic variables to body field.

• paneSize: Determines the size of the pane. Defaults to "large". Accepted values are "small", "large", or "extraLarge".

• helpPopoverProps - To add help popovers to various sections.

  • Header: Define popover props under apiTemplates. NOTE: href from helpLinkProps will be used for displaying the help doc link in NoData component. Header title will be used as the help popover title if no title is provided.
  • Custom headers: Define popover props under customHeaders.
  • Body: Define popover props under body.

  For more details. For more details, refer to the HelpPopover component documentation.

Usage

import React from "react";

import { ApiTemplates } from "neetomessagetemplates";

const App = () => {
  const queryClient = useQueryClient();

  const breadcrumbs = [{ link: "/settings", text: "Settings" }];
  const ownerId = "ownerId";

  const HELP_POPOVER_PROPS = {
    apiTemplates: {
      title: "Title for the popover displayed in header",
      description: "Description for the popover displayed in header.",
      helpLinkProps: { href: SEND_TO_API_HELP_DOC_URL },
    },
    customHeaders: {
      title: "Title for custom headers popover",
      description: "Description for custom headers popover.",
      helpLinkProps: { href: CUSTOM_HEADERS_HELP_DOC_URL },
    },
    body: {
      title: "Title for API payload popover",
      description: "Description for API payload popover.",
      helpLinkProps: { href: API_PAYLOAD_HELP_DOC_URL },
    },
  };

  TEMPLATE_VARIABLES = [
    { label: t("form.allAnswers"), key: "all-answers" },
    { label: t("common.formName"), key: "form-name" },
  ];

  return (
    <ApiTemplates
      {...{ breadcrumbs, ownerId }}
      templateVariables={TEMPLATE_VARIABLES}
      onMutationSuccess={() =>
        queryClient.invalidateQueries({ queryKey: ["rules"] })
      }
    />
  );
};

SendToApiPane (source code)

This component provides a pane where users can select an API template and modify it if needed and send the data to the specified HTTP(S) endpoint.

Props

• ownerId: A boolean determining whether the side pane is open.

• onClose: This function will be executed while closing the pane.

• onSubmit: This function will be executed while submitting the form.

• isSubmitting: A boolean to know the form submission status

• canManageTemplates - When this is set to false, save as template option won't be displayed to users.

• templateVariables: To add dynamic variables to body field.

• paneSize: Determines the size of the pane. Defaults to "large". Accepted values are "small", "large", or "extraLarge".

• helpPopoverProps - To add help popovers to various sections in the pane.

  • Pane title: Define popover props under sendToApi.
  • Custom headers: Define popover props under customHeaders.
  • Body: Define popover props under body.

  For more details. For more details, refer to the HelpPopover component documentation.

Usage

import React, { useState } from "react";

import { SendToApiPane } from "@bigbinary/neeto-message-templates-frontend";

const App = () => {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSendToApiPaneOpen, setIsSendToApiPaneOpen] = useState(false);

  const ownerId = "ownerId";

  const HELP_POPOVER_PROPS = {
    sendToApi: {
      title: "Title for send to API popover",
      description: "Description for send to API popover.",
      helpLinkProps: { href: SEND_TO_API_HELP_DOC_URL },
    },
    customHeaders: {
      title: "Title for custom headers popover",
      description: "Description for custom headers popover.",
      helpLinkProps: { href: CUSTOM_HEADERS_HELP_DOC_URL },
    },
    body: {
      title: "Title for API payload popover",
      description: "Description for API payload popover.",
      helpLinkProps: { href: API_PAYLOAD_HELP_DOC_URL },
    },
  };

  TEMPLATE_VARIABLES = [
    { label: t("form.allAnswers"), key: "all-answers" },
    { label: t("common.formName"), key: "form-name" },
  ];

  const handleSubmit = () => {
    setIsSubmitting(true);
    // API call
    setIsSubmitting(false);
  };

  return (
    <SendToApiPane
      {...{ isSubmitting, ownerId }}
      isOpen={isSendToApiPaneOpen}
      onClose={() => setIsSendToApiPaneOpen(false)}
      onSubmit={handleSubmit}
      helpPopoverProps={HELP_POPOVER_PROPS}
      templateVariables={TEMPLATE_VARIABLES}
    />
  );
};

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.