commentHTMLinjector feedback




HTML injector logo

A very, very long time ago I needed to create a static website for a client. The website was content heavy with a lot of pages. Every page had the same header and footer. Every time I needed to add a new page or modify the page header or footer layout, I'd have to go back and manually apply the same change to every single web page in the entire website. Not unsurprisingly, this became quite tedious and error prone.

To make life easier, I developed a little tool that would run through all the web pages and inject the same header and footer HTML into them. It was a really simple but nice solution. Over the lifetime of the project I modified it to work in a much more generic and flexible way.

Fast forward many years to when I decided to build this website. I could have used an off the shelf CMS system or gone down the ASP.NET route but since virtually all the content is static, why not just keep it super simple and efficient and build a static website? Use JavaScript to call web services where needed.

Having been down this road before, I decided to dust off my old template tool. The original tool was very, very old so I did a rewrite using more modern technologies. I thought I'd share the source code just in case anyone else might find it useful on GitHub.

About HTMLinjector

HTMLinjector is a software tool that can be used to inject template text into files. There are lots of ways it can be used but it's especially useful for creating static web sites. For example, to inject template HTML into multiple pages, such as page headers and footers, at design time.

HTMLinjector does all of it's work at design time. It's a command line application that you could run as a post build event in Visual Studio or perhaps as a gulp task.

The application is written in C# (.NET Core 2.0) and can be run on Windows, MacOS and Linux from the command line. The source code is available on GitHub here: HTMLinjector on GitHub

Demo Project

The Visual Studio solution on GitHub includes a demonstration project containing several web pages that use a template header and footer. The project includes a post build event that runs the HTMLinjector application to generate a working static website.

Template files

Lets say you have a web site with 20 web pages, all of which display a standard page footer. Every time the page footer needs to be changed, you have to manually modify 20 web pages. The tool can automate this process for you.

Firstly you'll need to create a template file that contains the footer HTML that you want to appear on all web pages. Create a file named "footer.template". You can name the file whatever you like but it must end with ".template".

Inside the file add two HTML comments <!-- TEMPLATE_START id='your_id' --> and <!-- TEMPLATE_END -->

You'll need to replace the text "your_id" with something else. This is the id that you'll use elsewhere to refer to this template. In this scenario "footer" is a good option.

Then place your shared footer HTML in-between the comments. Everything inside the comment will be injected into your web pages. Your template file might look something like this:

<!-- TEMPLATE_START id='footer' -->

HTML files

Now that you've created a template, you'll need to modify your web pages to tell them to use your footer template.

Open each web page and replace the footer HTML with the following HTML comment:

<!-- INJECT_TEMPLATE templateId='footer' -->

That's all you need to do. When you run the tool it will scan through all .html files, looking for INJECT_TEMPLATE comments. It'll try and find a template with a matching id and replace the INJECT_TEMPLATE comment with the text from the matching template file.

Every time you want to change the footer HTML, all you need to do is change the footer template file, run the tool and the changes will be applied to all web pages.

Running the Application

The source code is available on GitHub here: HTMLinjector on GitHub

You'll need to build it from source code. Get the source code from GitHub and compile it, for example using Visual Studio.

To run the tool you'll need .NET Core 2.0 or above which can be downloaded and installed from the Microsoft website, here.

Run the tool from the command line using the following syntax:

dotnet HTMLinjector.dll <source_folder> <output_folder>

The source folder is the folder that contains the .template files and all your website files.

The output folder is where the tool will write the modified files to. It'll copy over everything from the source folder, modifying the files that contain injection points as needed.

BEWARE: the output folder is deleted every time the tool runs.

Customising Templates

What if you want to customise a template to vary it slightly for each web page? This can be done in HTMLinjector by nominating injection points within a template.

Let's assume you have twenty web pages on your web site and the page header on all twenty is the same. Every so often you need to change the page header and it's a pain to have to manually change the html on all twenty pages to keep them in sync. So you rip out the page header from all twenty pages and replace it with a single HTMLinjector template. That's great - now whenever you need to change the page header, you only need to change it in one place - the template.

However, let's say you have an H1 element in your page header and the text in it needs to be different for each page. You put the H1 element in the template but how can you put custom text inside it?.

Nominating injection points inside a template

You can nominate injection points inside your template using either a special HTML comment or curly braces.

You can add HTML comment tags like this: "<!-- INJECT_TEMPLATE_VALUE valueId='your_id' -->", anywhere inside your template. These are the places (placeholders) that the host web page can inject custom values. For example, you might declare your header template as follows:

<!-- TEMPLATE_START id='header' -->
    <h1><!-- INJECT_TEMPLATE_VALUE valueId='titleText' --></h1>

Alternatively, you can use three curly braces like this: {{{your_id}}}. The following header template achieves exactly the same effect:

<!-- TEMPLATE_START id='header' -->

Should I use an HTML comment or curly braces? It's probably easier to use curly braces. HTML comments can be used where your HTML editor App is throwing up parsing errors, since an HTML comment is valid HTML.

Injecting custom text into a template

In any web page that uses the template, you can inject whatever text you want into the injection points. Simply add attributes to the INJECT_TEMPLATE HTML comment in the host page. Where the name of the attribute matches the name of an injection point inside the template.

For example, you might create a web page that uses your header template like this:

<!-- INJECT_TEMPLATE templateId='header' titleText='My Blog' -->

Firstly, HTMLinjector will inject the template into your web page. Then it will look for any INJECT_TEMPLATE_VALUE HTML comments or curly brace injection points inside the template. If you declared an attribute that matches the id of an injection point it injects the text there. I've highlighted the injection point and value in red in the above examples.

For the header examples above the following HTML would be output:

    <h1>My Blog</h1>

Templates within templates

You can inject templates inside other templates. There is no limit to the number or depth of templates that can be injected inside other templates. You can of course get yourself into a nice infinite loop by injecting a template into itself :)

<!-- TEMPLATE_START id='blogHeader' -->
    <h1>My Blog</h1>
    <!-- INJECT_TEMPLATE templateId='navLinks' -->

All injection values (see Injecting text and Injecting HTML element attributes) are shared across all templates in the same web page. HTMLinjector will inject all the templates first, including templates within templates and then inject any values into the resulting HTML. Just be careful not to declare the same injection value id in different templates.

Is HTMLinjector just for HTML files?

Despite its name, HTMLinjector works with any text file. It doesn't care if the file contains HTML, JavaScript, plain old Text, C++ or anything else, so long as it's text.

Got questions, comments?   Send me feedback