Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page explains how to create and configure a custom Filter.
Please read about Filters and request processing which explains some filters used by Magnolia.
Implementation
To ensure your filter is properly registered using Magnolia configuration, your filter should implement MgnlFilter or extend another Magnolia filter which implements MgnlFilter. Extending AbstractMgnlFilter is usually a good starting point.
Example:
public class KlackerFilter extends AbstractMgnlFilter{ @Override public void doFilter(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse, FilterChain filterChain) throws IOException, ServletException { httpServletResponse.setHeader("X-Clacks-Overhead", "GNU Terry Pratchett" ); filterChain.doFilter(httpServletRequest, httpServletResponse); } }
The example above is a dummy example inspired by GNU Terry Pratchett HTTP-Header.
Configuration and Registration of filters
Filters in a Java webapp using servlets 2.5 must be registered in the web.xml
. However:
When adding a filter to Magnolia - you should not register it in web.xml but on Magnolia configuration. If the configuration is done properly - filters are registered dynamically by Magnolia.
You can configure filters implementing MgnlFilter as well as other filters with Magnolia configuration by using Configuration app. Compared to "classical" web.xml based configuration - you can change the configuration on the running instance. This also includes enabling and disabling a filter.
As with any other configuration data - bootstrap the configuration within your module with a bootstrap file or create an installation task to ensure configuration is set correctly when your project must be reinstalled or deployed.
Add a node to /server/filters
To configure a filter add a node to /server/filters:
Node name | |
---|---|
server | |
filters | |
klacker | |
class | info.magnolia.documentation.examples.templates.KlackerFilter |
enabled | true |
class | required The fully qualified class name of your custom filter (which must implement MgnlFilter ). |
enabled | optional, default is Setting to false disables the filter. |
mappings | optional Add mappings. |
Configuring and registering a filter which does not implement info.magnolia.cms.filters.MgnlFilter
If you have a filter which can not implement MgnlFilter for some reason but which should be registered to Magnolia filter chain, your configuration should look like this:
Node name | |
---|---|
filters | |
anotherFilter | |
class | info.magnolia.cms.filters.FilterDecorator |
decoratedFilter | |
class | info.magnolia.documentation.examples.templates.AnotherFilter |
config | |
myInitParam | some value |
class | required In this case class must be info.magnolia.cms.filters.FilterDecorator. |
| required |
| required The fully qualified class name of your custom filter (which does not implement AbstractMgnlFilter ). |
| optional A map to add filter init parameters. You may add as many parameters as required. The init parameters can be read in the init method of the filter (see below). |
Adding filter init parameters
javax.servlet.Filter has an #init method which is called once when the filter is initialized.
Init parameters for filters implementing info.magnolia.cms.filters.MgnlFilter
When using filters implementing MgnlFilter you can use "normal" Node2Bean mechanism. Add bean properties to the filter class and configure appropriately:
Init parameters for filters not implementing info.magnolia.cms.filters.MgnlFilter
If you are using FilterDecorator for custom filters not implementing MgnlFilter , use the config node to add init parameters (see above). The parameters are set to javax.servlet.FilterConfig and can be used in the init method:
Ensure position in filter chain
Filters are executed in the order they are in the chain, from top to bottom. If you do not care about execution order, you can skip this section, otherwise make sure the filter is in the right position in the chain.
Magnolia provides task classes to adapt the order of the filter via module version handler. Use FilterOrderingTask or OrderFilterBeforeTask. The code example below is using the FilterOrderingTask
.
When installing a module, you can define the position with ModuleVersionHandler#getExtraInstallTasks
.
public class MyModuleVersionHandler extends DefaultModuleVersionHandler { @Override protected List<Task> getExtraInstallTasks(InstallContext installContext) { List<Task> extraInstallTasks = new ArrayList<Task>(super.getExtraInstallTasks(installContext)); extraInstallTasks.add(new FilterOrderingTask("klacker", new String[]{"contentType"})); return extraInstallTasks; } }
The code above would ensure to have the filter "klacker" right after the filter "contentType".