Download the Project Archive

Just visit the download page to locate and retrieve the project archive. Save the archive of your choosing anywhere you like and ensure you have appropriate software to extract the selected archive file.

Extract the Project Files

Using the software of choice, extract the project archive. When all goes well, you will find the three files that comprise all of the source code for the HTML Master Pages project:

1. demuxer.php
2. CresourceFile.php
3. CmasterPage.php

Upload the source files to your web server

Using whatever means are available and appropriate to you, copy the three HTML Master Pages project files to your web server. Exactly where you copy these files depends on whether you will be using them only for a single web-site or providing this solution to all of your customers. Take special note of exactly where you decide to place these files because you'll need this path in the next step.

For Do-It-Yourself Web Developers

If you are able to set the include_path of your PHP environment, you can copy the HTML Master Pages project files anywhere that suits you, as long as you also add the resulting absolute path to your include_path. If you are not able to set your include_path or you don't know how to, just copy the project files to the root directory of your web-site. This will work as long as your web hosting provider automatically adds this directory to your PHP include_path.

For Web Hosting Providers

Create a new directory in a generally secure location on your web servers' hard-drives and copy the HTML Master Pages project files to this new location. In order to protect other script files from accidental discovery or execution (because you will be granting script access to this directory to all of your customers), be careful not to use an existing directory with sensitive scripts already in it.

Configure Apache To Use HTML Master Pages

This step establishes the critical connection between the HTML Master Pages technology and your web server. You will add the following settings to your Apache configuration file(s) depending on your level of access (per the pre-installation requirements). The exact settings you use for this step depend on precisely where you copied the HTML Master Pages project files onto your web server and whether you are doing this for only one web-site (your own) or for everyone who uses your web server.

Note that in all following configuration examples, the selection of file extensions to pass to HTML Master Pages is merely a recommendation. I pass all .htm, .html, and .phtml files through HTML Master Pages to ensure that all "most likely" HTML files are processed in an expected way. Feel free to mandate any file extension(s) that you feel are more befitting your requirements.

For Do-It-Yourself Web Developers

In your dedicated configuration file (whether it is a special your-web-site.conf file or your .htaccess file, depending on how your web hosting provider has set you up), add or update the following lines:

# Ensure PHP can find the HTML Master Pages source files (and the rest of your site)
php_value include_path ".:/path/to/where/you/copied/htmlMasterPages:/path/to/your/web/root"

# Enable HTML Master Pages
Action html-master-pages /relative/path/to/htmlMasterPages/demuxer.php
AddHandler html-master-pages .htm
AddHandler html-master-pages .html
AddHandler html-master-pages .phtml
DirectoryIndex index.php index.phtml index.html index.htm
			

For Web Hosting Providers

There are essentially two distinct ways for you to configure Apache to find the HTML Master Pages files for your customers. You can either attempt a server-wide configuration or a per-site virtual configuration. The most significant differences between these configurations and that for the do-it-yourself set up are:

1. There will be only one centrally-managed copy of the HTML Master Pages project files on your web server (allowing you more control over its versioning and access)
2. The addition of ScriptAlias
3. Absolute specification of the path to the HTML Master Pages files
4. You will need to restart the httpd service to affect these changes

Per Virtual Host

This is the configuration I use on my own web servers. This is the easiest set up to grasp and enables you to control who does and does not use HTML Master Pages (or other web features). Inside each virtual host configuration file for which you want to allow HTML Master Pages, add or update the following lines.

# Ensure PHP can find the HTML Master Pages source files (and the rest of your site)
php_value include_path ".:/absolute/path/to/htmlMasterPages/script/files:/path/to/this/site/web/root"

# Enable HTML Master Pages
ScriptAlias /htmlMasterPages/ /absolute/path/to/htmlMasterPages/script/files/
Action html-master-pages /htmlMasterPages/demuxer.php
AddHandler html-master-pages .htm
AddHandler html-master-pages .html
AddHandler html-master-pages .phtml
DirectoryIndex index.php index.phtml index.html index.htm
			

Server-Wide Configuration

I haven't yet attempted a server-wide configuration on my own web servers, but here are some hints that I can offer based on what I would do if I were to try this myself. In an automatically included configuration file (as in the conf.d directory), create a new configuration file just for HTML Master Pages (like htmlMasterPages.conf). In this file, add the same lines as listed above excepting the site-specific include_path value.

Test Your Installation & Configuration

Running a simple test at this point is a very good idea. Apache configuration files have no allowance for error and file paths can be sometimes confusing (as in, "Do I use a virtual or absolute path for this particular configuration setting, and what is the current working directory for this particular host, anyway?").

In a new subdirectory of any host that you have configured for use with HTML Master Pages, create the following files. For the purpose of this example, we will create a subdirectory from your web-site root named test.

<!DOCTYPE html>
<html>
   <head>
      <title>Test Master Page</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <style>
         body {
            background-color: #000;
            color: #fff;
         }
      </style>
   </head>
   <body>
      <h1>Master Page Content On Every Page</h1>
      <div title="SSI-Container" id="masterPageContent1">
         <h2>Default Content!</h2>
         <p>Default content can be overwritten!</p>
      </div>
      <p>More content for every page!</p>
      <div title="SSI-Container" id="masterPageContent2">
         <h2>More Default Content!</h2>
         <p>Content not overwritten is left intact!</p>
      </div>
   </body>
</html>

<!DOCTYPE html>
<html>
   <head>
      <title>Test Child Page</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="masterPage.html">
      <style>
         h1 {
            color: #f0f;
         }
      </style>
   </head>
   <body>
      <h1>Child Content</h1>
      <p>Only child content wrapped in specially-marked DIVs gets promoted
         into the Master Page. This particular header and paragraph pair will
         only be visible when the HTML Master Pages configuration is incorrect
         or the specified Master Page (in this child's HEAD) could not be
         processed.</p>
      <div title="SSI-Filler" id="masterPageContent1">
         <p>Specially-marked content from a child page overwrites default
            content in the master page!</p>
         <p>Also notice that the HEAD of the child is merged with the HEAD of
            the master! For example, the TITLE attribute is concatenated with a
            hyphen between the included definitions!</p>
      </div>
   </body>
</html>

Create these files exactly as shown above, then point your web browser at the test directory into which you placed them. When Apache is configured properly, you will see the merged result! Of course, you can see the result right here for comparison (this is a live test directory that literally contains the files used for the example illustrated here).

For more details on how to use HTML Master Pages, please visit the Usage and Walk-Through Example pages.