robthebuilder
v0.5.1
Published
A service that handles templating over JSON-RPC
Downloads
3
Readme
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 advertiserobthebuilder
topostmaster-addr
: address to reach postmaster instance(s)templates-dir
: directory to load templates fromaddl-methods-dir
: directory to load additional methods fromfrom-email
: default thefromEmail
param to this valuefrom-name
: default thefromName
param 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-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 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 sameuniqueID
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.