Nepotistic Pontifex Maximus

    pogon.html

    1.0.3 • Public • Published

    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

    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

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

    Install

    npm i pogon.html

    DownloadsWeekly Downloads

    1

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    28.4 kB

    Total Files

    20

    Last publish

    Collaborators

    • gwbasic