PHP includes

Once a website gets above a few pages, the editing of content that is common to every page - such as menus, headers or footers - becomes very tiresome. PHP includes (the most popular method of a wider set of protocols known as server-side includes) is an elegant solution to this issue. Common content is placed in separate files from the main pages of the site and inserted by the server prior to the page being sent to the browser. In this manner you can, for example, add an extra item in your menu (by editing, say, a menu.php file) then see that change dissenminated to all the other files on the site. Here we are going to discuss how to do this, particularly in the context of using KompoZer. This page covers the most recent "stable" version of KompoZer, namely 0.7.10. Coverage of the 0.8 experimental versions will follow but in the meantime I'm happy to refer you to the relevant part of Charles Cooke's KompoZer Guide.

Getting ready

There are a few requirements for this approach to be successful, some are technological, others intellectual. Here they are, in no particular order:

  • A host that has PHP installed on the server (most do these days as nearly all popular blogging software is built on a PHP backbone)
  • Some familiarity on your part with what HTML code looks like - you are going to have to go into the files and cut out the code that you want to be "included" and set that up in new files
  • A text editor - software which is set up to edit code (visually similar but critically different to word processors such as Word or OpenOffice) - see the Software page on this site for suggestions
  • If you are using KompoZer you need to link the editor up using the Handcoder extension, again this is covered on the Software page
  • An understanding that your files will look a little odd until you get them up on the server, that common content will be missing when you look at files on your hard drive using KompoZer, a text editor, or even a browser

Changing file extensions

Before we go any further back up all your files! Copy them to a different folder so that if all else fails you still have an intact website.

KompoZer users should note that the "Open" and "Save As" dialogs default to .html files. You must use the drop down for "All Files" to see the .php files present and to be able to enter that extension.

The first thing we have to do is let the server know that it is going to have to do some PHP operations on the files on our website. To do this we have to change the .html (or .htm) file extensions to .php instead - so index.html becomes index.php etc. There are multiple ways of doing this, the simplest of which is simply editing the extensions by hand in Windows Explorer (having set up the View options so that the extensions are visible) or the Mac Finder or equivalent. If you are renaming a very large site then you might want to use some dedicated software for the task - freeware options include ReNamer for Windows, Name Mangler for Mac OS X 10.5 and later and it's progenitor File List (available from the same page) for older Mac systems.

Preparing the files for KompoZer

KompoZer has some "hidden" functionality intended to bail out novice users and those with dubious HTML where, among other actions (some of which are more bug than feature), an appropriate doctype is added to the head of the file being edited. We need to switch off this behaviour and the method is to open each file (directly in your chosen text editor or via KompoZer and Handcoder) and insert a php comment in the first line of the code like this:

<?php //Made with KompoZer?>

Any comment will do, the above is simply popular in the KompoZer community, a reference to doing the Funky Gibbon would work just as well.

Setting up the include

After all that preparation, actually setting up the include is so simple it is something of an anti-climax. First we create a new file for the common content to be included, then we cut out the code for that content from the original file and paste it in the "include" file and finally we place a little bit of php code in the original to let the server know where to get the "include" code and where to paste it.

It is probably easiest to explain this further with a worked example, so let's start with this file which already has a .php extension and the critical (for KompoZer users) php comment at the start of the file. It looks like this - deliberately hideous!

Browser view before includes

First we have to create a new empty file in our text editor called "menu.php" and insert that comment code in the first line. Save the file and keep it open.

Next we have to open up the original file in our text editor and identify the code for the menu. Look at the snippet of the html code in the panel below and you can see the menu code as the unordered list inside the "menu" div. We have to cut out that list, making sure we get the opening and closing list tags but not the surrounding div tags (you'll see why in a minute), and paste it under the comment tag in the menu.php file.

<div id="header">
  <h1>
    Header
  </h1>
</div>
<div id="menu">
  <ul>
    <li>menu item 1
    </li>
    <li>menu item 2
    </li>
  </ul>
</div>

The contents of the menu.php file should now look like this:

<?php //Made with KompoZer?> 

<ul>
  <li>menu item 1
  </li>
  <li>menu item 2
  </li>
</ul>

Note that this file is a functional web page, check it out here, which can be edited in KompoZer. It is important to note that the style has been lost from the original page - i.e. the font has gone back to the default and the bullets have come back - as there is no link to the external stylesheet (and there can't be as you would end up with conflicting heads in the reassembled document) - but they will revert to the desired style when "included" on the server at the end of the process. This makes editing a little different, even when using a WYSIWYG editor like KompoZer you aren't actually seeing the final, final result.

The next step is to place a php instruction in the original file so that the server inserts the contents of the include file into the final assembled file that is sent to the browser. This takes the form

<?php include("path to file with extension"); ?>

and this is what the original snippet of code given above looks like after the menu has been taken out and the php include code inserted in place of it.

<div id="header">
  <h1>
    Header
  </h1>
</div>
<div id="menu">
<?php include("menu.php"); ?>
</div>

Save the files, upload them to the server and you are done! If the uploaded files look fine then it is time to bite the bullet and go through the other files with the common code, delete that and insert the php include statement. Remember that if you look at the file locally (with a browser or KompoZer) the include material will not appear as the files haven't run through a server. In our case the "local view" looks like the panel below where the menu has disappeared and all that is left is that red border (and a space the width of the original menu div). As with editing the menu code above you have to get used to the idea of working with files where some of the final material is absent. This is why it is important to not place structural code in the include file (and why we took care to only cut the menu code above and not the code for the div surrounding it), it would be far more difficult to visualize an end product when the content isn't even in the correct place on the page. We will discuss how you can set up a local server to process these includes for you for review prior to sending them to your website at the end of this page.

Local browser view after includes

Incidentally you can look at the final product of our exercise here. It should look identical to the original down to the source appearing identical - but remember the server has inserted the includes by the time you see it.

Redirecting visitors with old bookmarks

One side effect of changing the extensions on you site from .html to .php is that any previous visitors who bookmarked one of the .html files will get a "404 file not found" error message (or an out of date file if you haven't cleaned out the old ones). This is easily overcome by setting up "redirect" files bearing the original html names so that anyone who points their browser at an .html file gets instantly sent to the corresponding .php file. The code for the redirect file is pretty simple, it's just an essentially empty file with a redirect instruction in a meta tag. Here is it:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="REFRESH" content="0;url=yourtargetfile.php" />
    <title>
    </title>
  </head>
  <body>
  </body>
</html>

All you need to do is, for each of the original .html files (or at least those that might have been bookmarked), replace it with a file containing the above code edited to point at the new file with the .php extension (represented by "yourtargetfile.php" above).

Setting up a local server

In the preceeding discussion I've gone to pains to point out that while editing a file that is either intended to be an include or one that will contain includes you will not see what the finished product looks like until you send all the files to the server and see the end result in your browser. This is true but what I'd like to mention here is that it is actually rather easy to set up a server on your home computer to review the file combination before it hits the internet. The XAMMP software package (available for Windows, Mac and multiple UNIX flavours) allows you to exactly this. Installation is easy (I'll leave instructions to the host site but for a Mac it is simply a case of uncompressing the download package) then you simply copy your files to the htdocs folder in the XAMMP folder, start the server, then look at the - now completely assembled - files in your browser.