Robthebuilder NPM

robthebuilder

JSON-RPC service compiles and renders templates. It can also forward templates to an instance of postmaster to send an email.

Command-line Options

rpc-port: the port to listen for rpc calls on. Defaults to a random port between 8000-9999.
skyapi-addr: address of SkyAPI server to advertise robthebuilder to
postmaster-addr: address to reach postmaster instance(s)
templates-dir: directory to load templates from
addl-methods-dir: directory to load additional methods from
from-email: default the fromEmail param to this value
from-name: default the fromName param to this value
logger: change the default logging class (defaults to debuglog)
log-level: change the log level (defaults to info)

Advertising to SkyAPI is optional. Using postmaster is also optional.

modulelog is used for logging. This allows you to npm install your own logging library and pass the name to --logger.

Templates

Templates are compiled using lodash's _.template. Additional metadata in JSON format can be sent at the top of the template file in order to require params and nest templates. An example metadata block:

<!--
{
    "parent": {
        "name": "generic_base",
        "args": {"showFooter": false},
        "include_var": "body"
    },
    "params": [
        "cardLast4",
        "totalAmount"
    ]
}
-->

parent defines the parent template to load. The current template is rendered and then passed to the parent template as the include_var variable. You can also pass additional arguments to the parent.

params defines the required params that must be sent to this template in order to render it. The above example requires cardLast4 and totalAmount to be sent. Additionally, you'll have access to the escape function in order to escape params that are passed in.

For the above metadata example, the parent might look like:

<!--
{
    "params": [
        "body",
        "showFooter"
    ]
}
-->
<!DOCTYPE html><html><body>
<%= body %>
<% if (showFooter) { %>
<p> footer </p>
<% } %>
</body></html>

You can also specify a subject for emails in the template:

<!--
{
    "params": [
        "name"
    ],
    "subject": "Welcome Email"
}
-->

and if a subject is NOT sent with RenderAndEmail then it will use the one provided by the template.

RPC Methods

Rob.Render

Arguments:

name: (string) name of the template to render
params: (object) params to send to the template

Response:

{html: "<!DOCTYPE html><html><body>..."}

Rob.RenderAndEmail

Arguments:

name: (string) name of the template to render
params: (object) params to send to the template
toName: (optional string) name of the recipient
toEmail: (string) address to send the email to
subject: (optional string) subject of the email. Required unless template specifies a subject.
fromEmail: (optional string) address to send the email from. Required unless --from-email was specified.
fromName: (optional string) name of the sender. To fallback to --from-name don't send this property or send an empty string.
flags: (optional number) flags to pass along to postmaster for categorizing emails
uniqueID: (optional string) uniqueID for this email such as user_15_favorited_user_16. This will be used for duplicate detection.
dupThreshold: (optional number) minimum number of seconds required since the last time an email with the same uniqueID was sent. Dafaults to 0 which means no checking.

toName, toEmail can be sent by defining your own pre-processor using rpclib. You can store toName and toEmail on the response object using the set method and those will be used if toEmail or toName are empty. If you want to only use the pre-processor values, send an empty string for both values. Additionally, a user object can be stored on response and the name property and email property will be used for toName and toEmail, respectively. The user object will also be sent to the template if its not already defined in params. An example pre-processor can be found in tests/pre/pre.js.

In order to prevent accidential duplicate emails, you can send a uniqueID with every email and pass a dupThreshold to prevent an email from being sent twice to the same user in some amount of seconds. The uniqueID should be something unique to the email itself and NOT unique to each individual time its being sent. If you send a dupThreshold but no uniqueID it will be automatically generated by JSON'ing the params and passing that through sha512 and then base64.