Redirected from /squirrellyjs/squirrelly-docs
Squirrelly

https://github.com/bgub/squirrelly-docs
Admin
Squirrelly is a lightweight, high-performance JavaScript template engine that supports helpers,...
Tokens:10,520
Snippets:118
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Squirrelly with Yarn

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/get-started/install.mdx

Install Squirrelly as a dependency in a Node.js project using Yarn.

```sh
yarn add squirrelly
```

--------------------------------

### Console.log with Native Code Syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/native-code.md

Example of logging to the console using native code syntax. Note the caution: semicolons are needed after calling functions, as shown in the example.

```hbs
{{! console.log("Hi"); }}
```

--------------------------------

### Example of a helper block

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/helpers.md

A concrete example of a helper block with nested blocks and a self-closing helper inside. Demonstrates how to pass parameters and use nested blocks.

```squirrelly
{{@portfolio( {userID: 3838357} )}}
Joe Edrick
{{#tagline}}
Cool Coder Person
{{#hobbies}}
Eating delicious food
{{#img}}
{{@user.img}}
{{/portfolio}}
```

--------------------------------

### Install Squirrelly with npm

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/get-started/install.mdx

Install Squirrelly as a dependency in a Node.js project using npm.

```sh
npm install squirrelly --save
```

--------------------------------

### Filter example with parameters

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/filters.md

Demonstrates basic filters and filters with parameters. The first line pipes 'mystring' through 'reverse' then 'capitalize'. The second line joins the array 'it.someArray' with a comma and space. Filters must be defined before use.

```hbs
{{! /* Basic filters */}}

{{mystring | reverse | capitalize}}

{{! /* With Parameters */}}

{{it.someArray | join(", ")}}
```

--------------------------------

### Self-closing helper example

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/helpers.md

Example of a self-closing helper that includes a partial named 'mypartial'.

```squirrelly
{{@include("mypartial")/}}
```

--------------------------------

### If/Else Helper Example

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/overview.md

Shows how to use the @if, #elif, #else, and /if helpers for conditional logic in a Squirrelly template. The condition checks the value of it.number and outputs different text based on the result.

```squirrelly
{{ @if (it.number === 3) }}
Number is three
{{ #elif (it.number === 4) }}
Number is four
{{ #else }}
Number is five
{{ /if}}
```

--------------------------------

### Use getConfig with custom tags in compileToString

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/configuration.md

Call getConfig with an options object to merge custom settings with the default configuration. Pass the result to compileToString as the second argument. This example sets the tags option to use <% and %> delimiters.

```javascript
Sqrl.compileToString(myTemplate, Sqrl.getConfig({ tags: ["<&", "%>"] }));
```

--------------------------------

### Sqrl.compile example

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/compilation.md

Compiles a template string and invokes the resulting function with data and default config. The compiled function returns the rendered string 'Hi, my name is Johnny Appleseed'.

```js
var myTemplate = "Hi, my name is {{it.name}}";
var compiled = Sqrl.compile(myTemplate);

// Returns a function:
// function anonymous(it,c,cb ) { var tR='';tR+='Hi, my name is ';tR+=c.l('F','e')(it.name);if(cb){cb(null,tR)} return tR }

compiled({ name: "Johnny Appleseed" }, Sqrl.defaultConfig);
//Returns "Hi, my name is Johnny Appleseed"
```

--------------------------------

### Comment with Native Code Syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/native-code.md

Example of a comment written using native code syntax. The comment is placed between the tag delimiters.

```hbs
{{! /* this is a comment */}}
```

--------------------------------

### Define and render a partial with and without data

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/templates.md

Shows how to define a partial with Sqrl.templates.define and render it using the include helper. The first partial outputs static text; the second accepts data via the second argument to include, which can be an object or the it variable to forward all data.

```javascript
Sqrl.templates.define("my-partial", Sqrl.compile("This is a partial speaking"));

Sqrl.render('... {{@include("my-partial")/}}', {});
// ... This is a partial speaking

// To call a partial w/ data:
Sqrl.templates.define("my-partial-2", Sqrl.compile("Name: {{it.name}}"));
Sqrl.render(
  '... {{@include("my-partial", {name: it.name})/}}',
  // The 2nd argument passed to `include` is the data. You could also pass `it` to forward all data
  { name: "Ben" }
);
// ... Name: Ben
```

--------------------------------

### Sqrl.render (async/await)

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/learn/async.md

Renders a template with async support using async/await. The template string can include async helpers, and the render function returns a Promise that resolves to the rendered output.

```APIDOC
## Sqrl.render (async/await)

### Description
Renders a template with async support using async/await. The template string can include async helpers, and the render function returns a Promise that resolves to the rendered output.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
#### Parameters
- **template** (string) - Required - The template string to render.
- **data** (object) - Optional - The data object to pass to the template.
- **options** (object) - Optional - Rendering options.
  - **async** (boolean) - Required - Set to `true` to enable async rendering.
  - **asyncHelpers** (array) - Required - An array of helper names that are async.

### Request Example
```js
const result = await Sqrl.render(
  '{{@async async-test()/}}',
  {},
  { async: true, asyncHelpers: ['async-test'] }
)
```

### Response
#### Success Response
- **result** (string) - The rendered output after async helpers resolve.

#### Response Example
```js
'HI FROM ASYNC'
```

### Error Handling
No error handling documented.
```

--------------------------------

### Sqrl.render (callback)

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/learn/async.md

Renders a template with async support using a callback. The callback receives an error and the rendered result.

```APIDOC
## Sqrl.render (callback)

### Description
Renders a template with async support using a callback. The callback receives an error and the rendered result.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
#### Parameters
- **template** (string) - Required - The template string to render.
- **data** (object) - Optional - The data object to pass to the template.
- **options** (object) - Optional - Rendering options.
  - **async** (boolean) - Required - Set to `true` to enable async rendering.
  - **asyncHelpers** (array) - Required - An array of helper names that are async.
- **callback** (function) - Required - The callback function `(err, res) => void`.

### Request Example
```js
Sqrl.render(
  '{{@async async-test()/}}',
  {},
  { async: true, asyncHelpers: ['async-test'] },
  function (err, res) {
    console.log(res)
  }
)
```

### Response
#### Success Response
- **res** (string) - The rendered output after async helpers resolve.

#### Response Example
```js
'HI FROM ASYNC'
```

### Error Handling
- **err** (Error) - An error object if rendering fails.
```

--------------------------------

### Basic helper block syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/helpers.md

Shows the general structure of a helper block: opening tag with parameters and optional variable list, content, and closing tag. Multiple blocks can be nested inside a helper.

```squirrelly
{{@helpername(parameters) => [var1, var2]}}

Content goes here

{{#helperblock}}

{{/helpername}}
```

--------------------------------

### Load Squirrelly from Unpkg CDN

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/get-started/install.mdx

Load Squirrelly in the browser via the Unpkg CDN. This makes the library available through the global `Sqrl` variable.

```html
<script src="https://unpkg.com/squirrelly"></script>
```

--------------------------------

### Enable/Disable AutoEscaping via Sqrl.defaultConfig.autoEscape

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/auto-escaping.md

Sets the global autoEscape configuration. Set to true to enable (default), false to disable. Comments show the default is on.

```javascript
Sqrl.defaultConfig.autoEscape = true // Turns autoEscaping on
Sqrl.defaultConfig.autoEscape = false // Turns autoEscaping off
// autoEscaping is on by default
```

--------------------------------

### getConfig(config, defaultConfig?)

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/configuration.md

Merges provided configuration options with the default configuration. Optionally accepts a third parameter to merge with the default first. This function is used to obtain a valid config object for lower-level APIs.

```APIDOC
## getConfig(config, defaultConfig?)

### Description
Merges the provided configuration options with the default configuration. Optionally takes a third parameter to merge with the default first. This function is used to obtain a valid config object for lower-level APIs.

### Method
Function call

### Endpoint
`getConfig(config, defaultConfig?)`

### Parameters
#### Parameters
- **config** (object) - Required - Configuration options to merge with the default.
- **defaultConfig** (object) - Optional - Additional configuration to merge with the default first.

### Request Example
```js
Sqrl.getConfig({ tags: ["<%", "%>"] })
```

### Response
#### Success Response
- **config** (object) - The merged configuration object.

#### Response Example
```json
{
  "tags": ["<%", "%>"]
}
```
```

--------------------------------

### Basic reference syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/interpolate.md

Displays the basic syntax for a reference in Squirrelly templates. Place a reference between the default delimiters `{{` and `}}` to output data.

```hbs
{{ reference }}
```

--------------------------------

### Async Include

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/async.md

Includes a partial template asynchronously. The include is invoked with the 'async' keyword and can be used to load partials that require asynchronous processing.

```APIDOC
## Async Include

### Description
Includes a partial template asynchronously. The include is invoked with the 'async' keyword and can be used to load partials that require asynchronous processing.

### Syntax
```
{{@async include("mypartial") /}}
```

### Parameters
- **mypartial** (string) - Required - The name of the partial template to include.

### Example
```
{{@async include("mypartial") /}}
```
```

--------------------------------

### each

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/builtin-helpers.md

Iterates over an array, exposing the current element and index. The variable names for element and index are customizable.

```APIDOC
## each

### Description
Iterates over an array, exposing the current element and index. The variable names for element and index are customizable.

### Usage
```hbs
{{@each(it.somearray) => val, index}}
Display this
The current array element is {{val}}
The current index is {{index}}
{{/each}}
```

### Parameters
- **array** (array) - Required - The array to iterate over.
- **val** (any) - Optional - The current array element. Can be renamed.
- **index** (number) - Optional - The index of the current element. Can be renamed.

### Notes
- Both `val` and `index` are optional and can be renamed. Example: `=> item` or `=> item, number`.
```

--------------------------------

### Sqrl.compile syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/compilation.md

Shows the function signature for Sqrl.compile. The options argument must be a valid config object. The returned function can be called with (data, options, [cb]).

```js
Sqrl.compile (str, options)
// returns a function that can be called with (data, options, [cb])
// note: options must be a valid config object
```

--------------------------------

### File Partials

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/partials.md

File partials are loaded from files and only work in Node.js. They are invoked with the @includeFile helper and do not need to be defined first.

```APIDOC
## File Partials

### Description
File partials are loaded from files and only work in Node.js. They are invoked with the `@includeFile` helper and do not need to be defined first.

### Syntax
```
{{@includeFile('path-to-partial', data) /}}
```

### Example
```handlebars
{{! /* src/partial.sqrl */}}
This is a partial speaking: "My name is {{it.name}}"
```

```js
// src/index.js
Sqrl.render("{{@includeFile('./partial', it) /}}", {
  name: 'Ben',
})

// This is a partial speaking: "My name is {{it.name}}"
```

```

--------------------------------

### Basic filter syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/filters.md

Shows the general syntax for applying a filter to a reference in Squirrelly. Use the pipe character '|' followed by the filter name, and chain multiple filters with additional pipes.

```hbs
{{somereference | somefilter |anotherfilter}}
```

--------------------------------

### Self-closing helper basic syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/helpers.md

Shows the syntax for a self-closing helper, which has no content and is called with parameters only.

```squirrelly
{{@helpername(parameters) /}}
```

--------------------------------

### Load Squirrelly from JSDelivr CDN

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/get-started/install.mdx

Load Squirrelly in the browser via the JSDelivr CDN. This makes the library available through the global `Sqrl` variable.

```html
<script src="https://cdn.jsdelivr.net/npm/squirrelly"></script>
```

--------------------------------

### if/else

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/builtin-helpers.md

Conditional helper that renders content based on a condition. Supports an optional else block.

```APIDOC
## if/else

### Description
Conditional helper that renders content based on a condition. Supports an optional else block.

### Usage
```hbs
{{@if(it.somevalue === 1)}}
Display this
{{#else}}
Display this
{{/if}}
```

### Parameters
- **condition** (expression) - Required - The condition to evaluate. Must be a valid JavaScript expression.

### Notes
- This is a native helper.
- The `#else` block is optional.
```

--------------------------------

### Express.js Integration

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/file-handling.md

Configure Squirrelly as the template engine for Express.js to render .html or .squirrelly files.

```APIDOC
## Express.js Integration

### Description
Set up Squirrelly as the view engine for Express.js to render template files.

### Method
N/A (Configuration)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```js
app.engine('html', require('squirrelly').renderFile)

// Or, if you want to use the .squirrelly file extension

app.set('view engine', 'squirrelly')
```

### Response
N/A
```

--------------------------------

### Sqrl.helpers.define

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/learn/async.md

Defines an async helper function that can be used in templates. The helper returns a Promise that resolves to the value to be rendered.

```APIDOC
## Sqrl.helpers.define

### Description
Defines an async helper function that can be used in templates. The helper returns a Promise that resolves to the value to be rendered.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
#### Parameters
- **name** (string) - Required - The name of the helper, used in templates as `{{@async name()/}}`.
- **fn** (function) - Required - The async function that returns a Promise.

### Request Example
```js
Sqrl.helpers.define('async-test', resolveAfter2Seconds)
```

### Response
#### Success Response
- **undefined** - No return value; the helper is registered for use.

#### Response Example
N/A

### Error Handling
No error handling documented.
```

--------------------------------

### Basic template rendering with Sqrl.render

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/rendering.md

Renders a template string with data. The template uses {{it.name}} to interpolate the 'name' property from the data object. The result is 'Hi, my name is Johnny Appleseed'.

```javascript
var myTemplate = "Hi, my name is {{it.name}}";
Sqrl.render(myTemplate, { name: "Johnny Appleseed" });

//Returns "Hi, my name is Johnny Appleseed"
```

--------------------------------

### Sqrl.compile

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/compilation.md

Compiles a template string into a function that can be called with data and options to render the template. The function returns a string result.

```APIDOC
## Sqrl.compile

### Description
Compiles a template string into a template function that can be called with data and options to render the template.

### Method
compile

### Endpoint
Sqrl.compile(str, options)

### Parameters
#### Parameters
- **str** (string) - Required - The template string to compile.
- **options** (object) - Required - A valid config object. See the options page for details.

### Return Value
Returns a function that can be called with (data, options, [cb]). The function returns a string.

### Example
```js
var myTemplate = "Hi, my name is {{it.name}}";
var compiled = Sqrl.compile(myTemplate);

// Returns a function:
// function anonymous(it,c,cb ) { var tR='';tR+='Hi, my name is ';tR+=c.l('F','e')(it.name);if(cb){cb(null,tR)} return tR }

compiled({ name: "Johnny Appleseed" }, Sqrl.defaultConfig);
//Returns "Hi, my name is Johnny Appleseed"
```

### Notes
Many template engines offer the option to Compile (which just renders your template) or Precompile (which turns your template into a function ahead of time). Squirrelly precompiles automatically, but is still faster than other engines.
```

--------------------------------

### foreach

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/builtin-helpers.md

Iterates over an object's keys and values, exposing the key and value of each child. The variable names for key and value are customizable.

```APIDOC
## foreach

### Description
Iterates over an object's keys and values, exposing the key and value of each child. The variable names for key and value are customizable.

### Usage
```hbs
{{@foreach(it.someobject) => key, val}}
This loops over each of an objects keys and values.
The value of the current child is {{val}}
The current key is {{key}}
{{/foreach}}
```

### Parameters
- **object** (object) - Required - The object to iterate over.
- **key** (string) - Optional - The key of the current object child. Can be renamed.
- **val** (any) - Optional - The value of the current child. Can be renamed.

### Notes
- Both `key` and `val` are optional and can be renamed. Example: `=> item` or `=> item, number`.
```

--------------------------------

### Registered Partials

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/partials.md

Registered partials are defined using Sqrl.templates.define and can be used in both browser and Node.js. They are invoked with the @include helper.

```APIDOC
## Registered Partials

### Description
Registered partials are defined using `Sqrl.templates.define` and can be used in both browser and Node.js. They are invoked with the `@include` helper.

### Syntax
```
{{@include('mypartial', data) /}}
```

### Example
```js
let mypartial = `My name is {{it.name}}`

Sqrl.templates.define('mypartial', Sqrl.compile(mypartial))

Sqrl.render("This is a partial: {{@include('mypartial', it) /}}", {
  name: 'Ben',
})

// This is a partial: My name is Ben
```

```

--------------------------------

### Import Squirrelly in Node.js

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/get-started/install.mdx

Import Squirrelly using ES modules or CommonJS. The library is packaged as a UMD module, so both import styles work.

```js
import * as Sqrl from 'squirrelly'
// or
var Sqrl = require('squirrelly')
```

--------------------------------

### Sqrl.defaultConfig

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/api/configuration.md

Returns the default configuration object for Squirrelly. This is a property that provides access to the default settings.

```APIDOC
## Sqrl.defaultConfig

### Description
Returns the default configuration object for Squirrelly.

### Method
Property access

### Endpoint
`Sqrl.defaultConfig`

### Parameters
None

### Response
#### Success Response
- **config** (object) - The default configuration object.

#### Response Example
```json
{
  "tags": ["{{ ", " }}"]
}
```
```

--------------------------------

### Async Helper

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/async.md

Defines an async helper that can be used in a template. The helper is invoked with the 'async' keyword and can be used to perform asynchronous operations.

```APIDOC
## Async Helper

### Description
Defines an async helper that can be used in a template. The helper is invoked with the 'async' keyword and can be used to perform asynchronous operations.

### Syntax
```
{{@ async helpername(parameters) => var1 }}

{{/helpername}}
```

### Parameters
- **helpername** (string) - Required - The name of the helper.
- **parameters** (any) - Optional - Comma-separated list of parameters passed to the helper.
- **var1** (any) - Required - The variable that will receive the result of the async operation.

### Example
```
{{@ async helpername(parameters) => var1 }}

{{/helpername}}
```
```

--------------------------------

### try-catch

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/builtin-helpers.md

Attempts to execute a block of template code and catches any errors that occur, exposing the error object.

```APIDOC
## try-catch

### Description
Attempts to execute a block of template code and catches any errors that occur, exposing the error object.

### Usage
```hbs
{{@try}}
This won't work: {{ *it.hi | validate}}
{{#catch => err}}

Uh-oh, error! Message was '{{err.message}}'
{{/try}}
```

### Parameters
- **err** (Error) - Required - The error object caught by the catch block.

### Notes
- The `#catch` block is required to handle errors.
```

--------------------------------

### Using the safe flag

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/filters.md

Shows how to disable autoescaping for a reference by appending the 'safe' flag. This is not a true filter but a flag that tells Squirrelly not to autoescape the output.

```hbs
{{myreference | safe}}
```

--------------------------------

### Basic Native Code Tag Syntax

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/native-code.md

The basic syntax for a native code tag in Squirrelly. It inserts the contents directly into the template function.

```hbs
{{! ...  }}
```

--------------------------------

### Async Filter

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/async.md

Applies an async filter to a value in a template pipeline. The filter is invoked with the 'async' keyword and can be used for asynchronous transformations.

```APIDOC
## Async Filter

### Description
Applies an async filter to a value in a template pipeline. The filter is invoked with the 'async' keyword and can be used for asynchronous transformations.

### Syntax
```
{{val | filter1 | async filter2}}
```

### Parameters
- **val** (any) - Required - The input value to be filtered.
- **filter1** (string) - Required - The first filter to apply.
- **filter2** (string) - Required - The second filter, prefixed with 'async' to indicate it is asynchronous.

### Example
```
{{val | filter1 | async filter2}}
```
```

--------------------------------

### Disable Escaping with safe Filter

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/auto-escaping.md

Use the `safe` filter to avoid escaping a specific reference.

```html
{{someref | safe}}
```

--------------------------------

### Disable Escaping with Asterisk Prefix

Source: https://github.com/bgub/squirrelly-docs/blob/main/content/docs/syntax/auto-escaping.md

Use an asterisk after opening delimiters and whitespace control tags to avoid escaping.

```html
{{* someref}}
```

```html
{{_ * someref}}
```
Tokens:
Raw