Hippo URL Rewriter – Installing

Prerequisites

These instructions assume that you have an Hippo project based on the Hippo project archetype, i.e. a Maven project consisting of at least three modules: cms, site and content.

Add the Forge repository configuration

In the main pom.xml of the project, in the repositories section, add this repository if it is not configured there yet.

    <repository>
      <id>hippo-forge</id>
      <name>Bloomreach Forge maven 2 repository.</name>
      <url>https://maven.onehippo.com/maven2-forge/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
      <layout>default</layout>
    </repository>

Install the url rewriter plugin into your project

The following steps are needed:

1. Configure root pom

Specify the version in the properties section of your project's root pom:

<forge.urlrewriter.version>1.0X.XX</forge.urlrewriter.version>

2. Configure CMS pom

Add CMS plugin to the CMS pom:

<dependency>
  <groupId>org.onehippo.forge.urlrewriter</groupId>
  <artifactId>urlrewriter-module-cms</artifactId>
  <version>${forge.urlrewriter.version}</version>
</dependency>

Add repository plugin to the CMS pom (since 1.03.00):

<dependency>
  <groupId>org.onehippo.forge.urlrewriter</groupId>
  <artifactId>urlrewriter-module-repository</artifactId>
  <version>${forge.urlrewriter.version}</version>
</dependency>

3. Configure site pom

Add HST plugin to the site pom:

<dependency>
  <groupId>org.onehippo.forge.urlrewriter</groupId>
  <artifactId>urlrewriter-module-hst</artifactId>
  <version>${forge.urlrewriter.version}</version>
</dependency>

4. Configure web.xml

Configure the RewriteFilter in the site's web.xml

Add to the parameter hst-bean-annotated-classes the beans of URL Rewriter (NB since 7.9, org/onehippo/forge/** is already there by default):

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>classpath*:org/onehippo/forge/rewriting/beans/**/*.class</param-value>
</context-param>

And add the HippoRewriteFilter to the web.xml:

<filter>
    <filter-name>RewriteFilter</filter-name>
    <filter-class>org.onehippo.forge.rewriting.HippoRewriteFilter</filter-class>
    <!-- sets up log level (will be logged to context log)
     can be: TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL, log4j, commons, slf4j,
     sysout:{level} (ie, sysout:DEBUG)
     if you are having trouble using normal levels use sysout:DEBUG
     (default WARN) -->
    <init-param>
      <param-name>logLevel</param-name>
      <param-value>slf4j</param-value>
    </init-param>
    <!-- you can disable status page if desired can be: true, false (default true)              -->
    <init-param>
      <param-name>statusEnabled</param-name>
      <param-value>true</param-value>
    </init-param>
    <!-- you can change status path so that it does not conflict with your installed apps (note, defaults to /rewrite-status) note, must start with /  -->
    <init-param>
      <param-name>statusPath</param-name>
      <param-value>/rewrite-status</param-value>
    </init-param>
    <init-param>
      <param-name>statusEnabledOnHosts</param-name>
      <param-value>localhost, 127.0.0.*, *.lan, *.local</param-value>
    </init-param>
    <init-param>
      <param-name>rulesLocation</param-name>
      <param-value>/content/urlrewriter</param-value>
    </init-param>
</filter>

Important!
In your web.xml, add the filter mapping as first entry after CharacterEncodingFilter and before the other filter mappings like HstFilter.

See also Tomcat FAQ about encoding: Character Encoding Issues

<filter-mapping>
  <filter-name>RewriteFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

Add the REQUEST and FORWARD dispatchers to your HstFilter filter mapping:

<filter-mapping>
  <filter-name>HstFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

5. Add relevant Spring components.

In the Spring context of your site module, add a RewritingManager that reads the rules from the repository and an EventListener for invalidation of the manager when rules are changed in the CMS.

To do so, copy file "/site/src/main/resources/META-INF/hst-assembly/overrides/urlrewriting-context.xml" from the demo project to the following location within your project: {PROJECT_ROOT}/site/src/main/resources/META-INF/hst-assembly/overrides/

6. Deploy with bootstrap flag up.

When deploying a newly installed URL rewriter to an existing repository, be sure to make the plugin bootstrap itself by setting system property repo.bootstrap=true. See more at Content Bootstrap at onehippo.org.

Known issue, fixable by manual configuration

In URL Rewriter v1.04.01, the validator required in the document type [1] does not execute non-empty validation for "type" field, which results in the document successfully saved even when the required field is empty. Adding extra validator non-empty will give a proper behavior and warning when the type field is empty.

This step should be done for the following document type: rule, advancedrule and xmlrule

[1] /hippo:namespaces/urlrewriter/rule/hipposysedit:nodetype/hipposysedit:nodetype/ruletype[@validators=required]

Bloomreach Forge URL Rewriter Plugin

Installing URL Rewriter