Roosevelt

API

• teddy.getTemplates(): Get the internal cache of templates.

• teddy.setTemplate(name, template): Add a new template to the template cache.

• teddy.clearTemplates(): Clear the template cache.

• teddy.render(template, model, options): Render a template by supplying either source code or a file name (in Node.js).

  • Returns fully rendered HTML.
  • Removes <!--! teddy comments --> and {! teddy comments !}
  • options is optional, and applies to this render alone: verbosity, emptyVarBehavior, and cache, which mean the same as teddy.setVerbosity, teddy.setEmptyVarBehavior, and teddy.setCacheTemplates. E.g. teddy.render(template, model, { emptyVarBehavior: 'hide' }).
  • A callback can be passed after options, or in place of them, as Express does; it's called with (err, html).

• teddy.renderFragment(template, model, options): Render a template into a DocumentFragment rather than a string, ready to insert into the page. Only where there's a DOM, such as in the browser.

  • An element written with a ref attribute is handed back by name in the fragment's refs, with the attribute taken off, so you have the elements you need without querying for them. E.g. for <button ref="ok">OK</button>, fragment.refs.ok is the button.
  • A ref names one element. If more than one has the same name, refs holds the first of them.

• teddy.check(template): Compile a template, by source code or name, without rendering it, and return an array of what's wrong with it: the warnings Teddy would otherwise print, each naming the template, or an empty array if there's nothing. Nothing is printed. A build step can run this over its templates and fail on anything it returns.

  • Only what can be told from the template alone is reported. What depends on a model, such as a loop over something the model doesn't have, is reported when the template is rendered.

• teddy.setTemplateRoot(path): Set the location of your templates directory. Default is the current directory.

• teddy.compile(templateString): Takes a template string and returns a function which when given model data will render HTML from the template and model data.

  • Example:

    const templateFunction = teddy.compile('<p>{hello}</p>')
    templateFunction({ hello: 'world' }) // returns "<p>world</p>"

• teddy.setVerbosity(n): Sets the level of verbosity in Teddy's console logs. Call teddy.setVerbosity(n) where n equals one of the below values to change the default:

  • 0 or 'none': No logging.
  • 1 or 'concise': The default. Concise logging. Will usually only log serious errors.
  • 2 or 'verbose': Verbose logging. Logs even minor errors.
  • 3, 'debug', or 'DEBUG': Debug mode. Very verbose.

• teddy.setDefaultParams(): Reset all params to default.

• teddy.setEmptyVarBehavior('hide'): Will make it possible for variables which don't resolve to display as empty strings instead of displaying the variable. Default: 'display'.

  • {varName|h} to force it to hide or {varName|d}

• teddy.setIncludeNotFoundBehavior('hide'): Will make it possible for <include> tags which don't resolve to display as empty strings instead of displaying an error. Default: 'display'.

• teddy.setCacheTemplates(true): Keep templates read from the filesystem in memory rather than reading them again on the next render. Default: false.

  • Caching is off by default so that editing a template takes effect without restarting, which is how ejs and pug treat their own caching too.
  • You can also set this per render by passing cache in the model, e.g. teddy.render(template, { cache: true }). That takes precedence over this setting.
  • When Teddy is used as an Express view engine you do not need to set any of this: Express supplies its own view cache setting, which it enables in production and disables in development, and Teddy uses it. An explicit cache in the model still wins.
  • Templates registered with teddy.setTemplate are not affected. Those are always kept, and kept compiled, since registering one by hand is the only way to supply a template in the browser, where there is no filesystem to read from, and registering new markup under a name replaces what was compiled for it.