schablone

Schablone =========

Schablone

(It means template in German)

Jade template rendering service

Templates are jade files that live in our static projects. You point Schablone to the template you'd like to render, give it a context and some locales (in the i18n sense), and it gives you the rendered output.

POST /v1/render

The render endpoint accepts a JSON body which defines the template(s) to be rendered and the context/locale/timezone tuples (referred to as an instance) to be passed to those templates.

You end up with templates * instances output strings.

curl https://api.hubapiqa.com/schablone/v1/render -d '{"templates": {"html": {"project": "MarketingGraderUI", "version": "1.183", "path": "html/home.jade"}}, "instances": [{"context": {"test": 3}, "locale": "de", "timezone": "America/Chicago"}]}' -H 'Content-Type: application/json'
{
  "0": {
    "html": "<header class=\"mg-main large\"><h1><span class=\"hubspot-brand\"><img src=\"//static.hsappstatic.net/MarketingGraderUI/static-1.182/img/hubspot-logo-2x.png\" alt=\"HubSpot\"/></span><span data-i18n='header.brand.possessive' data-i18n-options='{\"noGap\":true}'>'s Marketing Grader</span></h1><h2> <span data-i18n='header.pitch.grade' data-i18n-options='{}'>Grade your marketing.</span> <span class=\"highlight blue\"> <span data-i18n='header.pitch.better' data-i18n-options='{}'>Make it better.</span> </span> <span data-i18n='header.pitch.peers' data-i18n-options='{}'>Outpace your peers.</span> </h2></header><div id=\"grader-form-container\"><form id=\"grader-form\" class=\"hs-form\"><fieldset><div class=\"field url-field\"><div class=\"input-wrapper\"><span style=\"display: none;\" class=\"fake-placeholder\"> <span data-i18n='home.form.url.placeholder' data-i18n-options='{}'>Your website URL</span> </span><input type=\"text\" id=\"url\" name=\"url\" tabindex=\"1\" spellcheck=\"false\" autocapitalize=\"off\" data-hsvalidate=\"required,url\" placeholder=\"Your website URL\" class=\"hs-input has-fake-placeholder\"/></div><p class=\"description\"> <span data-i18n='home.form.url.description' data-i18n-options='{}'>Enter your website address and we'll work up a full report on how you're doing with your marketing online.</span> </p></div><div class=\"field email-field\"><div class=\"input-wrapper\"><span style=\"display: none;\" class=\"fake-placeholder\"> <span data-i18n='home.form.email.placeholder' data-i18n-options='{}'>Your email address</span> </span><input type=\"text\" id=\"email\" name=\"email\" tabindex=\"2\" autocapitalize=\"off\" data-hsvalidate=\"email\" placeholder=\"Your email address\" class=\"hs-input has-fake-placeholder\"/></div><p class=\"description\"> <span data-i18n='home.form.email.description' data-i18n-options='{}'>Enter your email address to receive occasional updates and tips.</span> </p></div><input type=\"checkbox\" id=\"opt_in\" name=\"opt_in\" checked=\"checked\" class=\"hidden\"/><div class=\"form-actions\"><input type=\"submit\" value=\"Grade Me\" tabindex=\"3\" class=\"hs-brand-button blue\"/></div></fieldset></form><div class=\"msg-container\"></div></div><div id=\"sprocket-container\"><div class=\"sprocket gray\"></div><div class=\"sprocket orange\"></div></div>"
  }
}
{
  "templates": Object or Array,
  "instances": Object or Array
}

templates and instances accept either an object with keys which are meaningful to you (the service doesn't care), or an array.

Each item in the templates array or object should be an object with the following keys:

  • project: The name in the static_conf.json of the project containing the template
  • version: A specific build number <major version>.<build number> (i.e. 1.3422), major version (i.e. 1), or identifier (current-qa)
  • path: The path in the static/ directory to the template file

The static_conf.json each project specifies it's "major version", and whether that major version should be considered the "current" version.

Specifying a major version number in the version field will give you the latest successful build that used that version number. Specifying current-qa will give you the latest successful build which specified that it's major version was the "current" version, which is generally the stable branch external consumers should be using.

The current plan is for consuming projects to be locked to a specific version AND build (1.2342) at build-time.

instances is an array or object where each entry is an object with three keys context, locale and timezone.

As with templates, you can pass an object with whatever keys you like (e.g. ids), or an array, in which case the response will use the index of each item in the array.

  • context - An object which will be passed into the jade template as context
  • locale - A locale code (en, de, de-DE, etc.)
  • timezone - A timezone code (America/Chicago, EST, etc.)

The response is an object, with an entry for each instance you passed in. The keys of this object are either the keys you used in the instances object, or the indices in the instances array if it was an array.

Each object contains another object with an entry for each template which was rendered. Similarily, the keys of this object are either the keys you used in the templates object, or the indicies in the templates array if it was an array.

The preview endpoint takes a single template, context and locale and returns it with the text/html Content-Type. This is useful for previewing an HTML template in a browser.

Pass project, version, path, context, timezone and locale as get params. context is JSON, all the other parameters are simple strings:

https://api.hubapiqa.com/schablone/v1/preview?project=EmailTemplateUI&version=edge-qa&path=html/sample.jade&context=%7B%22link%22:%22test%22,%22portalId%22:53%7D&locale=de

When you hit a local Schablone server, the env defaults to local, and the version defaults to static. Specify env=qa if you'd like to hit S3.

Versioned template and locale files are LRU cached as memory allows, they are never explicitly evicted.

The mapping of 'current-qa' or a major version to a specific build is not cached.

The more instances you include in a single request, the better, as loading and parsing the template is the largest part of the rendering time.

For local email testing, see

https://git.hubteam.com/HubSpot/Schablone/tree/master/docs/email_local_testing.md

The cli.coffee program can be executed to do local rendering.

./cli.coffee --project EmailTemplateUI --version current-qa --template 'html/sample.jade' --context '{"link":"test","portalId":53}' 

If the compilation is successful it will exit with code 0 and write the output over stdout. If it fails, it will exit with a non-zero code and a JSON error.

Run ./cli.coffee --help for a full list of options.

schabloneInit = require('schablone')
 
# Init a single time, pass it a callback: 
schabloneInit null(render) ->
 
  # When you're ready to render something: 
  render {templatesinstances}

The object you pass render follows the same format as what gets posted to /v1/render.