Inserting the contents of a file on the server
The SSI include command tells the Web server to insert the contents of a specified file residing on the server into the current document, at the location of the command in the document’s source code, before sending it to a Web browser. The file to be included should contain HTML or plain text; the command cannot be used to insert images or other binary files.
There are two basic situations where using an include command can be convenient. You should consider using an include command in either of the following situations:
- You have a piece of content that you want to repeat identically in several documents. Rather than copying and pasting the common content in each document, you can save the common content in its own document and use an include command to have the Web server dynamically insert the content in each document that needs it. This technique not only saves disk space, but also makes it easier to change the common content if necessary. An example of this situation is a footer that you want to repeat identically on every page of a site.
- You have a document that is mostly static, but in which a relatively small piece of content must change frequently. In this case, rather than editing the entire document every time you need to change one small part of it, you can keep the frequently-changing content in a separate file and edit just that file. An example of this situation is a “message of the day” that changes daily in an otherwise unchanging or rarely-changing document. (However, if the frequently-changing content makes up most of the document, or if your needs are more complicated, you should consider creating a database-driven document rather than using include commands.)
To insert an include command
- Place the insertion point at the location in the current document where you want the file to be inserted by the Web server.
- On the Custom toolbar, click SSI, and then click Include. (If SSI is not visible, add it to the toolbar by opening the Customize dialog box, going to the Commands tab, selecting Insert on the Categories list and then selecting SSI on the Commands list.)
- Select the appropriate Type option as follows:
- If the file to be included is in the same folder as the document, or in a subfolder of the document’s folder, select File.
- If the file to be included is outside of the document’ folder, select Virtual.
- In the Path box, enter the path of the file to be inserted. (See the note below about acceptable kinds of paths.)
- Click OK.
If the specified file exists in the local file system at the specified path, Namo WebEditor will display its contents in the document window at the location where you inserted the include command. Otherwise, it will display a dialog box stating that the specified file could not be found. This is no cause for concern; as long as the file exists at the specified path on the Web server when you publish the document, the include command will be successful.
If the display of special tag marksTo toggle the display of special tag marks, click Show/Hide Special Tag Marks on the Standard Toolbar. is enabled, an “SSI” box (
) will also appear at the location of the include command, just before the included file contents (if displayed).
After inserting any SSI command, make sure to change the file name extension of the containing document (not the inserted file) to “.shtml”.
Notes regarding include commands
- When specifying the path of the file to be included, if you specified the Type as Virtual, you can enter an absolute path, such as “/footer.html”, or a relative path, such as “footer.html” or “../footer.html”. The path may not contain a domain name—thus, “http://www.example.com/footer.html” and “www.example.com/footer.html” are not valid. If you specified the Type as File, the path must be relative and must point to a file in the document’s folder or a subfolder of it.
- Be careful when using an include command to insert an HTML file. When a Web server encounters an include command, it always inserts the entire contents of the file at the location of the command in the containing document, regardless of the file’s content. As a result, if you use an include command to insert a complete HTML document into another HTML document, the resulting combined document generated by the server will contain two sets of <html> tags, two sets of <body> tags, and so forth—in violation of the rules of HTML. Although most Web browsers deal with such problems gracefully, there can be undesired consequences. For example, if the included document contains a style sheet, a Web browser may apply its styles to the containing document as well, which may not be what you want. To avoid such problems, it’s a good idea to make sure that the included file contains only HTML elements that normally occur within the <body> element—what is called an HTML fragment. In other words, it should not contain <html>, <head>, and <body> elements, or any elements that go inside a <head> element, such as <style>.
- Keep in mind that the outermost element or elements of an included HTML fragment will become a child element or children elements of whatever element contains the include command in the containing document. Consequently, you should take care that an included HTML fragment not contain elements that should not occur in the containing element (or, conversely, that the containing element be an element that can legally contain the elements in the included fragment). For example, if the containing element is an inline element, such as <span>, the included fragment should not contain any block-level elements, such as <p>; or if the included fragment does contain block-level elements, the containing element should also be a block-level element.
- If the file to be included contains plain text (without HTML markup), note that white space in its content will be treated by Web browsers the same as any other white space in HTML documents. Any line breaks in the text will be converted to spaces, and multiple adjacent spaces will be converted to a single space. If you want browsers to preserve line breaks and other white space in an included text file, insert the include command in a <pre> element. (While the insertion point is in the paragraph containing the include command, click the Element box on the Formatting Toolbar and select Preformatted Text.)