Include me in

What is an include and why should I care?

Below is the prototypical HTML page:

<html>
<head>
<title>The Page</title>
</head>
<body bgcolor="white">
Hello World!
</body>
<html>

Now your pages may have an entirely different layout, but there's one basic truth about everybody's page ....

Every page has three parts

A good story has three parts - a beginning, a middle, and an end. Every web page has three parts as well - the 'stuff' before the page content; the content; and the 'stuff' after the content. And pretty well the 'stuff' above the content and the 'stuff' below the content are both the same for every page on your site.

Now when you do maintenance on your site, wouldn't it be nice to change one thing and have that change effected on every page? Welcome to the power of 'includes' ....

What is an include and why should I care? - continued

Our prototypical HTML page can be broken down as three parts:

the top
<html>
<head>
<title>The Page</title>
</head>
<body bgcolor="white">

the content

Hello World!


the bottom
</body>
<html>

So if we could save 'the top' and 'the bottom' separately from the content, each of our site's page would look very similar except for the actual content:

the same top
different page content
the same bottom

And then when a visitor's browser requests that page, we want the server to .... include what we defined as 'top', follow with the page's specific content, and then include what we defined as 'bottom'.

Let's make those 'included' bits

First, write this piece of code, and save it with the file name top.php:

<html>
<head>
<title>The Page</title>
</head>
<body bgcolor="white">

Next, write this piece of code, and save it with the file name bottom.php:

</body>
<html>

Finally, write this piece of code, and save it with the file name mypage1.php:

<?
include("top.php");
?>
Hello World
<?
include("bottom.php");
?>

Testing Time

Copy all three files to your server, then navigate to mypage1.php. You'll see the simple Hello World page. View the HTML source to verify for yourself that it is exactly the same as the 'top', content, and 'bottom' that you created. That's as simple as 'includes' get.

Open mypage1.php in your favorite text editor, change "Hello World" to "Hello, My name is Bob" and save that file as mypage2.php. Open top.php and change body bgcolor="white" to body color="green". Save that file as top.php.

Copy top.php and mypage2.php to your server, then navigate to mypage2.php to see that it works and the background color is green. Then navigate to mypage1.php - notice that the background color is green. No matter how many pages you needed to change the background color for, that single change to top.php would affect every one of them. That's as simple a way of changing every page on your site as you can imagine.

That's all very well but ...

I can change the background to every page of my site by editing a single CSS file that is external to each page if I had the following code as part of the head of all my HTML page:

True. You could. Not only that, but you could have used standard HTML includes to achieve what we've shown so far. For example if you collected all of your site's standard navigation links and saved them as an html file named nav-links.html, you could include one line on every page in place of your navigation code:

So what's the point of php includes?

Well, php includes sounds cool. No, that's not the point!

The benefit to using php includes is that they have all the same maintenance-reducing, development time-reducing aspects of using external CSS and javascript files and HTML includes .... but with brains.

Remember that php is a scripting language so it can accept variables, undertake conditional actions based on those variables, and a whole host of other things.

Smart Includes - check this page

Earlier, we used the following as an example of using included files:

<?
include("top.php");
?>
your page content
<?
include("bottom.php");
?>

And the benefit was that the 'top' and 'bottom' section of our pages was always the same so we saved maintenance and coding time. There's an obvious problem there. If the 'top' is always the same, what happens when I want a slight difference on every page? You can either use conventional HTML for that section of your code (different on each page!) -- or get smarter.

If you've been looking near the top of the pages of this tutorial - where this page says "Server-side Starter Tutorial: Includes - Part 5 of 6" you might have noticed that the part number is different on each page. That wasn't done by editing the HTML code every time, it was done in a much smarter fashion. First, I modified the basic code for this page so that is looked like this:

<?
$page = 5;
$maxpage = 6;
$tut_name = "Includes";
include("top.php");
?>
your page content
<?
include("bottom.php");
?>

Now each page knows which page it is, and that there are six pages in this tutorial. Then I edited the top.php code so that right after where it displayed "Server-side Starter Tutorial: ", this code was added:

<?
echo $tut_name. " - Part ". $page. " of ". $maxpage;
?>

So with those two changes, as long as I set $page to the right page number, the 'header' to this article is always right without the need to edit an html page. And by including the name of the tutorial in the page, the top.php file will correctly print that page header for every page of every tutorial here. That saved coding time, and eased maintenance.

Now look at the bottom of the page

Since I already know (from above) the page number and the number of pages in this tutorial, I can code (once) a smart previous/next pair of links that are always right. I could have coded the html for every page differently, but because my coding time is valuable (or so I like to think), I decided that an automatic way of getting those links to appear correctly - regardless of how many pages were in the tutorial - made more sense. As I've said before, a major benefit to php is time-saving.

That was done by including a short piece of php code to the file named 'bottom.php' which did the following:

If this page is page #1, print a link to page 2, with the word 'next', then stop.
If this page is page #maxpage, print a link to the previous page # with the word 'previous' then stop.
Otherwise, print a link to the previous page # with the word 'previous', and print a link to the next page # with the word 'next'.

As you will note, that short piece of code works for every page in this tutorial - one piece of code, many pages automatically behaving, much time saved. And since I also included the value of a variable named $tut to represent the tutorial set number, that one piece of next/previous code also constructs the file names used in the previous/next links ... and it works with every page of every tutorial without me ever needing to change it again. Convinced yet?

And now look at the left of the page

The menu has become 'smart'. There are links to every tutorial in the set except this one. And how was that done? I used some php script in my menu code. Basically if this page is from tutorial #3 then just print the name of tutorial 3 instead of printing a complete html link, etc. One piece of code, used without modification all through the whole tutorial set.

The End

There you have it. 'Smart includes' is what php can do for you. Time- and effort-saving stuff. Limited only by your own ingenuity and specific requirements. One thing that should be apparent (and I'll state it here so you will notice it) is that using includes works a lot better when you think things through before you actually begin coding. That doesn't stop you from converting an all-HTML site to one that uses includes of course, but you'll soon wish you had used includes from the start.

A useful 'trick'

If you always use the same 'top' file, then every page of your site will display the same title in the browser. Not exactly a good idea, but fortunately there's a very, very simple fix.

In your top.php file replace the HTML title code (<title>My Page</title>) with this:

<?
echo "<title>";
echo $page_title;
echo "</title>"
?>

That will automatically print the value of the variable $page_title as your page title. And in each of your php pages, declare the value of that variable. For example:

<?
$page_title = "your page title";
include("top.php");
?>
your page content
<?
include("bottom.php");
?>

include filename extensions?

In this tutorial, I've used filename.php consistently. Some people prefer to use .inc as the filename extension so they'll remember it's a file to be included as opposed to a .php file which they reserve for 'executable' files. Some people will use .tpl as the filename extension so they'll rememeber it's a template file. It doesn't matter which you prefer, they all work. Cautionary note: some restrictions apply - but only for files that include 'sensitive' information like passwords or usernames. That topic will be discussed in our tutorial on databases.

Happy Including

Reprinted from www.llamasery.com