Skip to content
This repository has been archived by the owner on Jul 22, 2020. It is now read-only.

Commit

Permalink
Merge pull request #21 from risker/feature/config-plugins
Browse files Browse the repository at this point in the history
Add ability to register custom twig.js plugins and add docs
  • Loading branch information
Chapabu authored Feb 4, 2019
2 parents 422c238 + e11b172 commit a399e25
Showing 1 changed file with 136 additions and 2 deletions.
138 changes: 136 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Twig Adapter

[WIP] An adapter to let you use [Twig](https://github.com/twigjs/twig.js) templates with [Fractal](http://github.com/frctl/fractal).
An adapter to let you use [Twig](https://github.com/twigjs/twig.js) templates with [Fractal](http://github.com/frctl/fractal).

Currently requires the (unreleased) Fractal v1.1.0-alpha.2 or greater - you can install it in your project using `npm i @frctl/fractal@next --save`.
Requires Fractal v1.1.0 or greater.

To install this adapter run this command:

Expand All @@ -18,3 +18,137 @@ const twigAdapter = require('@frctl/twig')();
fractal.components.engine(twigAdapter);
fractal.components.set('ext', '.twig');
```

## Extending with a custom config
```
/*
* Require the Twig adapter
*/
const twigAdapter = require('@frctl/twig')({
// if pristine is set to true, bundled filters, functions, tests
// and tags are not registered.
// default is false
pristine: false,
// if importContext is set to true, all include calls are passed
// the component's context
// default is false
importContext: false,
// use custom handle prefix
// this will change your includes to {% include '%button' %}
// default is '@'
handlePrefix: '%',
// register custom filters
filters: {
// usage: {{ label|capitalize }}
capitalize: function(str) {
if (!str) return '';
return str.charAt(0).toUpperCase() + str.slice(1);
}
},
// register custom functions
functions: {
// usage: {{ capitalize(label) }}
capitalize: function(str) {
if (!str) return '';
return str.charAt(0).toUpperCase() + str.slice(1);
}
},
// register custom tests
tests: {
// usage: {% if label is equalToNull %}
equalToNull: function(param) {
return param === null;
}
},
// register custom tags
tags: {
flag: function(Twig) {
// usage: {% flag "ajax" %}
// all credit to https://github.com/twigjs/twig.js/wiki/Extending-twig.js-With-Custom-Tags
return {
// unique name for tag type
type: "flag",
// regex match for tag (flag white-space anything)
regex: /^flag\s+(.+)$/,
// this is a standalone tag and doesn't require a following tag
next: [ ],
open: true,
// runs on matched tokens when the template is loaded. (once per template)
compile: function (token) {
var expression = token.match[1];
// Compile the expression. (turns the string into tokens)
token.stack = Twig.expression.compile.apply(this, [{
type: Twig.expression.type.expression,
value: expression
}]).stack;
delete token.match;
return token;
},
// Runs when the template is rendered
parse: function (token, context, chain) {
// parse the tokens into a value with the render context
var name = Twig.expression.parse.apply(this, [token.stack, context]),
output = '';
flags[name] = true;
return {
chain: false,
output: output
};
}
};
}
}
});
```


## Using external plugins

An example to use [twig-js-markdown](https://github.com/ianbytchek/twig-js-markdown):
```
const twigMarkdown = require('twig-markdown');
const instance = fractal.components.engine(twigAdapter);
// instance.twig refers to the twig.js instance
instance.twig.extend(twigMarkdown);
```

## Included filters

### path
Takes a root-relative path and re-writes it if required to make it work in static HTML exports.

It is strongly recommended to use this filter whenever you need to link to any static assets from your templates.

The path argument should begin with a slash and be relative to the web root. During a static HTML export this path will then be re-written to be relative to the current page.

Usage:
```
{{ '/css/my-stylesheet.css'|path }}
```

## Included tags

### render
The render tag renders a component (referenced by its handle) using the context data provided to it. If no data is provided, it will use the context data defined within the component's configuration file, if it has one.

Usage:
```
{% render "@component" with {some: 'values'} %}
```

0 comments on commit a399e25

Please sign in to comment.