Skip to content

GWBasic/pogon.html

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.

About

Global look and feel HTML-based templating for Nodejs (expressjs)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published