ListElixr.js
This library provides simple customizable widgets that perform various actions on ListElixr.
Note: ListElixr is a private API meant only for clients of ActiveEngagement, LLC. This software is not open source or licensed to be used except by ActiveEngagement clients.
Using from a CDN
https://unpkg.com/listelixr-js@VERSION/dist/ListElixr.umd.js
Note, @VERSION is a placeholder and must be a valid format such as ^1.0, ~1.0, 1.0.5. It's best practice to lock into a specific version when using in production to ensure future updates do not break functionality.
<script src="https://unpkg.com/listelixr-js@VERSION/dist/ListElixr.umd.js"></script>Put this at the bottom of your body tag.
<script>
// If you are using the subscribe form
ListElixr.subscribeForm(el, {
// your options here...
});
// If you are using the preference form
ListElixr.preferenceForm(el, {
// your options here...
});
</script>Using from NPM
npm install listelixr-js@VERSIONimport { preferenceForm, subscribeForm } from 'listelixr-js';
// If you are using the subscribe form
subscribeForm(el, {
// your options here...
})
// If you are using the preference form
preferenceForm(el, {
// your options here...
})Subscribe Forms
Subscribe forms allow you to add subscribers.
<script src="https://unpkg.com/listelixr-js@VERSION/dist/ListElixr.umd.js"></script>
<script>
const el = document.querySelector('#foo');
ListElixr.subscribeForm(el, {
key: 'the-access-token-goes-here',
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, phone.
The order of the fields determines the order they appear in the form.
Required Fields
You may also mark the following fields as required:
first, last, street, city, state, zip, phone.
<script>
const el = document.querySelector('#foo');
ListElixr.subscribeForm(el, {
key: 'the-access-token-goes-here',
fields: ['email', 'first', 'last'],
requiredFields: ['first', 'last']
});
</script>Email is always required.
Preference Forms
Preference forms allow existing subscribers to manage their subscriptions for various lists.
<script src="https://unpkg.com/listelixr-js@VERSION/dist/ListElixr.umd.js"></script>
<script>
const el = document.querySelector('#foo');
ListElixr.preferenceForm(el, {
key: 'the-access-token-goes-here'
});
</script>Custom Labels and Descriptions
You may wish to add descriptions or custom labels. Both label and
description are optional.
ListElixr.preferenceForm(document.querySelector('#app1') as Element, {
key: 'b85cbb19-b0c2-49f2-b3b0-7618d008d58e',
fields: {
email: {
label: 'Your Email:'
},
'Daily': {
description: 'Weekdays - Most Popular | <a href="">Sample</a>'
},
'Weekend': {
description: 'Sunday | <a href="">Sample</a>'
},
'ICYMI': {
description: 'Saturday | <a href="">Sample</a>'
},
'Breaking': {
description: 'As needed | <a href="">Sample</a>'
},
'Freedom Post': {
description: 'Twice a week | <a href="">Sample</a>'
},
'Exclusive Offers': {
description: 'Thrice a week | <a href="">Sample</a>'
},
'Marketers': {
description: 'Once a month | <a href="">Sample</a>'
}
}
})Custom Headings
You may also override the heading and/or add a field heading (which is like a
subheader). Both heading and fieldHeading are optional. If nothing is given,
the defaults on the form will be used.
ListElixr.preferenceForm(document.querySelector('#app1') as Element, {
key: 'b85cbb19-b0c2-49f2-b3b0-7618d008d58e',
heading: 'My Custom Heading',
fieldHeading: 'My Custom Subheader'
})Remove the Heading
You may also remove the heading on the form by passing false.
ListElixr.preferenceForm(document.querySelector('#app1') as Element, {
key: 'b85cbb19-b0c2-49f2-b3b0-7618d008d58e',
heading: false
})Themes
The widgets all support CSS-in-JS styling. Alternatively, you may style the widgets using traditional CSS. However, the CSS-in-JS solutions are much easier and provide sensible defaults.
Note: all themes provide CSS scoping and will not conflict with any of the other styles on your site.
Extending the Default Theme
Extending themes allows you to inherit the default styles, while changing only the pieces you desire. For example, this theme will extend the default theme and change the button color to red.
const theme = ListElixr.defaultTheme.extend({
'button': {
background: 'red',
'&:active': {
background: 'darkred'
},
'&:focus': {
boxShadow: '0px 0px 0px 3px rgb(255, 0, 0, .5)',
}
}
});Extending the Base Theme
It's generally advised to start from the base theme, if you are not extending the default theme. The base theme is a reset stylesheet.
const theme = ListElixr.base.extend({
'button': {
// your button css here...
},
'input, select, textarea': {
// your form field css here...
}
});Creating a Custom Theme
However, should you want to start completely from scratch you can still do so.
const theme = ListElixr.theme({
'button': {
// your button css here...
},
'input, select, textarea': {
// your form field css here...
}
});Using Your Theme
Once you create the theme, just pass it to the options of the widget.
const el = document.querySelector('#foo');
// If you are using the subscribe form...
ListElixr.subscribeForm(el, {
key: 'the-access-token-goes-here',
theme,
// your options here...
});
// Or for the preference form...
ListElixr.preferenceForm(el, {
key: 'the-access-token-goes-here',
theme,
// your options here...
});Using Multiple Themes
You may also pass an array of themes if you wish to break the themes up into smaller chunks.
// If you are using the subscribe form...
ListElixr.subscribeForm(el, {
key: 'the-access-token-goes-here',
theme: [
ListElixr.theme({
// define the theme rules here...
}),
ListElixr.theme({
// define the theme rules here...
})
]
});Toggle Switches
Below is an example theme for how to convert checkboxes to toggle switches.
ListElixr.subscribeForm(el, {
key: 'the-access-token-goes-here',
theme: ListElixr.theme({
'[type=checkbox]': {
appearance: 'none',
backgroundColor: '#dfe1e4',
borderRadius: '72px',
borderStyle: 'none',
flexShrink: 0,
height: '24px',
margin: '0',
position: 'relative',
width: '39px',
cursor: 'default',
'&::after': {
backgroundColor: '#fff',
borderRadius: '50%',
content: '""',
height: '1.25rem',
width: '1.25rem',
position: 'absolute',
left: '.125rem',
top: '.125rem',
transition: 'all 100ms ease-out'
},
'&:checked': {
backgroundColor: '#1774ce',
'&::after': {
backgroundColor: '#fff',
left: 'calc(39px - 1.25rem - .125rem)'
},
}
},
})
});