The sendables plugin dynamically generates some HTML and allows users to download it as a PDF or send it in an email.
It will generate the HTML from a template defined within your project and populate it with the data you provide.
To use this plugin, you must have HTML templates and JSON schemas as part of your project, under a
sendables/folder.
For more information, please see the getting started guide for the sendables plugin.
Properties
player.sendables.version : string
The sendables plugin’s version string.
Example
console.log('The sendables plugin version is', player.sendables.version);
Methods
player.sendables.generate(template, context, target, [options]) ⇒ Promise
Generates a PDF/email/SMS given the template, context, and options.
Returns a promise and resolves with a result object.
For more information on the results, see the objects section below.
| Param | Type | Description |
|---|---|---|
| template | string |
Required. The file name (with the extension) of the html template that should be used. |
| context | object |
Required. Data that will be validated against the json schema and will hydrate the template. See the getting started guide for more information. |
| target | object |
Required. An object with the id of a target specified in config.json and any data required for that target. See the getting started guide for more information. |
| target.id | string |
Required. The id of the target specified in the config.json in your project. See the getting started guide for more information. |
| target.data | object |
Required to send an email or an SMS. This is the information necessary to send an email (i.e. recipient, configurable subject line, etc) or a text/SMS message (i.e. phone number) |
| target.data.to | string |
Required to send an email. This is the recipient of the email. (i.e. ‘myEmail@email.com’) |
| [target.data.subject] | object |
Optional. Use this to populate the subject line of your email, if needed. See the getting started guide for more information. |
| target.data.phoneNumber | string |
Required to send a text/SMS message. The recipient’s mobile phone number. |
| [target.data.country] | string |
Optional. For sending a text/SMS message. Provided country code in iso-3166 alpha 2 or 3 format. (e.g. “USA”, “CAN”). This will be used to normalize the phone number and add the “+[COUNTRY_CODE]” prefix if missing. |
| [target.data.senderId] | string |
Optional. For sending a text/SMS message. A custom ID that contains up to 11 alphanumeric characters, including at least one letter and no spaces. The sender ID is displayed as the message sender on the receiving device. For example, you can use your business brand to make the message source easier to recognize. Support for sender IDs varies by country and/or region. For example, messages delivered to U.S. phone numbers will not display the sender ID. For the countries and regions that support sender IDs, see Supported Regions and countries. If you do not specify a sender ID, the message will display a long code as the sender ID in supported countries and regions. For countries or regions that require an alphabetic sender ID, the message displays NOTICE as the sender ID. |
| [options] | object |
Optional. Additional configuration options (i.e. immediately open the link). |
| [options.open] | boolean |
Optional. If true, and if a PDF/HTML page was generated, it will open the link immediately after generation. This utilizes the urls plugin to open the link. |
| [options.target] | string |
Optional. Target attribute. See the urls plugin for more information. |
Example
//////////////////////////////////////
// Generate a link
//////////////////////////////////////
// The following code will hydrate myTemplateName.html with `listItems`,
// and then create a link to the HTML page, and open it in a new tab.
player.sendables.generate(
'myTemplateName.html', // template
{ // context
listItems: [{
name: 'myListItem1',
img: 'myListItem1Image.jpg'
}]
},
{ // target
id: 'myLinkTarget'
},
{
open: true
}
).then((res) => {
console.log(res.data.link);
});
//////////////////////////////////////
// Generate a pdf
//////////////////////////////////////
// The following code will hydrate myTemplateName.html with `listItems`,
// and then generate a PDF file from that page, and create a link to that PDF.
player.sendables.generate(
'myTemplateName.html', // template
{ // context
listItems: [{
name: 'myListItem1',
img: 'myListItem1Image.jpg'
}]
},
{ // target
id: 'myPDFTarget'
}
).then((res) => {
console.log(res.data.link);
});
//////////////////////////////////////////////////////////
// Generate an email with no subject line configuration
//////////////////////////////////////////////////////////
// The following code will hydrate myTemplateName.html with `listItems`,
// and then send an email with that html as the body to usersemail@email.com.
player.sendables.generate(
'myTemplateName.html', // template
{ // context
listItems: [{
name: 'myListItem1',
img: 'myListItem1Image.jpg'
}]
},
{ // target
id: 'myEmailTarget',
data: {
to: 'usersemail@email.com'
}
}
).then((res) => {
console.log(res);
});
/////////////////////////////////////////////////////////
// Generate an email with subject line configuration
/////////////////////////////////////////////////////////
// The following code will hydrate myTemplateName.html with `dynamicListItems`,
// and then send an email to `usersemail@email.com` with that html as the body
// and `dynamicListItems.length` as part of the subject line.
let dynamicListItems = { items: [{ name: 'myListItem1', img: 'myListItem1Image.jpg' }] };
player.sendables.generate(
'myTemplateName', // template
{ // context
listItems: dynamicListItems
},
{ // target
id: 'myEmailWithConfigSubjectTarget',
data: {
to: 'usersemail@email.com',
subject: {
var1: dynamicListItems.length
}
}
}
).then((res) => {
console.log(res);
});
//////////////////////////////////////////////////////////
// Send a text/SMS message to a mobile phone number
//////////////////////////////////////////////////////////
// The following code will hydrate mySMSTemplate.txt
// with a context object that contains a "name" property,
// and then send a text/SMS message with the rendered text
// as message body to the mobile phone number +1 (800) 123-4567.
// This code assumes that a target of type "sms" has been setup in the
// "src/sendables/config.json" file like so:
// {
// "targets" : {
// "mySMSTarget": {
// "type": "sms"
// }
// }
// }
player.sendables.generate(
'mySMSTemplate.txt', // template
{ // context
name: 'Coolio'
},
{ // target
id: 'mySMSTarget',
data: {
phoneNumber: '+18001234567'
}
}
).then((res) => {
console.log(res);
});
Objects
LinkResultSuccess : object
A successful request for a PDF or HTML page will return the following result object.
Example
{
'data': {
'link': 'https://helloek....'
},
'statusCode': 200
}
- LinkResultSuccess :
object- .data :
object- .link :
string
- .link :
- .statusCode :
number
- .data :
linkResultSuccess.data : object
The data associated with the result.
data.link : string
The link to the PDF or HTML page.
linkResultSuccess.statusCode : number
The status code of the request.
EmailResultSuccess : object
A successful request for an email will return the following result object.
Example
{
'data': {},
'statusCode': 200
}
- EmailResultSuccess :
object- .data :
object - .statusCode :
number
- .data :
emailResultSuccess.data : object
The data associated with the result.
emailResultSuccess.statusCode : number
The status code of the request.
ErrorResult : object
If any requests error out, the following result object will be returned.
Example
{
'error': 'Bad Request',
'message': 'Could not find target in config.'
'statusCode': 400
}
- ErrorResult :
object- .error :
string - .message :
string - .statusCode :
number
- .error :
errorResult.error : string
The error that occurred.
errorResult.message : string
The error message associated with the error.
errorResult.statusCode : number
The status code of the request.