Configuring Tiles

Your application needs to be configured to work with Tiles. There are various options, depending on your needs, your application type, etc.

Starting Tiles in a web application

Tiles has always been a web application package, usually used in conjunction with Struts. Tiles 2 evolved to the point of being technology-independent, but its use in a Servlet-based web application will be the most frequent use case.

Starting Tiles engine

To start Tiles you can use pure Java initialization or the original initialization-parameter-based initialization. In both cases, you have two options, just choose what is the best for your needs:

  • Load the Tiles servlet at startup. You can do it by specifying it in your web.xml file:
    <servlet>
    <servlet-name>tiles</servlet-name>
    <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class>
    ...
    <load-on-startup>2</load-on-startup>
</servlet>

    Note: The Tiles servlet is just a startup servlet and it does not serve any request. Therefore, a mapping is not needed.

  • Load the Tiles listener. Specify it in your web.xml file:
    <listener>
    <listener-class>org.apache.tiles.web.startup.TilesListener</listener-class>
</listener>

Startup with Java code

To startup with Java code, extend TilesListener or TilesServlet and override the createTilesServletInitializer method:

protected TilesInitializer createTilesInitializer() {
    return new MyCustomTilesInitializer;
}

Startup with initialization parameters

You can configure Tiles by using initialization parameters, like in Tiles 2.0.x. If you use TilesServlet, you can use init-param elements: 

<servlet>
    <servlet-name>tiles</servlet-name>
    <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class>
    <init-param>
        <param-name>
          org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG
        </param-name>
        <param-value>
          /WEB-INF/tiles-defs.xml,/org/apache/tiles/classpath-defs.xml
        </param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

As you can see, the init parameter org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG specifies the path of the Tiles configuration files. You can specify it also as a context parameters.

If you use TilesListener:

<listener>
    <listener-class>org.apache.tiles.web.startup.TilesListener</listener-class>
</listener>

you can specify the Tiles configuration files using a context parameter:

    <context-param>
        <param-name>
          org.apache.tiles.impl.BasicTilesContainer.DEFINITIONS_CONFIG
        </param-name>
        <param-value>
          /WEB-INF/tiles-defs.xml,/org/apache/tiles/classpath-defs.xml
        </param-value>
    </context-param>

Starting Tiles in a portlet application

TBD

Configuring Tiles internals

Pure Java configuration

In both environments, it is possible to use pure Java configuration, without messing with the deployment descriptors. You have two choices of configuration:

Custom Tiles container factory

You have to do create a class that extends AbstractTilesContainerFactory. In particular you can use BasicTilesContainerFactory as a basis for your extended configuration. BasicTilesContainerFactory is the configuration that replicates the default configuration of Tiles, i.e. the one that assumes when no additional parameter is provided. The Javadoc documentation of BasicTilesContainerFactory documents all the methods that can be overridden to use your own configuration.

To enable pure Java configuration, provide the org.apache.tiles.factory.AbstractTilesContainerFactory parameter this way:

<init-param>
    <param-name>org.apache.tiles.factory.AbstractTilesContainerFactory</param-name>
    <param-value>org.apache.tiles.test.factory.TestTilesContainerFactory</param-value>
</init-param>

Where TestTilesContainerFactory is a class that extends AbstractTilesContainerFactory.

Custom Tiles application context factory

You have to do create a class that extends AbstractTilesApplicationContextFactory In particular you can use ServletTilesApplicationContextFactory as a basis for your extended configuration under a servlet environment.

To enable pure Java configuration for the Tiles application context, provide the org.apache.tiles.context.AbstractTilesApplicationContextFactory parameter this way:

<init-param>
    <param-name>org.apache.tiles.context.AbstractTilesApplicationContextFactory</param-name>
    <param-value>org.apache.tiles.test.context.TestTilesApplicationContextFactory</param-value>
</init-param>

Where TestTilesApplicationContextFactory is a class that extends AbstractTilesApplicationContextFactory.

Configuration through initialization parameters

You can configure Tiles internal behaviour by specifying:

  • in a web application environment, by using context parameters or init parameters of TilesServlet or TilesFilter;
  • in a portlet environment, by using portlet init parameters.

    For the details see Tiles configuration reference.