Skip to content

Latest commit

 

History

History
122 lines (92 loc) · 5.5 KB

api.md

File metadata and controls

122 lines (92 loc) · 5.5 KB
Raw

API

ST.compile(filename[, options])

  • filename <string> The file path of the template to compile.
  • options <Object>
    • syncOnly <boolean> If true, the compiled template will not support an asynchronous features, and it will return a string instead of an async iterator. Default: false.
    • load <Function> This option allows you to override how template files are loaded. It should be an async function that takes a string (e.g., a file path or URL) and returns the string contents of the file. By default, fs.readFile is used.
    • resolve <Function> This option allows you to override how included template paths are interpretted. It should be an async function that takes a string (as found within expressions like {{> "string"}}) and returns the string which will be passed to load(). The function's second argument will be the string that was used to load the current template file, where the {{> "string"}} was found. By default, these strings are interpreted as file paths.
  • Returns: <Promise<string>>

Compiles a template file, and returns the compiled template as a string. Compiling templates can be slow, so it's recommended to cache compiled templates, rather than re-compiling each time you need to execute them.

const compiledTemplate = await ST.compile('./my-template.html');

If there's a syntax error in your template, a SourceError will be thrown. If you catch it, you can call console.log(error.print()) to display a pretty error message that shows the offending source code in your template.

try {
    const compiledTemplate = await ST.compile('./my-template.html');
} catch (err) {
    if (err.name === 'SourceError') {
        console.log(err.print());
    } else {
        throw err;
    }
}

An example of overriding the resolve and load functions

In this example, template files are loaded from the web, instead of the filesystem.

const compiledTemplate = await ST.compile('http://example.com/template.html', {
    resolve(includeString, resolveFrom) {
        return new URL(includeString, resolveFrom).toString();
    },
    async load(url) {
        const response = await fetch(url);
        return response.text();
    },
});

ST.create(compiledTemplate[, helpers])

  • compiledTemplate <string> A compiled template string.
  • helpers <Object> An object whose key-value pairs will be accessible as variables in scope when the template executes. This is useful for providing reusable functions that can be used anywhere within a template.
  • Returns: <Function>

Creates an executable template function. The template function returns an async iterator which outputs strings as the template executes.

const template = ST.create(compiledTemplate);

for await (const str of template()) {
    process.stdout.write(str);
}

If the syncOnly option was used when the template was compiled, the template function will instead return a string (the entire output):

const template = ST.create(compiledTemplate);

console.log(template());

Passing parameters to templates

If the template requires any parameters, you can pass them as an object (of key-value pairs) to the template function.

{{let name}}
<html>
    <head>
        <title>Welcome to my site!</title>
    </head>
    <body>
        My name is {{name}}.
    </body>
</html>

const template = ST.create(compiledTemplate);

const parameters = {
    name: 'Josh',
};

for await (const str of template(parameters)) {
    process.stdout.write(str);
}

ST.escape(rawString)

Transforms the given string so that HTML/XML special characters are escaped.