README

Pogon.html

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.

Highlights

Fully-compatible Express template engine
Familiar syntax: 100% HTML and Handlebars
Programmer-defined components
Test mode for easy testing of views

For Example:

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>

Installation / Usage

npm install pogon.html

ExpressJS template Engine

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
});

Standalone

const pogon = require('pogon.html');
const mergedHtml = await pogon.render('/path/to/file.pogon.html', {my: 1, options: 2});

Advanced Features

Default and overridden titles

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.

Override template.html on a file-by-file basis

<!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.

Override the default template

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."

Test Mode

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'));
    });
});

Auto-check input for radio buttons

<!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-based components

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>

Components declared in source code

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

More examples

For more examples, see the unit tests.

Contributing

Make sure that all changes have appropriate tests added to the unit tests.
Use async / await instead of callbacks.

Usage no npm install needed!