Contents: A better look and feel Server-side includes JSP includes Adding dynamic content Resources About the author Rate this article Related content: JSP architecture JSP taglibs: Better usability by design Govern your images with JSP code Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Brett McLaughlin (mailto:brett@oreilly.com?cc=&subject=Improve your look and feel with the JSP include mechanism)
Author, O'Reilly and Associates
15 April 2003

This first installment in the new JSP best practices series introduces the JavaServer Pages include mechanism. Follow along as Java programming expert Brett McLaughlin shows you how to use include to incorporate static header and footer files into your Web site or Web application pages.

Welcome to the latest Best practices series from the Java zone. If you've followed previous series, you know that best practices are designed to quickly bring you up to speed on useful aspects of various Java technologies. This series of best practices is dedicated to JavaServer Pages (JSP) technology, which is one of the core J2EE technologies.

In a nutshell, JSP technology is a tool for building Web pages or Web application interfaces on the Java platform. JSP technology allows us to do such things as dynamically respond to request data, display complex XML and HTML, and create visually interesting, dynamically driven Web sites. In this series you'll learn some of the basics of putting together a Web site with JSP technology. I'll introduce you to the most common JSP mechanisms, and through them you'll learn about essential Web development techniques such as templating, manipulating dynamic content, image hosting, creating a utility code library, and more.

In this first installment in the series, we'll focus on the JSP include mechanism, which lets us pull in content from local HTML pages. We'll start with some background on the evolution of Web page includes, particularly the use of frames and server-side includes. Then I'll show you how to use the JSP include mechanism to add uniform headers and footers to your Web pages or Web application screens.

The JSP best practices series This series isn't intended as a complete introduction to JSP technology, nor as a how-to guide for building a particular type of application. Rather, each installment in the series focuses on one aspect of programming with JSP technology, breaking it down into bite-sized pieces. For a broader introduction to JSP technology, or for a more in-depth look at how it can be used for particular results, see the Resources section. What you'll need All of the best practices in this series are based on the JavaServer Pages technologies. To run any of them, you'll need to set up a JSP-compliant Web container, such as Apache Tomcat, either on your local machine or on a test server. You'll also need to use a text editor or IDE to code your JSP pages. See Resources for a link to Tomcat and a listing of JSP-compatible Web containers and IDEs.

A better look and feel
Creating a consistent design and layout for your Web pages is one of the easiest ways to ensure a professional look and feel. You've probably seen enough Web sites to know that most pages in a single site share a uniform header and footer, as well as some sort of navigation bar. On a well-designed site, these elements will present the same layout, content, and functionality on every page, while the main panel (often called the content pane) may change with every view.

This sort of layout was once implemented almost exclusively by frames and framesets. Each piece of static content was placed in a frame, while the main content of the page sat in a middle frame. The trouble with frames is that they are often rendered differently by different browsers, making their appearance inconsistent. It's also more difficult than it should be to link from your internal page to an external site using frames. The idea is to allow the user to view outside content without leaving your site, but the result is often less than cohesive. The user may end up with a complete site squeezed into a much smaller frame, or even worse, your site may end up being nested within another site's frames. This sort of confusion drove Web designers to look for a better solution. We found it in the form of server-side includes (SSIs).

Server-side includes
Not long ago, SSIs were among the most popular options for creating shared content. A simple SSI directive lets you set up a page to include content (such as a header and footer) from another page, as shown in Listing 1.

<![CDATA[
<html>
     <head>
      <title>Simple SSI test</title>
     </head>
     <body>
       This content is statically in the main HTML file.<br />
       <!--#include virtual="included.html" -->
     </body>
</html>
]]>

We'll do an exercise using this file shortly. For now, you should save it as test-ssi.shtml. In most setups, SSI files have to end in .shtml, which lets the Web server know to parse them for SSI directives. Listing 2 shows the content of the included file, named included.html.

<![CDATA[
This content is in another file, included.html
]]>

When a request for test-ssi.shtml is made, you'll see the content of that file, as well as the content from included.html. You can view these files on any SSI-capable Web container, such as Apache Tomcat (see Resources).

SSIs are a big improvement over frames from the user's perspective because there's no perceptible difference between a single file and one that pulls content from other included files. On the downside, SSIs require a specific server setup that is often unavailable to Java developers. Additionally, SSIs have generally required that included content be static, although later versions have incorporated dynamic-content includes.

SSIs are a workable solution for including different types of content in your Web site or Web application, but they're not the best choice for Java developers. Not only does JavaServer Pages technology provide an all-Java alternative to SSIs, but the two technologies aren't easily combined. JSP pages end in the extension .jsp, which means that for SSI directives to work you have to either change your SSI configuration to also parse JSP files (adding overhead to every JSP page parse), or change your JSP configuration to treat the .shtml extension as a JSP page (which is a bad idea). JSP technology is the best content management solution for Java developers, and fortunately its include mechanism is a snap to learn.

JSP includes
The JSP include directive is quite similar to its SSI counterpart. Listing 3 shows the JSP equivalent of the SSI directive shown in Listing 1. Any JSP-capable Web container will handle the display of this JSP page (again, see the Resources section for links). You should save this file as test-include.jsp.

<![CDATA[
<%@ page language="java" contentType="text/html" %>
<html>
     <head>
      <title>JSP include element test</title>
     </head>
     <body>
      This content is statically in the main JSP file.<br />
      <%@ include file="included.html" %>
     </body>
</html>
]]>

The include directive makes it very easy to incorporate uniform header and footer files into your site. Listing 4 shows a main index page that contains several included files.

<![CDATA[
<%@ page language="java" contentType="text/html" %>
<html>
<head>
    <title>newInstance.com</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    <link href="/styles/default.css" rel="stylesheet" type="text/css" />
</head>

<body>

<%@ include file="header.jsp" %>
<%@ include file="navigation.jsp" %>
<%@ include file="bookshelf.jsp" %>
<%@ include file="/mt-blogs/index.jsp" %>
<%@ include file="footer.jsp" %>

</body>
</html>
]]>

Seeing the code should give you all sorts of ideas about how to use JSP includes. You should also try it out for yourself to learn how it works.

Adding dynamic content
In addition to static content such as a header, footer, and navigation files, Listing 4 includes a call to a Weblog (/mt-blogs/index.jsp), which brings us to the topic of dynamic content. Like the SSI include directive, the JSP include mechanism has problems when it comes to dynamic content. You may pull in dynamic content using the JSP include directive, but changes to that content won't be picked up. This is because the included files are read by the Web container as part of the original (including) page. The container caches the result as a single file rather than multiple JSP components. Because the Web container doesn't poll included files for changes, it won't realize anything has changed, and it will automatically show the cached page rather than a refreshed one. To see how this works, we'll do a simple exercise. First, update your saved included.html page to look like the one shown in Listing 5.

<![CDATA[
This content is in another file, included.html.
<br />
Some new content...
]]>

Next, save these changes, navigate to the test-include.jsp file, and refresh your browser. You'll note that the new content in included.html does not show up in the browser. The content of the included file was cached before the changes were made, so it won't show up. If your site includes dynamic content, or content that may be frequently modified, this can be a problem. Fortunately there's a workaround. In the next installment, I'll show you how to use the <jsp:include> tag to incorporate dynamic content into your Web pages. Until then, check out the Resources section, play with the code provided here, and I'll see you online.

Resources

• To do the exercises in this series, you'll need a JSP-compatible Web container, like Apache Tomcat.
  
  
• You may also want to look into using a JSP-compliant IDE. Here are several to choose from:
  • jEdit
  • NetBeans
  • Eclipse
  
  
• For the nitty-gritty details of JSP technology, your best bet is to read the JSP specification.
  
  
• For a guided introduction to JSP technology, try the tutorial "Introduction to JavaServer Pages technology" (developerWorks, August 2001).
  
  
• developerWorks also offers many in-depth articles about JSP and related technologies, including the following:
  • "JSP architecture," an excerpt from Professional JSP, (February 2001) is a good primer to JavaServer Pages technology.
  • "JSP taglibs: Better usability by design" (December 2001) is an exploration of the JSP custom tag library facility, which lets you develop your own tags for describing the components of your Web pages.
  • "Govern your images with JSP code" (November 2002) discusses many of the same concepts that have come up in this installment of JSP best practices -- but focuses on image-based content.
  • Mark Kolb's four-part series on JavaServer Pages Standard Tag Library provides some of the back-end theory to the best practices contained in this series. As of this press time, only three have been posted: Part 1, The expression language (February 2003) introduces JSTL and the Expression Language; Part 2, Getting down to the core (March 2003) delves further into the core library with a discussion on flow control and URL management; and Part 3, Presentation is everything (April 2003) focuses on the use of the fmt tag for internationalization.
  
  
• Hans Bergsten's JavaServer Pages (O'Reilly & Associates, 2002) is an indispensable resource for learning about JSP technology.
  
  
• "Ten JSP technology books compared" on developerWorks is a little bit outdated (June 2001), but it's still a fine review of worthwhile JSP titles.
  
  
• If you like JSP best practices, you might also want to check out the EJB best practices series on developerWorks.
  
  
• JSP technology is based on Java Servlets technology. Learn more about Servlets by reading Jason Hunter's Java Servlet Programming (O'Reilly & Associates, 2002).
  
  
• See the developerWorks Java technology tutorials page for a complete listing of free Java technology tutorials from developerWorks.
  
  
• You'll find hundreds of articles about every aspect of Java programming (including more articles on JSP technology) in the developerWorks Java technology zone.
  
  

About the author Brett McLaughlin has been working in computers since the Logo days (remember the little triangle?). He currently specializes in building application infrastructure using Java and Java-related technologies. He has spent the last several years implementing these infrastructures at Nextel Communications and Allegiance Telecom Inc. Brett is one of the co-founders of the Java Apache project Turbine, which builds a reusable component architecture for Web application development using Java servlets. He is also a contributor of the EJBoss project, an open source EJB application server, and Cocoon, an open source XML Web-publishing engine.

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks > Java technology