Component Filtering with HstComponentWindowFilter

Overview

You can filter the page component hierarchy for specific requests using the HstComponentWindowFilter interface. This approach allows you to remove components from the component tree dynamically, based on request-specific criteria.

When to Use

Use component filtering when you need to conditionally show or hide components (blocks) on a page. For example, you might want to hide a specific component for authenticated users. Instead of handling this logic in each component's controller and view, you can filter out components at the container level, preventing their controllers and views from being invoked.

Example Scenario

Suppose you want to hide the "Hippo Developer Training" component for authenticated visitors. The following page configuration extends from base and includes the relevant component:

/hst:abstractpages:
  jcr:primaryType: hst:pages
  /base:
    jcr:primaryType: hst:component
    /main;
      jcr:primaryType: hst:component
      /content:
        jcr:primaryType: hst:component
        /container:
          jcr:primaryType: hst:containercomponent
          /hippo-developer-training:
            jcr:primaryType: hst:containeritemcomponent

While you can implement logic in each component's controller to check authentication and suppress rendering, this does not prevent the controller and view from being executed. Filtering components at the container level is more efficient and flexible.

HstComponentWindowFilter Interface

The HstComponentWindowFilter interface in the HST API enables component filtering. The interface is defined as follows:

public interface HstComponentWindowFilter {

    /**
     * @param requestContext
     * @param compConfig     the {@link HstComponentConfiguration} from which <code>window</code> is created
     * @param window         The {@link HstComponentWindow} to decorate
     * @return A {@link HstComponentWindow} instance which can be an enhanced or decorated version of the
     *         <code>window</code>. If the <code>window</code> should be entirely disabled/skipped, <code>null</code>
     *         should be returned
     * @throws HstComponentException
     */
    HstComponentWindow doFilter(HstRequestContext requestContext,
                                HstComponentConfiguration compConfig,
                                HstComponentWindow window) throws HstComponentException;

}

Return Value Behavior

Returning null from doFilter removes the component from the component tree for the current request.
Returning the window after calling window.setVisible(false) disables rendering but still invokes the controller and view.

Example Implementation

The following example implements HstComponentWindowFilter to skip components that have the parameter hide-for-authenticated-users = true when the visitor is authenticated:

public class AuthenticatedBasedComponentFilter implements HstComponentWindowFilter {
    @Override
    public HstComponentWindow doFilter(final HstRequestContext requestContext,
                                       final HstComponentConfiguration compConfig,
                                       final HstComponentWindow window) throws HstComponentException {

        Boolean hideForAuthenticatedUsers = (Boolean)ConvertUtils.convert(
                compConfig.getParameters().get("hide-for-authenticated-users"), Boolean.class);
        if (!hideForAuthenticatedUsers) {
            return window;
        }
        Subject subject = requestContext.getSubject();
        if (subject == null) {
            return window;
        }
        return null;
    }
}

This filter checks for the hide-for-authenticated-users parameter. If it is set to true and the visitor is authenticated, the component is removed from the tree for that request.

Registering the Filter

To activate your custom HstComponentWindowFilter, add the following Spring configuration in META-INF/hst-assembly/overrides:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
    <property name="targetObject" ref="org.hippoecm.hst.core.container.HstComponentWindowFilter.list"/>
    <property name="targetMethod" value="add"/>
    <property name="arguments">
      <bean class="org.example.AuthenticatedBasedComponentFilter"/>
    </property>
  </bean>

</beans>

This configuration registers your filter so that it is applied during request processing.

Verification

After deploying the filter and configuration, verify that components with the hide-for-authenticated-users parameter set to true are not rendered for authenticated users.