Global look and feel HTML-based templating for Nodejs (expressjs)
pogonophile: an admirer of beards; a student of beards.
Pogon is an HTML-based templating system for Express that's based on Handlebars. It merges html in a view with HTML in a master template resulting in a page with a global look and feel. It is intended for web applications that primarily use server-side rendering.
- Fully-compatible Express template engine
- Familiar syntax: 100% HTML and Handlebars
- Programmer-defined components
- Test mode for easy testing of views
1: Specify the general look and feel in views/template.html:
<!DOCTYPE html>
<html>
<head>
<title>My Awesome Web App</title>
<link rel="stylesheet" href="/stylesheets/style.css">
</head>
<body>
<header><!-- Put in the links, images, ect, that will go into your app's header and navbar --></header>
<pogon_outlet><!-- This is replaced with the custom HTML for the page --></pogon_outlet>
</body>
<footer><!-- More links, copyright, ect --></footer>
</html>2: Define the view for your route in views/myroute.pogon.html:
<!DOCTYPE html>
<html>
<head>
<script src="/javascripts/myroute.js"></script>
</head>
<body>
<h1>My Route</h1>
This is the page that's shown for myroute.html<br />
Some param: <em>{{param}}</em>
</body>
</html>3: Result: ({param: 'replaced by handlebars'})
<!DOCTYPE html>
<html>
<head>
<title>My Awesome Web App</title>
<link rel="stylesheet" href="/stylesheets/style.css">
<script src="/javascripts/myroute.js"></script>
</head>
<body>
<header><!-- Put in the links, images, ect, that will go into your app's header and navbar --></header>
<h1>My Route</h1>
This is the page that's shown for myroute.html<br />
Some param: <em>replaced by handlebars</em>
</body>
<footer><!-- More links, copyright, ect --></footer>
</html>npm install pogon.html
app.set('views', './views') // specify the views directory
app.set('view engine', 'pogon.html') // register the template engine(Expressjs implicitly calls require('pogon.html'))
In your views folder:
- Include template.html
- Name your view files with .pogon.html
Then, in your express router:
router.get('/', async (req, res) => {
// Do something...
res.render('myview', {
option1: someval,
option2: someval
});
// Note that express will look for myview.pogon.html
});const pogon = require('pogon.html');
const mergedHtml = await pogon.render('/path/to/file.pogon.html', {my: 1, options: 2});Template.html can provide a <title> tag in its <head> section. Views can override this title
by providing their own <title> tags in their <head> sections. Pogon will automatically choose
the <title> tag from the view file when specified, or from the template when its missing.
<!DOCTYPE html>
<html pogon-template="overridden_template.html">Now the html file uses overridden_template.html. Useful for configuration pages or situations where a single global template is not enough.
const pogon = require('pogon.html');
pogon.defaultTemplate = "myawesometemplate.html";Useful if you'd like users / customers to provide their own replacement for template.html, or if you just don't like the name "template.html."
Stop struggling to parse your views' HTML just to extract the values sent to the templates. Instead, test mode switches pogon to return descriptive HTML to your tests.
const pogon = require('pogon.html')
describe('My test', () => {
beforeEach(async () => {
pogon.testMode = true;
);
afterEach(async () => {
pogon.testMode = true;
);
it('Test case', async () => {
const response = await server
.get(`/myview`)
.expect(200);
const result = JSON.parse(response.text);
const options = result.options;
assert.equal(options.my, 1);
assert.equal(options.options, 2);
assert.equal(result.fileName, 'file.pogon.html');
assert.isTrue(result.html.includes('Part of my html'));
});
});<!DOCTYPE html>
<html>
<body>
<form>
<input type="radio" name="for-test" value="one" pogon-checked="{{for-test}}">
<input type="radio" name="for-test" value="two" pogon-checked="{{for-test}}">
<input type="radio" name="for-test" value="three" pogon-checked="{{for-test}}">
<input type="radio" name="for-test" value="four" pogon-checked="{{for-test}}">
</form>
</body>
</html>The appropriate input tag has checked set based on for-test's value. For example, if
res.render('myview', {for-test: 'three'}) or await pogon.render('file.pogon.html, {for-test: 'three'})
is called, the radio button for three will be checked.
Pogon will automatically fill components specified in other files. This can avoid excessive copy and paste.
usescomponent.pogon.html:
<!DOCTYPE html>
<html>
<head>
</head>
<body>
Before the component
<pogon_component name="fortest.component.html"></pogon_component>
After the component
</body>
</html>fortest.component.html
<!DOCTYPE html>
<html>
<head>
</head>
<body>
In the component: <span id="inComponent">{{in_component}}</span>
</body>
</html>template.html:
<!DOCTYPE html>
<html>
<head>
<title>My Awesome Web App</title>
<link rel="stylesheet" href="/stylesheets/style.css">
</head>
<body>
<pogon_outlet> </pogon_outlet>
</body>
</html>result: ({in_component: 66})
<!DOCTYPE html>
<html>
<head>
<title>My Awesome Web App</title>
<link rel="stylesheet" href="/stylesheets/style.css">
</head>
<body>
Before the component
In the component: <span id="inComponent">66</span>
After the component
</body>
</html>Pogon allows creating custom tags that are evaluated and replaced server-side.
const pogon = require('pogon.html');
pogon.registerCustomTag('myapp_mytag', async (options, attributes, html) => {
return {
componentFileName: 'myfile.customtag.html', // The file that pogon uses for the custom tag
newOptions: { // New handlebars options to pass to the custom tag
}};
});See the "custom tags" test for a complete example
For more examples, see the unit tests.
- Make sure that all changes have appropriate tests added to the unit tests.
- Use async / await instead of callbacks.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent