WWW FAQs: How do I include one HTML file in another?

2007-09-20: The easiest way, by far, is to use "server side includes" in your HTML. Almost all web servers support this, except for free web hosting companies. This is overwhelmingly the preferred way to go. And the same exact syntax works for ASP and ASP.NET sites. For webmasters who prefer PHP, a minor variation on this theme is the use of PHP syntax instead of traditional server side include syntax.

For those who cannot use server side includes, ASP, ASP.NET or PHP, we also present two client side methods: the JavaScript method, and the iframe method. Both have significant disadvantages and you should absolutely try to use server side includes first. Not to put too fine a point on it, but professionals do not use client side includes, except in very specialized circumstances. "I don't know how" and "I chose the wrong web host" are not acceptable reasons when someone is paying you to design a website.

How to Use Server Side Includes

Server side includes are a simple way to tell your web server to insert various things at various points in your HTML page. You can use them without major changes to your existing pages. However, some web servers require that you name your file .shtml rather than .html in order to enable the parsing of your file by the server in order to find server side include directives. If server side includes don't appear to work, try renaming the page with a .shtml file extension before you give up.

Of course, server side includes only work when a web server is being used to access your pages. This is only an issue when testing your pages on your local hard drive. If this becomes a problem, it may be time to install a web server on your own computer, for local testing purposes. After all, Apache is free for Windows, and both free and standard in Linux and MacOS X.

A simple server side include directive to include another file found in the same folder looks like this:

include virtual and include file do almost the same thing. The difference is that include virtual takes a URL-style path, which is what you probably expect. include virtual can also execute CGI programs, if your web server supports that, and include their output. include file takes a file-system path, and cannot execute CGI programs. Both also accept relative paths, so for a simple case like the above they work the same. If you don't understand the difference between web paths and file system paths, use include virtual.

There are many more server side include directives available; for example, you can easily insert the current date into your page.

IF IT DOESN'T SEEM TO WORK, TRY NAMING YOUR FILE WITH A .shtml EXTENSION, instead of .html. Please do not ignore this tip and then email me asking why it doesn't work!

For more information, see the Apache server side includes tutorial, which also covers how to configure the free Apache web server correctly with support for server side include directives. For information about enabling Server Side Includes in Microsoft IIS, consult Microsoft TechNet.

How to Use PHP For Server Side Includes

If your server is configured to support PHP but not server side includes, or you just prefer to use PHP everywhere, you can easily include fragments of HTML in your PHP page like this:

This is essentially the same thing as server side includes, just using a different syntax. The PHP page that contains this directive must have a .php extension and the server must support PHP. If you don't know PHP, you probably want to use ordinary server side includes instead as described above.

PHP include directives can also point at files on any website using a full URL:

Of course, you must not steal content from another website without the express written permission of the owners. To do so is a copyright violation and may lead to legal action against you.

How to Use ASP and ASP.NET For Server Side Includes

If you are using old-fashioned ASP (.asp files), you're in luck. The server-side include commands discussed earlier in this article will work with no modifications. Naturally, your pages will have a .asp extension rather than a .shtml extension. Otherwise, no changes need be made. The files you include can also contain ASP code.

Since server-side includes are compiled in advance in ASP.NET, before any ASP.NET code is run, you can't use an ASP.NET variable as part of a filename to be included. Those who require such advanced capabilities can open files on the server directly from ASP.NET code. If you don't understand this... you probably don't need it! See the Microsoft Knowledge Base article How To Dynamically Include Files in ASP.NET for more information.

How to Use Client Side Includes

As I mentioned earlier, there are two ways to create client side includes: JavaScript and iframe. Let's look at the advantages and disadvantages of both before we tackle how to do it.

The JavaScript method is the more seamless of the two. JavaScript code can fetch a fragment of a page from any URL and insert it into another page at any point. The end result looks as good as a server-side include— but only if JavaScript is turned on. And search engines don't see the included text at all, which is a serious problem.

The iframe method is simpler. The iframe element can be used to force a second page to "embed" inside the first page, in much the same way that Flash movies, videos and MP3 players are embedded with the object element. And JavaScript doesn't have to be turned on. But there are disadvantages here too. The iframe element has a fixed width and height, no matter how big the content is. That can mean scrollbars inside your page. And, as of this writing, Google doesn't appear to index the separate page referenced by the iframe so that searchers can find your page.

Client-Side Includes: The JavaScript Method

Until recently web browsers did not support any elegant way of including one HTML document seamlessly into the body of another. While frames and inline frames have been available for a long time, these are ways to insert an obviously separate, scrollable sub-document into the page. Generating part of your page using JavaScript code kept in a separate file has also been possible for quite a while, but this requires that parts of your HTML be kept in JavaScript form, which is a pain to deal with.

With Firefox (on any system), Internet Explorer 5 and up (on Windows), and Apple's Safari browser (on MacOS X), the situation has improved. A new mechanism called XMLHTTP can be used to fetch XML documents "on the fly" from a JavaScript program. That includes fetching HTML files. And both of these browsers support inserting what we've fetched at any given point in the current page.

Professional designers: don't do this. Really, don't. It might be appropriate in some types of web applications, but it is not appropriate where server side includes would also work. It's just a workaround for people who can't afford real web hosting with support for PHP, ASP or server side includes. If you use this technique on a website you're being paid to design, and your client complains when the included content is invisible to Google— or doesn't show up in every browser— that's your own fault! Use the techniques earlier in this article for serious web development.

But this isn't a miracle cure. The web browser still has to be Firefox (on any operating system), Safari (on MacOS X), or IE 5 or better on Windows. That's the vast majority of users, but it's not everyone. And some users will have JavaScript turned off for security reasons.

VERY IMPORTANT: if you use this method with pages on your hard drive, not on a web server, the latest versions of Internet Explorer will warn the user that there is "active content" in the page and refuse to insert your included file unless the user goes out of their way to allow it. You won't have this problem once you move the page to a real web server. Then it becomes clear to Internet Explorer that the page and the included file are on the same website, and that nothing sneaky is going on.

OK, we've been warned, so how do we do it? By adding the following JavaScript code to the element of the web page:

Now we have the power to include another file at any point in the web page. We do that by creating a simple "placeholder" HTML element, giving it an ID that JavaScript code can recognize, and then passing both that ID and the URL of the file we want to include at that point to our clientSideInclude JavaScript function.

One tricky wrinkle: clientSideInclude doesn't always work unless the page has already been completely loaded. So we'll need to call it from the onLoad handler of the element. That's the safest time to call because the browser has definitely parsed all of our HTML by then.

So at the point in your page where you wish to insert the file includeone.html, which is found in the same folder as the page, you'll need to do this:

And at the beginning of the body of your page, you'll need to do this:

Of course, a long, complicated onLoad handler can be very ugly. You can avoid that problem by moving the call (or calls!) to clientSideInclude to a function in a

Client-Side Includes: The iframe Method

If the JavaScript method doesn't meet your needs, consider using the iframeelement. This method has the advantage of simplicity, and doesn't require JavaScript. But bear in mind that search engines still don't like it very much. And you are forced to decide in advance exactly how much space your second document will get in your first document.

If the second document is too wide or tall, scrollbars will appear. Depending on your needs, this might be just perfect or a complete deal-breaker.

Using iframe is straightforward. If your second, embedded document is calledincluded.html, just place the following element in the first, "parent" document to display it in an area 450 pixels wide by 400 pixels tall:

Why do I have an ordinary a element inside the iframe element, linking to the document we're trying to embed? Because certain older browsers, and the major search engines, don't support iframe. While very few human beings are still stuck with Netscape 4, almost everyone is using search engines like Google. And we don't want those to ignore our embedded content completely!

The iframe element has additional attributes to control its appearance. In addition to setting width and height, which you must do, you can also decide whether to allow scrolling. In most cases, you'll want to accept the default behavior: displaying scrollbars when the embedded document is too wide or tall for the width and height of the iframe element. But if you absolutely don't want to permit scrolling, even if it prevents the user from seeing all of the embedded document, you can set the scrolling attribute to no instead.

You can also eliminate the visible border around the embedded page by setting the frameborder element to 0. This is important if you want the embedded page to look like a natural part of your page.

Here's the example again with no frame border:

For more information about iframe, see The Web Design Group's very thorough article on the iframe element.

What To Include, And What Not To Include

Some users have asked whether the file that is being included needs to be a fully complete and standards-compliant HTML document. For server-side includes and JavaScript client-side includes, the included documentshould not be a complete HTML document. If you include one complete HTML document into another, you wind up with two head elements, two body elements, and so on, which is just plain wrong.

Just think about it this way: what the web browser finally receives should be a complete, standards-compliant document. It doesn't matter what the pieces you assemble to create that document look like on the server. Only what ultimately reaches the web browser is important.

For iframe client-side includes, the situation is different. Here you are embedding a completely independent second page into the first page. So that second page should be a complete HTML document in its own right.

How can I include a file on another website in my page?

You can't do that legally without permission. Here I am assuming that both sites belong to you or your client.

It's easy enough to display a web page on another site as part of your page with the