add docs

excl-networks · Sep 23, 2022 · 16a387d · 16a387d
1 parent c4f2bcc
commit 16a387d
Show file tree

Hide file tree

Showing 13 changed files with 4,717 additions and 213 deletions.
diff --git a/README.md b/README.md
@@ -15,214 +15,11 @@ _Objective:_
 
 _The objective of ez forms is to have a really simple and fast way to integrate forms with notifications without a lot of setup.  We will be continuing to build features but we are going to keep this plugin simple to setup. Meaning features like server side form validation and heavy customiztations will most likely never be added to this forms plugin. If you need something more customized you should look into making a custom controller._
 
-## Installation
-
-`npm install strapi-plugin-ezforms`
-
-or
-
-`yarn add strapi-plugin-ezforms`
-
-## Configuration
-
-_Use `env('YOUR_SECRET')` if you would like to store secrets in your env_
-
-In your `/config/plugins.js`
-
-```
-ezforms:{
-  config:{
-    captchaProvider: {
-      name: 'your-provider',
-      config: {
-        // captcha provider configuration
-      }
-    },
-    notificationProviders: [
-      {
-        name: 'notificationProvider',
-        enabled: true,
-        config: {
-          // Notification provider configuration
-        }
-      }
-    ]
-  }
-}
-
-```
-
-
-### Example Configuration
-
-```
-ezforms:{
-    config:{
-      captchaProvider: {
-        name: 'recaptcha',
-        config: {
-          secretKey: 'Your Key',
-          minimumScore: 0.5
-        }
-      },
-      enableFormName: true // Optional
-      notificationProviders: [
-        {
-          name: 'email',
-          enabled: true,
-          config: {
-            from: 'Your Email'
-          }
-        },
-        {
-          provider: 'twilio',
-          enabled: true,
-          config: {
-            accountSid: '',
-            authToken: '',
-            from: '',
-          }
-        }
-      ]
-    }
-}
-```
-
-
-#### No Captcha No Notifications (Only DB) Config
-
-```
-ezforms:{
-    config:{
-      captchaProvider: {
-        name: 'none',
-      },
-      notificationProviders: []
-    }
-}
-```
-### Strapi Admin Panel Configuration
-
-After you install this plugin you will see 2 new collections in the admin panel.
-
-#### Form Submissions
-
-This will store all of your form submissions. There are 2 parts to this collection. There is the score section which
-corresponds to the captcha score (if you have captcha disabled it will display -1) The second part is the actual form data in JSON form.
-#### Notification Recipients
-These are all of the people that need to be notified of the submission.
-
-![](https://i.imgur.com/mmxPln2.png)
-
-| key | value |
-| --- | ----------- |
-| Name | String |
-| Email | String |
-| Number | String E164 |
-
-_Number must be in E164 format_
-
-#### Permission Setup
-
-Under `Settings` > `User & Permissions Plugin` > `Roles` 
-
-You can define which roles can submit to the EZ Forms endpoint. If you want anyone to be able to submit select `Public` if you only want authenicated users to submit forms select `Authenticated` Or selected a custom role.
-
-![image](https://user-images.githubusercontent.com/25715982/155970840-38801141-bce8-4a1f-9750-5a7600ccb8cc.png)
-
-## Captcha Providers
-If you would like to not use a Captcha use this configuration
-
-```
-captchaProvider: {
-  name: 'none'
-},
-```
-### Recaptcha
-
-```
-captchaProvider: {
-  name: 'recaptcha',
-  config: {
-    secretKey: 'your-key',
-    minimumScore: 0.5
-  }
-},
-```
-
-## Notification Providers
-
-### Email
-
-This uses Strapi's built-in email plugin to send emails. If that is not setup properly this notification provider will
-not work.
-
-_Note that the from field is required and will not use the Strapi default from_
-
-```
-{
-  name: 'email',
-  enabled: true,
-  config: {
-    subject: "Your Custom Subject", // Optional
-    from: '[email protected]'
-  }
-},
-```
-
-### Twilio
-
-```
-{
-  name: 'twilio',
-  enabled: true,
-  config: {
-    accountSid: 'sid',
-    authToken: 'token',
-    from: '+18005555555',
-  }
-}
-```
-
-## Submitting Data
-
-submit data to the `/api/ezforms/submit/` endpoint (or `/ezforms/submit` if you are not use the `/api/` prefix)
-
-Submit data as a JSON object with this format:
-
-```
-{
-  token: 'your-recaptcha-token',
-  formName: 'Test Form' // Optional, need to set enableFormName to true in your config to attatch this to database record. 
-  formData:{
-    name: 'John Doe',
-    email: '[email protected]'
-    message: 'Hello World'
-  }
-}
-```
-
-Everything within the formData object will be sent as a notification and stored in the database.
-
-### Axios Example
-
-```js
-  let form = {
-      fname: 'John',
-      lname: 'Doe',
-  }
-  let token = 'recaptcha token',
-
-  axios.post('http://localhost:1337/api/ezforms/submit', {token, formData: form})
-    .then((res) => {
-      console.log(res)
-    })
-    .catch((error) => {
-      // error.response.status Check status code
-    }).finally(() => {
-    //Perform action in always
-  });
-```
+## Docs
+
+[Go To Documentation](ezforms.excl.dev)
+
+
 ## Issues
 
 All general issues should be submitted through the [Github issue system](https://github.com/excl-networks/strapi-plugin-ezforms/issues)
@@ -240,8 +37,8 @@ If you find a security issue please do not publicly post it instead send an emai
  - [ ] Add more captcha providers
  - [ ] Add more notification providers
  - [ ] Allow disabling db write
- - [ ] Make emails pretty
- - [ ] Allow providers to be extendable on a per project basis (similar to how email providers work)
+ - [ ] Make emails pretty (see custom formatting)
+ - [x] Allow providers to be extendable on a per project basis (similar to how email providers work)
  - [ ] Allow selection which notifications are sent to which people
  - [ ] Convert to TS
  - [x] Add eslint

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -0,0 +1,35 @@
+export default {
+  title: 'EzForms Docs',
+  description: 'Easily add forms to your website with EzForms',
+  themeConfig: {
+    nav: [
+      {text: 'Getting Started', link: '/getting-started'},
+      {text: 'NPM', link: 'https://www.npmjs.com/package/strapi-plugin-ezforms'},
+      {text: 'Github', link: 'https://github.com/excl-networks/strapi-plugin-ezforms'}
+    ],
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          {text: 'Introduction', link: '/'},
+          {text: 'Getting Started', link: '/getting-started'},
+          {text: 'Configuration', link: '/configuration'},
+          {text: 'Notification Providers', link: '/notification-providers'},
+          {text: 'Captcha Providers', link: '/captcha-providers'},
+          {text: 'Submitting Data', link: '/submitting-data'},
+
+
+        ]
+      },
+      {
+        text: 'Advanced',
+        items: [
+          {text: 'Custom Formatting', link: '/advanced/custom-formatting'},
+          {text: 'Custom Controller', link: '/advanced/custom-controller'},
+          {text: 'Custom Notification Provider', link: '/advanced/custom-notification-provider'},
+
+        ]
+      }
+    ]
+  }
+}
diff --git a/docs/advanced/custom-controller.md b/docs/advanced/custom-controller.md
@@ -0,0 +1,65 @@
+# Custom Controller
+
+EzForms comes with a default controller that handles the form submission. However, if you need more advanced features or form validation you can reuse the EzForms functions so you don't need to rewrite Captcha providers or Notification providers.
+
+## Overriding
+
+You can create a custom controlling by following the instructions in the [official Strapi Docs](Official Strapi Docs)
+
+
+### Captcha Providers
+
+```js
+
+// Call captcha provider function
+
+strapi.plugin('ezforms').service('recaptcha').validate(ctx.request.body.token)
+
+```
+
+Captcha providers will return an object with a valid property
+```js
+// invalid captcha
+return {
+  valid: false,
+  message: 'Missing token',
+  code: 400
+}
+// valid captcha
+return {
+  score: .75,
+  valid: true
+}
+```
+
+### Notification Providers
+
+You can use any of the notification providers that come with EzForms or you can create your own. Each provider takes a config variable which you can view the required data [here](/notification-providers) and data which is the formData.
+
+
+```js
+// Twilio Example
+let config = {
+    accountSid: 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+    authToken: 'your_auth_token',
+    from: '+12345678901',
+}
+let data = {
+    name: 'John Doe',
+    email: '[email protected]'
+}
+
+strapi.plugin('ezforms').service('twilio').send(config, data)
+```
+
+
+### formatData
+
+The formatData function takes the data object and formats it into a string that can be used in a notification.
+
+```js
+strapi.plugin('ezforms').service('formatData').formatData(data)
+```
+
+
+
diff --git a/docs/advanced/custom-formatting.md b/docs/advanced/custom-formatting.md
@@ -0,0 +1,29 @@
+# Custom Formatting
+
+By default ezforms will display data as key value pairs in a pretty format 1 level deep, anything beyond 1 level will use `JSON.stringify()`
+
+
+You can see our `formatData()` function [here](https://github.com/excl-networks/strapi-plugin-ezforms/blob/master/server/services/utils/formatData.js)
+
+## Overriding
+
+To override this function you can create an [extension in your project](https://docs.strapi.io/developer-docs/latest/development/plugins-extension.html#within-the-extensions-folder)
+
+```js
+// ./src/extensions/ezforms/strapi-server.js
+
+module.exports = (plugin) => {
+
+  plugin.services.formatData = () => ({
+    formatData(data) {
+      return "Custom formatData"
+    }
+
+  })
+
+  return plugin;
+};
+
+```
+
+The `data` object is the `formData` object from the request.
diff --git a/docs/advanced/custom-notification-provider.md b/docs/advanced/custom-notification-provider.md
@@ -0,0 +1,36 @@
+# Custom Notification Provider
+
+EzForms comes with first party notification providers but you can setup your own. If you think the notification provider would be useful to others please open a PR.
+
+In your PR simply add your provider to [notification-providers](https://github.com/excl-networks/strapi-plugin-ezforms/tree/master/server/services/notification-providers) then register it with the [services](https://github.com/excl-networks/strapi-plugin-ezforms/blob/master/server/services/index.js) and finally add a section to the [docs](https://github.com/excl-networks/strapi-plugin-ezforms/blob/master/docs)
+
+## Overriding
+
+To override this function you can create an [extension in your project](https://docs.strapi.io/developer-docs/latest/development/plugins-extension.html#within-the-extensions-folder)
+
+```js
+// ./src/extensions/ezforms/strapi-server.js
+
+module.exports = (plugin) => {
+  plugin.services.customNotificationProvider = () => ({
+    async send(config, data) {
+      console.log(config)
+      console.log(data)
+      // access recipient from collection
+      let recipients = await strapi.query('plugin::ezforms.recipient').findMany()
+      // format data
+      let message = strapi.plugin('ezforms').service('formatData').formatData(data)
+      // custom notification logic
+      console.log("Custom notification logic")
+      return true
+    }
+  })
+  return plugin;
+};
+
+
+```
+
+The `data` object is the `formData` object from the request and `config` is the `config` from your Strapi config.
+
+