sendables

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
propertyreadonly

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
method

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.data : object
property

The data associated with the result.

data.link : string
property

The link to the PDF or HTML page.

linkResultSuccess.statusCode : number
property

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.data : object
property

The data associated with the result.

emailResultSuccess.statusCode : number
property

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.error : string
property

The error that occurred.

errorResult.message : string
property

The error message associated with the error.

errorResult.statusCode : number
property

The status code of the request.

Rate this page: X
Tell us more!