HTMLinjector

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 doesn't do any clever tricks like injecting JavaScript into your web pages to dynamically load content or call back to a server at run time. If you're designing a static website then the output of HTMLinjector will be a static website.

The application is written in C# (dotnet 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

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 inbetween the comments. This is the HTML will be injected into your web pages. Your template file might look something like this:

<!-- TEMPLATE_START id='footer' -->
<footer>
...
</footer>
<!-- TEMPLATE_END -->

HTML files

Now that you've created a template, you'll need to modify the web pages that you want it to be injected into.

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 HTML from the 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

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

The tool requires dotnetcore 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 your website files, including files containing INJECT_TEMPLATE comments.

The output folder is where the tool will write the modified files to. It also copies all other files from the source folder except for the .template files, replicating the folder structure of the source folder.

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

Customising Templates

What if you want to customise the template to vary it slightly for each web page? This can be done in HTMLinjector by nominating injection points within a template. There are a couple of ways to do this.

Injecting text

Let's say you have 5 web pages on your web site and you want to use the same page header on all of them. But you also want to show some custom text within the header that is specific to each page.

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

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

Then, in any web page that uses the template, you can declare the values that you want to be injected into the template. The values are added as attributes to the INJECT_TEMPLATE HTML comment in the host page.

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

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

HTMLinjector will inject the template into your web page and then look for any INJECT_TEMPLATE_VALUE HTML comments with a valueId property that matches an attribute on the INJECT_TEMPLATE HTML comment. 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:

<header>
    <h1>My Blog</h1>
</header>
<body>
    ...
</body>

Note that the text that you want to inject into the template must be enclosed in single quotes

Injecting HTML element attributes

You can use HTML comments as explained above to inject text literally anywhere inside a template. HTMLinjector is very simple. It doesn't know about or parse HTML - it works at the text level - so it doesn't care where you put the HTML comments. The only reason that HTML comments were used at all was so that your HTML editor will ignore them. HTMLinjector will remove them all from the output HTML whether or not you provide a value to inject.

Let's say you want to have the same header HTML on all of your web pages but you want to vary an attribute of one of the HTML elements per page. You could acheive that as follows:

<!-- TEMPLATE_START id='header' -->
<header>
    <a <!-- INJECT_TEMPLATE_VALUE valueId='loginClass' -->>Login</a>
</header>
<!-- TEMPLATE_END -->

But that looks a bit crappy. Instead, as a special use case for HTML attributes, you can add an HTML attribute named "injectTemplateValue" instead. The value that you assign to this attribute is the id of the injection point. That probably doesn't make much sense without an example:

<!-- TEMPLATE_START id='header' -->
<header>
    <a injectTemplateValue="loginClass">Login</a>
</header>
<!-- TEMPLATE_END -->

Both of the templates above will result in exactly the same output. In your host web page, you inject the template as follows:

<!-- INJECT_TEMPLATE templateId='header' loginClass='class="highlighted"' -->
<body>
    ...
</body>

Note that the value to be injected into the template is highlighted in red and can be different for each web page. The output would then be:

<header>
    <a class="highlighted">Login</a>
</header>
<body>
    ...
</body>

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' -->
<header>
    <h1>My Blog</h1>
    <!-- INJECT_TEMPLATE templateId='navLinks' -->
</header>
<!-- TEMPLATE_END -->

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.