Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
djbe committed Jul 29, 2022
1 parent 1a3e081 commit 3940cd5
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 0 deletions.
48 changes: 48 additions & 0 deletions Documentation/tag-import.md
@@ -0,0 +1,48 @@
# Tag: "Import"

This tag loads and executes another template, but will **never** render any output. It's only purpose is for loading [macros](tag-macro.md) and [setting some variables](tag-set.md).

## Node Information

| Name | Description |
|-----------|------------------------|
| Tag Name | `import` |
| End Tag | N/A |
| Rendering | Immediately; no output |

| Parameter | Description |
|------------|--------------------------------------------|
| Template | The name of the template you want to load. |

The template name will depend on how your environment's loader is configured:

- If you're using a file loader, template should be a valid file name.
- If you're using a dictionary loader, template should be a key in that dictionary.

## When to use it

Should be used when you have some [macro](tag-macro.md)s or [set](tag-set.md)s that you want to reuse in multiple templates.

Note that this tag may appear similar to the existing [include](https://stencil.fuller.li/en/latest/builtins.html#include) tag, but the purposes are opposite of each other:

- `include` will render the included template, but never store changes to the context.
- `import` will never render the imported template, but will store changes to the context.

## Usage example

```stencil
{% import "common.stencil" %}
{% call test "a" "b" "c" %}
```

`common.stencil` file:

```stencil
{% macro test a b c %}
Received parameters in test:
- a = "{{a}}"
- b = "{{b}}"
- c = "{{c}}"
{% endmacro %}
```
3 changes: 3 additions & 0 deletions README.md
Expand Up @@ -17,6 +17,9 @@
* [Set](Documentation/tag-set.md)
* `{% set <Name> %}…{% endset %}`
* Renders the nodes inside this block immediately, and stores the result in the `<Name>` variable of the current context.
* [Import](Documentation/tag-import.md)
* `{% import "common.stencil" %}`
* Imports any macro & set definitions from `common.stencil` into the current context.
* [Map](Documentation/tag-map.md)
* `{% map <Variable> into <Name> using <ItemName> %}…{% endmap %}`
* Apply a `map` operator to an array, and store the result into a new array variable `<Name>` in the current context.
Expand Down

0 comments on commit 3940cd5

Please sign in to comment.