NOT READY FOR PRODUCTION USE
This repository is being moved to monorepo abelljs/abell. You can new release there [email protected].
A template parser that lets you use JavaScript syntax to render loops, conditions, do maths, and require JSONs from HTML. Low level library used in abelljs/abell
🚀 Installation & Usage
Executing directly with npx
npx abell-renderer build --input src/index.abell --output dist/index.htmlor
npm install -g abell-rendererabell-renderer build --input src/index.abell --output dist/index.htmlCheck out Abell Template Guide for how to write .abell files.
📘 Abell Template Guide
.abell files are nothing but .html files which can contain JavaScript inside double curly brackets {{ and }}.
Note that abell-renderer renders abell files in NodeJS context which means you cannot access DOM inside brackets.
Simplest example of .abell file can look like:
{{ const siteTitle = "Abell Demo" }}
<html>
<head>
<title>{{ siteTitle }}</title>
</head>
<body>
{{
const a = 3;
const b = 5;
}}
<h1>{{ siteTitle.toUpperCase() }}</h1>
<div>Addition of {{ a }} and {{ b }} is {{ a + b }}</div>
</body>
</html>All the JavaScript inside curly brakets will be rendered on virtual instance on NodeJS and you will get the output as completely renderer .html file:
<html>
<head>
<title>Abell Demo</title>
</head>
<body>
<h1>ABELL DEMO</h1>
<div>Addition of 3 and 5 is 8</div>
</body>
</html>➿ Loops in Abell
You can use JavaScript Array methods to loop over array. Other JavaScript Array methods like .filter, .map, .reduce can be used as well.
{{
const users = [
{name: 'Saurabh', age: 20},
{name: 'John Doe', age: 78}
]
}}
<main>
{{
users.map(user => `
<div>
<h2>${user.name}</h2>
<span>Age: ${user.age}</span>
</div>
`).join('')
}}
</main>
/*
Ouputs:
<main>
<div>
<h2>Saurabh</h2>
<span>Age: 20</span>
</div>
<div>
<h2>John Doe</h2>
<span>Age: 78</span>
</div>
</main>⤵️ Import JS/JSON/NPM Modules
NOTE: Starting v0.1.10 require() can only be used when allowRequire: true is passed from options or --allow-require flag is passed in CLI
With Abell you can import your Native NodeJS Modules, NPM Modules, JS Files (should export data), and JSON Files with require()
{{ const MarkdownIt = require('markdown-it') }}
<!-- NPM Module to convert markdown to HTML (npm install --save markdown-it) -->
{{ const md = new MarkdownIt(); }}
<!DOCTYPE html>
<html>
<body>
{{ md.render("[Open Google](https://google.com)") }}
</body>
</html>
/*
Outputs:
<!DOCTYPE html>
<html>
<body>
<p><a href="https://google.com">Open Google</a></p>
</body>
</html>
*/Note: fs module or any module that deals with external files cannot be used. The only way to read any external file is require()
💛 JavaScript API
npm install --save-dev abell-rendererconst abellRenderer = require('abell-renderer');
const sandbox = {
nameObjects: [{ name: 'Nice' }, { name: 'very cool' }],
globalMeta: {
siteName: 'Abell Renderer Demo'
}
};
const template = `
<body>
<h1>{{ globalMeta.siteName }}</h1>
<div class="article-container">
{{
nameObjects
.map(content => '<b>' + content.name + '</b>')
.join('');
}}
</div>
</body>
`;
const htmlTemplate = abellRenderer.render(template, sandbox);
console.log(htmlTemplate);
/*
Outputs:
<body>
<h1>Abell Renderer Demo</h1>
<div class="article-container">
<b>Nice</b>
<b>very cool</b>
</div>
</body>
*/🤖 Server-side Rendering with Abell + Express
You can tell express to use Abell as a template engine, check out following example to know how
const express = require('express');
const app = express();
app.engine('abell', require('abell-renderer').engine({ allowRequire: true }));
app.set('views', './views'); // specify the views directory
app.set('view engine', 'abell'); // register the template engine
app.get('/', function (req, res) {
res.render('index', { foo: 'I am coming from server.js' });
});
app.listen(3000, () => {
console.log('Server running on http://localhost:3000');
});Then you can have your index.abell file in views/ directory.
Check out saurabhdaware/abell-ssr-express for full example.
📚 Reference
abellRenderer.render(template, sandbox, options)
template: Abell template in String
sandbox: Object over which the scripts execute, Can define variables and inject them into script.
options.basePath: basePath which is prefixed on require() paths in abellTemplate.
options.allowRequire: Passing true allows using require() in templates. Default is false.
🤗 Contributing
Check out CONTRIBUTING.md for Local Setup Guide, and Contribution Guidelines.
🕑 Changelogs
For status updates you can follow me on Twitter @saurabhcodes