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 advertiserobthebuildertopostmaster-addr: address to reach postmaster instance(s)templates-dir: directory to load templates fromaddl-methods-dir: directory to load additional methods fromfrom-email: default thefromEmailparam to this valuefrom-name: default thefromNameparam to this valuelogger: 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 renderparams: (object) params to send to the template
Response:
{html: "<!DOCTYPE html><html><body>..."}
Rob.RenderAndEmail
Arguments:
name: (string) name of the template to renderparams: (object) params to send to the templatetoName: (optional string) name of the recipienttoEmail: (string) address to send the email tosubject: (optional string) subject of the email. Required unless template specifies a subject.fromEmail: (optional string) address to send the email from. Required unless--from-emailwas specified.fromName: (optional string) name of the sender. To fallback to--from-namedon't send this property or send an empty string.flags: (optional number) flags to pass along to postmaster for categorizing emailsuniqueID: (optional string) uniqueID for this email such asuser_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 sameuniqueIDwas 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.