Background
I got the inspiration for this project while working on my bachelor thesis project internship at IBM in 2005. I was developing an application usage analyzer system which included a web front-end implementing their intranet layout. I observed that it was a bit tedious to get it implemented properly. Moreover, I noticed that I had to repeat the same patterns over and over again for each page.
I saw some "tricks" that other people did to cope with these issues, but I considered all of them workarounds -- they were basically a bunch of includes in combination with a bit of iteration to make it work, but looked overly complicated and had all kinds of issues.
Some time before my internship, I learned about the Model-view-controller architectural pattern and I was looking into applying this pattern to the web front-end I was developing.
After some searching on the web using the MVC and Java Enterprise Edition (which was the underlying technology used to implement the system) keywords, I stumbled upon the following JavaWorld article titled: 'Understanding JavaServer Pages Model 2 architecture'. Although the article was specifically about the Model 2 architecture, I considered the Model 1 variant -- also described in the same article -- good enough for what I needed.
I observed that every page of an intranet application looks quite similar to others. For example, they had the same kinds of sections, same style, same colors etc. The only major differences were the selected menu item in the menu section and the contents (such as text) that is being displayed.
I created a model of the intranet layout that basically encodes the structure of the menu section that is being displayed on all pages of the web application. Each item in the menu redirects the user to the same page which -- based on the selected menu option -- displays different contents and a different "active" link. To cite my bachelor's thesis (which was written in Dutch):
De menu instantie bevat dus de structuur van het menu en de JSP zorgt ervoor dat het menu in de juiste opmaak wordt weergegeven. Deze aanpak is gebaseerd is op het Model 1 [model1] architectuur:
which I could translate into something like:
Hence, the menu instance contains the structure of the menu and the JSP is responsible for properly displaying the menu structure. This approach is based on the Model 1 [model1] architecture.
(As a sidenote: The website I am referring to calls "JSP Model 1" an architecture, which I blindly adopted in my thesis. These days, MVC is not something I would call an architecture, but rather an architectural pattern!)
I was quite satisfied with my implementation of the web front-end and some of my coworkers liked the fact that I was capable of implementing the intranet layout completely on my own and to be able to create and modify pages so easily.
Creating a library
After my internship, I was not too satisfied with the web development work I did prior to it. I had developed several websites and web applications that I still maintained, but all of them were implemented in an ad-hoc way -- one web application had a specific aspect implemented in a better way than others. Moreover, I kept reimplementing similar patterns over and over again including layout elements. I also did not reuse code effectively apart from a bit of copying and pasting.
From that moment on, I wanted everything that I had to develop to have the same (and the best possible) quality and to reuse as much code as possible so that every project would benefit from it.
I started a new library project from scratch. In fact, it were two library projects for two different programming languages. Initially I started implementing a Java Servlet/JSP version, since I became familiar with it during my internships at IBM and I considered it to be good and interesting technology to use.
However, all my past projects were implemented in PHP and also most of the web applications I maintained were hosted at shared webhosting providers only supporting PHP. As a result, I also developed a PHP version which became the version that I actually used for most of the time.
I could not use any code from my internship. Apart from the fact that it was IBM's property, it was also too specific for IBM intranet layouts. Moreover, I needed something that was even more general and more flexible so that I could encode all the layouts that I had implemented myself in the past. However, I kept the idea of the Model-1 and Model-2 architectural patterns that I discovered in mind.
Moreover, I also studied some usability heuristics (provided by the Nielsen-Norman Group) which I tried to implement in the library:
- Visibility of system status. I tried supporting this aspect, by ensuring that the selected links in the menu section were explicitly marked as such so that users always know where they are in the navigation structure.
- The "Consistency and standards" aspect was supported by the fact that every page has the same kinds of sections with the same purposes. For example, the menu sections have the same behavior as well as the result of clicking on a link.
- I tried support "Error prevention" by automatically hiding menu links that were not accessible.
I kept evolving and improving the libraries until early 2009. The last thing I did with it was implementing my own personal homepage, which is still up and running today.
Usage
So how can these libraries be used? First, a model has to be created which captures common layout properties and the sub pages of which the application consists. In PHP, a simple application model could be defined as follows:
<?php
$application = new Application(
/* Title */
"Simple test website",
/* CSS stylesheets */
array("default.css"),
/* Sections */
array(
"header" => new StaticSection("header.inc.php"),
"menu" => new MenuSection(0),
"submenu" => new MenuSection(1),
"contents" => new ContentsSection(true)
),
/* Pages */
new StaticContentPage("Home", new Contents("home.inc.php"), array(
"page1" => new StaticContentPage("Page 1", new Contents("page1.inc.php"), array(
"page11" => new StaticContentPage("Subpage 1.1",
new Contents("page1/subpage11.inc.php")),
"page12" => new StaticContentPage("Subpage 1.2",
new Contents("page1/subpage12.inc.php")),
"page13" => new StaticContentPage("Subpage 1.3",
new Contents("page1/subpage13.inc.php")))),
...
)))
);
The above code fragment specifies the following:
- The title of the entire web application is: "Simple test website", which will be visible in the title bar of the browser window for every sub page.
- Every sub page of the application uses a common stylesheet: default.css
- Every sub page has the same kinds of sections:
- The header section always displays the same (static) content which code resides in a separate PHP include (header.inc.php)
- The menu section displays a menu navigation section displaying links reachable from the entry page.
- The submenu section displays a menu navigation section displaying links reachable from the pages in the previous menu section.
- The contents section displays the actual dynamic contents (usually text) that makes the page unique based on the link that has been selected in one of the menu sections.
- The remainder of the code defines the sub pages of which the web application consists. Sub pages are organised in a tree-like structure. The first object is entry page, the entry page has zero or more sub pages. Each sub page may have sub pages of their own, and so on.
Every sub page provides their own contents to be displayed in contents section that has been defined earlier. Moreover, the menu sections automatically display links to the reachable sub pages from the current page that is being displayed.
By calling the following view function, with the application model as parameter we can display any of its sub pages:
displayRequestedPage($application); ?>
The above function generates a basic HTML page. The title of the page is composed of the application's title and the selected page title. Moreover, the sections are translated to div elements having an id attribute set to their corresponding array key. Each of these divs contains the contents of the include operations. The sub page selection is done by taking the last few path components of the URL that come after the script component.
If I create a "fancy" stylesheet, a bit of basic artwork and some actual contents for each include, something like this could appear on your screen:
Although the generated HTML by displayRequestedPage() is usually sufficient, I could also implement a custom one if I want to do more advanced stuff. I decomposed most if its aspects in sub functions that can be easily invoked from a custom function that does something different.
I have also created a Java version of the same concepts, which predates the PHP version. In the Java version, the model would look like this:
package test;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import io.github.svanderburg.layout.model.*;
import io.github.svanderburg.layout.model.page.*;
import io.github.svanderburg.layout.model.page.content.*;
import io.github.svanderburg.layout.model.section.*;
public class IndexServlet extends io.github.svanderburg.layout.view.IndexServlet
{
private static final long serialVersionUID = 6641153504105482668L;
private static final Application application = new Application(
/* Title */
"Test website",
/* CSS stylesheets */
new String[] { "default.css" },
/* Pages */
new StaticContentPage("Home", new Contents("home.jsp"))
.addSubPage("page1", new StaticContentPage("Page 1", new Contents("page1.jsp"))
.addSubPage("subpage11", new StaticContentPage("Subpage 1.1",
new Contents("page1/subpage11.jsp")))
.addSubPage("subpage12", new StaticContentPage("Subpage 1.2",
new Contents("page1/subpage12.jsp")))
.addSubPage("subpage13", new StaticContentPage("Subpage 1.3",
new Contents("page1/subpage13.jsp"))))
...
)
/* Sections */
.addSection("header", new StaticSection("header.jsp"))
.addSection("menu", new MenuSection(0))
.addSection("submenu", new MenuSection(1))
.addSection("contents", new ContentsSection(true));
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
dispatchLayoutView(application, req, resp);
}
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
dispatchLayoutView(application, req, resp);
}
}
As may be observed, since Java is statically typed language, more code is needed to express the same thing. Furthermore, Java has no associative arrays in its language, so I decided to use fluent interfaces instead.
Moreover, the model is also embedded in a Java Servlet, that dispatches the requests to a JSP page (WEB-INF/index.jsp) that represents the view. This JSP page could be implemented as follows:
<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" import="io.github.svanderburg.layout.model.*"
import="io.github.svanderburg.layout.model.page.*,test.*"%>
<%
Application app = (Application)request.getAttribute("app");
Page currentPage = (Page)request.getAttribute("currentPage");
%>
<%@ taglib uri="http://svanderburg.github.io" prefix="layout" %>
<layout:index app="<%= app %>" currentPage="<%= currentPage %>" />
The above page takes the application model and the current page (determined by the URL to call it) as requests parameters. It invokes the index taglib (instead of a function in PHP) to compose an HTML page from it. Moreover, I have also encoded sub parts of the index page as reusable taglibs.
Other features
Besides the simple usage scenario shows earlier, the libraries support a collection of other interesting features, such as:
- Multiple content section support
- Per-page style and script includes
- Error pages
- Security handling
- Controller sections to handle GET or POST parameters. In Java, you can invoke Java Servlets to do this, making the new library technically compliant with the JSP Model-2 architectural pattern.
- Using path components as parameters
- Internationalised sub pages
Conclusion
In this blog post, I have described an old dormant project that I revived and released. I always had the intention to release it as free/open-source software in the past, but never actually did it until now.
These days, some people do not really consider me a "web guy". I was very active in this domain a long time ago, but I (sort of) put that interest into the background, although I am still very much involved with web application development today (in addition to software deployment techniques and several other interests).
This interesting oatmeal comic clearly illustrates one of the major reasons why I have put my web technology interests into the background. This talk about web technology from Zed Shaw has an overlap with my other major reason.
Today, I am not so interested anymore in making web sites for people or to make this library a killer feature, but I don't mind sharing code. The only thing I care about at this moment is to use it to please myself.
Availability
The Java (java-sblayout) as well as the PHP (php-sblayout) versions of the libraries can be obtained from my GitHub page and used under the terms and conditions of the Apache Software License version 2.0.
