listelixr-js v1.0.0-beta.4

ListElixr Subscribe Form

This is a widget that allows clients to embed a form on their website to automatically create subscriptions in ListElxir. The OAuth access token must be generated by an administrator. Once the access token has been generated, copy/paste the JavaScript code. This plugin is highly customizable, so the form can look however you desire.

Basic Usage

https://unpkg.com/listelixr-js@VERSION/dist/ListElixr.umd.cjs

Note, where VERSION is, it must be various formats such as ^1.0 ~1.0 1.0.5. It's best to lock into a hard version on client sites because that version will work indefinitely and updates wont impact it.

<script src="https://unpkg.com/listelixr-js@1.0.0-beta.4/dist/ListElixr.umd.cjs"></script>

<script>
var el = document.querySelector('#foo');
var key = 'the-access-token-goes-here';

ListElixr.subscribeForm(el, {
    key: key,
    tags: ['foo', 'bar'], // optional
    source: 'XXXXX', // optional
    channel: 'YYYYY', // optional
    fields: ['email', 'first', 'last']
});
</script>

Available Fields

The following are the standard fields:

email, first, last, street, city, state, zip, and phone.

The order of the fields determine the order they appear in the form. Should you need to provide custom html structure for the fields, you may also pass an HTMLElement that contains an input field with one of the accepted field names.

Customizeable Themes

The following will extend the default theme. You could create an entirely new theme from scratch, but this example just shows how to override the submit button color. Should you run into style conflicts, you could add !important or whatever you need to fix the conflicting styles.

Note, the theme syntax is CSS-in-JS or (JSS) syntax.

<script src="https://unpkg.com/listelixr-js@1.0.0-beta.4/dist/ListElixr.umd.cjs"></script>

<script>
var el = document.querySelector('#foo');
var key = 'the-access-token-goes-here';
var theme = ListElixr.defaultTheme.merge({
    'button': {
        backgroundColor: 'red',

        '&:active': {
            background: 'darkred,'
        },

        '&:focus': {
            boxShadow: '0px 0px 0px 3px rgb(255, 0, 0, .5)',
        }
    }
});

ListElixr.subscribeForm(el, {
    key: key,
    theme: theme,
    fields: ['email', 'first', 'last']
});
</script>

Creating a Custom Theme

It's generally advised to start from the base theme, which is only a reset stylesheet. This will ensure everything renders correctly across different browsers.

<script src="https://unpkg.com/listelixr-js@1.0.0-beta.4/dist/ListElixr.umd.cjs"></script>

<script>
var el = document.querySelector('#foo');
var key = 'the-access-token-goes-here';

var theme = ListElixr.base.merge({
    'button': {
        // your button css here
    },
    'input, select, textarea': {
        // your form field css here
    }
});

ListElixr.subscribeForm(el, {
    key: key,
    theme: theme,
    fields: ['email', 'first', 'last']
});
</script>

Access Tokens

Each access token is scoped to a catalog id. This ensures users can only be subscribed to a predetermined catalog, and can never be determined by the request body. To generate an access token, you must know the CLIENT_ID and CLIENT_SECRET of the ListElixr Client Credentials Grant.

Run the following command on the Elxir server. Be sure to replace CLIENT_ID CLIENT_SECRET AND CATALOG_ID with the actual values. The scope client-api is also required.

php artisan passport:client:access-token
    --id=CLIENT_ID
    --secret=CLIENT_SECRET
    --scope="catalog-CATALOG_ID client-api"

Variables

CLIENT_ID is the OAuth Client ID. \ CLIENT_SECRET is the secret value for the given CLIENT_ID \ CATALOG_ID is the id of the catalog you wish to subscribe users.