Overview

This plugin makes it easy to collect email addresses for something like an invite list, launch list or newsletter. It includes a sign-up form component, email confirmation, email follow-up, etc..

It can be easily customized via factor-settings.js and/or you can use its filters to connect new sign-ups with external services.

Installation

To install, just add @factor/plugin-email-list as a dependency to your Factor project.

npm add  @factor/plugin-email-list

Basic Usage

Once installed, this plugin adds a globally available component: <factor-email-list />. You can place this anywhere in your Factor templates you'd like it to show up.

<!-- some-component.vue -->

<template>
  <factor-email-list list-id="default" />
</template>

If you're using a custom list, with settings that are specific for that list, you'll need to add the list-id of the list you're using. More on that in the customization section below.

Options and Settings

The customization system for this plugin is based on the standard factor-settings.js API that is provided by Factor.

Changing Defaults

To start customization, add a key of emailList to the settings file in your app. All you need to do is add your settings in the place of the default ones.

To customize defaults, you can

// app factor-settings.js
export default {
  emailList: {
    default: {
      form: {
        buttonText: "My text",
      },
    },
  },
}

Adding A Custom List (with custom settings)

To use a custom list, add a new root key under emailList, below the ID is customListId. Inside of this add the custom settings, the format should match the default settings.

// app factor-settings.js
export default {
  emailList: {
    customListId: {
      form: {
        buttonText: "My custom list text"
      }
    }
    default: {
      form: {
        buttonText: "My text"
      }
    }
  }
}

Use the component

To use your new custom list just add the list ID to the component:

<!-- some-component.vue -->

<template>
  <factor-email-list list-id="customListId" />
</template>

Disable Emails

If you don't want to use the confirmation emails from this plugin, it's possible to disable one or all of the emails.

To disable a specific email, e.g. the 'complete' email, then just set it to false in factor-settings.

// app factor-settings.js
export default {
  emailList: {
    customListId: {
      emails: {
        complete: false,
      },
    },
  },
}

To disable all emails, set the emails key to false:

// app factor-settings.js
export default {
  emailList: {
    customListId: {
      emails: false,
    },
  },
}

Using with External Services

If you'd like to use this plugin to add emails to external services like email systems or CRM systems, you can easily do that with the email-list-add-[listId] filter.

import { addFilter } from "@factor/api"
addFilter(`plugin-email-list-add-myListId`, (email) => {
  someExternalApi.addEmail(email)

  return email
})