https://github.com/posthtml/posthtml-extend
Template extending (Jade-like)
https://github.com/posthtml/posthtml-extend
posthtml
Last synced: 6 months ago
JSON representation
Template extending (Jade-like)
- Host: GitHub
- URL: https://github.com/posthtml/posthtml-extend
- Owner: posthtml
- License: mit
- Created: 2015-12-25T16:26:13.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-03-15T01:23:23.000Z (almost 3 years ago)
- Last Synced: 2024-10-29T21:06:04.989Z (over 1 year ago)
- Topics: posthtml
- Language: JavaScript
- Size: 1.52 MB
- Stars: 46
- Watchers: 5
- Forks: 9
- Open Issues: 10
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/funding.yml
- License: license
Awesome Lists containing this project
README
# posthtml-extend [](http://badge.fury.io/js/posthtml-extend) [](https://travis-ci.org/posthtml/posthtml-extend)
[PostHTML](https://github.com/posthtml/posthtml) plugin that allows a template to extend (inherit) another templates ([Jade-like](http://jade-lang.com/reference/inheritance/)).
## Usage
Let's say we have a base template:
`base.html`
```xml
— Github
footer content
```
Now we can inherit this template. All defined blocks inside `` will
replace the blocks with the same name in the parent template. If the block is not
defined inside `` its content in the parent template remains the same.
In the example the blocks `title` and `content` will be replaced and
the block `footer` will remain unchanged:
```js
var posthtml = require('posthtml');
var html = `
How to use posthtml-extend
Read the documentation
`;
posthtml([require('posthtml-extend')({
encoding: 'utf8', // Parent template encoding (default: 'utf8')
root: './' // Path to parent template directory (default: './')
})]).process(html).then(function (result) {
console.log(result.html);
});
```
The final HTML will be:
```xml
How to use posthtml-extend
Read the documentation
footer content
```
### Append/prepend
It's also possible to append and prepend block's content:
```js
var posthtml = require('posthtml');
var html = `
How to use posthtml-extend
Read the documentation
— 2016
`;
posthtml([require('posthtml-extend')()]).process(html).then(function (result) {
console.log(result.html);
});
```
The final HTML will be:
```xml
How to use posthtml-extend — Github
Read the documentation
footer content — 2016
```
### Pass data to layouts
In addition to normal html content you can also pass data as a json object to your layout file. To do this add a `locals` attribute to your `` and pass a json string.
Like this:
```js
var posthtml = require('posthtml');
var html = `
Read the documentation
`;
posthtml([require('posthtml-extend')()]).process(html).then(function (result) {
console.log(result.html);
});
```
Now you can easily access your data inside of your `base.html`:
```xml
How to use posthtml-extend — Github
```
The final HTML will be:
```xml
How to use posthtml-extend — Github
Read the documentation
```
This behaviour can be customized with the option [`expressions`](#expressions).
## Options
### encoding
Type: `string`\
Default: `utf8`
The encoding of the parent template.
### plugins
Type: `array`\
Default: `[]`
You can include [other PostHTML plugins](http://posthtml.github.io/posthtml-plugins/) in your templates.
Here is an example of using [posthtml-expressions](https://github.com/posthtml/posthtml-expressions), which allows to use variables and conditions:
```js
var posthtml = require('posthtml');
var options = {
plugins: [
require('posthtml-expressions')({ locals: { foo: 'bar'} })
]
};
var html = `
content value foo equal bar
value foo not equal bar
`;
posthtml([require('posthtml-extend')(options)]).process(html).then(function (result) {
console.log(result.html);
});
```
The final HTML will be:
```xml
How to use posthtml-extend — Github
content value foo equal bar
footer content — 2016
```
### root
Type: `string`\
Default: `./`
The path to the root template directory.
### strict
Type: `boolean`\
Default: `true`
Whether the plugin should disallow undeclared block names.
By default, the plugin raises an exception if an undeclared block name is encountered. This can be useful for troubleshooting (i.e. detecting typos in block names), but
there are cases where "forward declaring" a block name as an extension point for downstream templates is useful, so this restriction can be lifted by setting the `strict`
option to a false value:
```js
const extend = require('posthtml-extend');
const root = './src/html';
const options = { root, strict: false };
posthtml([extend(options)]).then(result => console.log(result.html));
```
### slot/fill
Type: `string`\
Default: `block`
Tag names used to match a content block with a block for inserting content.
`base.html`
```xml
— Github
footer content
```
```js
var posthtml = require('posthtml');
var html = `
How to use posthtml-extend
Read the documentation
`;
posthtml([require('posthtml-extend')({
slotTagName: 'slot',
fillTagName: 'fill'
})]).process(html).then(result => console.log(result.html));
```
The final HTML will be:
```xml
How to use posthtml-extend
Read the documentation
footer content
```
### tagName
Type: `string`\
Default: `extends`
The tag name to use when extending.
```js
var posthtml = require('posthtml');
var html = `
Using a custom tag name
Read the documentation
`;
posthtml([require('posthtml-extend')({
tagName: 'layout',
})]).process(html).then(result => console.log(result.html));
```
The final HTML will be:
```html
Using a custom tag name
Read the documentation
footer content
```
### expressions
Type: `object`\
Default: `{}`
This option accepts an object to configure `posthtml-expressions`.
You can pre-set locals or customize the delimiters for example.
Head over to the [full documentation](https://github.com/posthtml/posthtml-expressions#options) for information on every available option.