the affordable java shopping cart   

Customizing Screen Sections: Working with the Tiles Framework

SoftSlate Commerce uses the Tiles Framework to organize its JSP templates. Throughout SoftSlate Commerce's JSP templates, you'll see tags like this, which invoke a Tiles definition:

<tiles:insert attribute="header"/>

If you aren't familiar with Tiles, you don't have to be to customize the templates. However, some understanding of Tiles and the Tiles definitions will help you find your way around and give you opportunities to customize your store in simpler ways.

"Tiles" can be thought of as different blocks on a page displayed in the browser. Which templates produce the different blocks are defined in Tiles definition files, which are xml files located in the /WEB-INF/conf folder of SoftSlate Commerce. For example, the Tiles definition for the Center Layout and for the Welcome Screen is found in /WEB-INF/conf/core/tiles-defs.xml. They look like this:

<definition name="core.baseCenterLayout" 
	<put name="htmlHead" value="/WEB-INF/layouts/default/core/htmlHead.jsp" />
	<put name="header" value="/WEB-INF/layouts/default/core/header.jsp" />
	<put name="error" value="/WEB-INF/layouts/default/core/error.jsp" />
	<put name="message" value="/WEB-INF/layouts/default/core/message.jsp" />
	<put name="leftSide" value="core.leftSide" />
	<put name="rightSide" value="core.rightSide" />
	<put name="subMenu" value="customer.accountMenu" />
	<put name="body" value="/WEB-INF/layouts/default/core/empty.jsp" />
	<put name="footer" value="/WEB-INF/layouts/default/core/footer.jsp" />

<definition name="core.welcome" extends="core.baseCenterLayout">
	<put name="pageTitleKey" value="page.welcome"/>
	<put name="body" value="/WEB-INF/layouts/default/core/welcome.jsp" />

These two definitions tell the Tiles Framework which JSP templates to use when displaying the Welcome Screen. They indicate that the /WEB-INF/layouts/default/core/centerLayout.jsp file is used to control the overall layout of the screen. Within that file, the definitions tell Tiles to include /WEB-INF/layouts/default/core/header.jsp where the <tiles:insert attribute="header"/> tag appears. Similarly, the core.welcome definition tells Tiles to include /WEB-INF/layouts/default/core/welcome.jsp when it comes across the <tiles:insert attribute="body"/> tag. In this way, the Welcome Screen is constructed by the Tiles Framework, using the JSP templates defined in the Tiles definition file.


SoftSlate Commerce extends the Tiles framework to first look inside the custom directory each time a given template is called for, before using the template found in the default directory. This is how a definition that calls for /WEB-INF/layouts/default/core/welcome.jsp will include /WEB-INF/layouts/custom/core/welcome.jsp instead, if it exists.

There are some situations where the simplest way to customize a section of a screen is to change the Tiles definition for the screen rather than the JSP templates themselves. As an example, let's say you want your store's Welcome Screen to have a different header than the rest of your store's screens. By default, all of the store's screens include /WEB-INF/layouts/default/core/header.jsp to render the header. But you want the Welcome Screen to use a different template (maybe because you want to enlarge your logo, or include a different set of navigation links).

Example 11.3. Replacing the Welcome Screen's Header

  1. The file /WEB-INF/conf/core/tiles-defs-custom.xml is included in SoftSlate Commerce to help with creating custom Tiles definitions. A custom definition will let us identify a special header template file for the Welcome Screen. Find the /WEB-INF/conf/core/tiles-defs-custom.xml file and open it in a text editor.
  2. Add the following custom definition to /WEB-INF/conf/core/tiles-defs-custom.xml, inside the <tiles-definitions> tag:
    <?xml version="1.0" encoding="ISO-8859-1" ?>
    <!DOCTYPE tiles-definitions PUBLIC
    	"-//Apache Software Foundation//DTD Tiles Configuration 1.1//EN"
    <!-- Tiles definitions for custom pages. -->
    	<definition name="core.welcome" extends="core.baseCenterLayout">
    		<put name="pageTitleKey" value="page.welcome"/>
    	    <put name="body" value="/WEB-INF/layouts/default/core/welcome.jsp" />
    	    <put name="header" 
    		value="/WEB-INF/layouts/default/core/homeHeader.jsp" />
  3. What this will do is override the default definition for the Welcome Screen. Where the default definition calls for /WEB-INF/layouts/default/core/header.jsp to be used for the header, this change will call up /WEB-INF/layouts/default/core/homeHeader.jsp instead, for just Welcome Screen. Save the /WEB-INF/conf/core/tiles-defs-custom.xml file and if necessary upload it to your installation of SoftSlate Commerce.
  4. Of course, you now need to create the homeHeader.jsp file itself, with the changes you want to include on the Welcome Screen's header. Since this file is new and not part of the SoftSlate Commerce distribution, you can safely place it in the default directory. Doing so will let all of your custom layouts use the file as a default (which will come in handy if you end up creating Multiple Custom Layouts, described below). Create the homeHeader.jsp file now and if necessary upload it into the /WEB-INF/layouts/default/core directory.
  5. Finally, whenver you make a change to a Tiles definition file, you must reload the SoftSlate Commerce application in your servlet container for the change to take effect.
  6. After reloading the application, refresh the Welcome Screen in your browser. You should see the content of the homeHeader.jsp file appearing in place of the regular header.


The /WEB-INF/conf/core/tiles-defs-custom.xml file is configured to be read in by SoftSlate Commerce after all of the other Tiles definition files, so it can be used to override the existing definitions (as described above). Please use this technique to change a definition, and avoid modifying the other definition files. These other files may be modified or replaced when you install a future upgrade of SoftSlate Commerce.


The three layout definitions, core.baseLayout, core.baseLeftLayout, and core.baseCenterLayout cannot be overridden using the /WEB-INF/conf/core/tiles-defs-custom.xml file. These definitions are extended by other definitions before the /WEB-INF/conf/core/tiles-defs-custom.xml file is read. The three definitions are exactly the same, so they can be interchanged. Consider using a JSP include command to include additional files from one of these core layout files.


There is much more information about Tiles available in books and online. Refer to the Struts Web site for more details.

Home  |   Features  |   Pricing  |   Demo Store  |   Documentation  |   About Us  |   Contact Us

Copyright © 2005 SoftSlate, Inc. All Rights Reserved.