Creating a content URL generation filter class

A content URL generation filter is used to customize the URLs that are generated by a web content viewer. By creating a plug-in that implements a content URL generation filter, you can tailor the URLs to content items.

The web content viewer generates a content URL whenever there is a URL to web content within content that the viewer is displaying.

The content URL generation filter chain is a chain of filters that are based on the Intercepting Filter design pattern. This design pattern provides a mechanism for intercepting a request and manipulating the request and its response. When used with requests for content URL generation, the content URL generation filter chain has default filters that run the following actions:

Process any request to generate a URL that target a web content item.
Create a URL based on the configuration of the web content viewer and any parameters set on the URL generation tags, such as the URLCmpnt tag.

The default filters occur at the end of the filter chain.

You can customize the content URL generation filter chain by creating custom filters. These filters are registered with the portal through the Eclipse plug-in framework with the extension ID com.ibm.workplace.wcm.api.ContentUrlGenerationFilter. The sequence of filters in the filter chain is specified by a weight value that is associated with each filter plug-in. To insert custom filters into the filter chain before the default filters, you can use the weight attribute in the plugin.xml file. If the weight attribute is not present, filter sequence is determined by the getFilterChainWeight method of each custom filter factory.

Custom content URL generation filters can run various actions:

Modify parameters before you call the default URL generation filters.
Modify the URL that is generated by the default filters.
Handle exceptions that are generated by the default filters.
Determine whether the default filters are started.
Modify the content path that is used as input for the default URL generation filters.
Generate any type of URL without using the default URL generation filters.

Important

You can use custom content URL generation filters to modify only URLs that are generated by web content tags, such as the Placeholder or the URLCmpnt tag. The Web Content Viewer does not call custom content URL generation filters when it generates, for example, the URLs of a page navigation component.

To use a content URL generation filter, you must create two classes:

A content URL generation filter that is used to create URLs.
A content URL generation filter factory that is used to create new instances of the filter.

You must deploy both classes on the server and register the filter factory by using a plugin.xml file.

Create a Java class that implements the interface com.ibm.workplace.wcm.api.extensions.url.ContentUrlGenerationFilterFactory. This class must implement the following methods:
- public ContentUrlGenerationFilter getFilter(RenderRequest portletRequest, RenderResponse portletResponse) throws ContentUrlFilterInstantiationException
  
  This method is called by the content URL generation chain once for each content item that is rendered. The method creates an instance of a content URL generation filter, which generates all URLs that appear in the rendered web content.
- public int getFilterChainWeight() {}
  
  This method returns the weight that is applied to the content URL generation filter elements in the filter chain. The less it is weighted, the earlier the filter is inserted into the chain. If the weight parameter is defined in the plugin.xml file, that value overrides the value that is returned by this method.
See the Javadoc documentation for further information. The Javadoc files for Web Content Manager are in the [PortalServer\_root](../reference/wpsdirstr.md#wp_root)/doc/Javadoc/spi_docs/com/ibm/workplace/wcm directory.
Create a Java class that implements the interface com.ibm.workplace.wcm.api.extensions.url.ContentUrlGenerationFilter. This class must implement the following methods:
- public void writeURL(ContentUrlGenerationRequest request, ContentUrlGenerationResponse response, ContentUrlGenerationFilterChain chain) throws ContentUrlGenerationException, IOException
  
  This method is started during content URL generation processing and is started once per content URL. The response parameter is used to write to the URL. The request parameter contains the following information:
  - Information about the item for which the URL is generated.
  - Any web content viewer configuration and related information that might affect the generation of the URL. The filter chain contains the subsequent filters that can be started when needed.
- public void dispose()
  
  This method is started by the filter chain after all URLs that appear in the rendered content items are written. The method enables filters to run a cleanup of their internal state.
For more information about this class, see the Javadoc documentation.
A plugin.xml file is needed whether the deployment is done by using a WAR or EAR file, or by using a JAR file. If you deploy with an application in a WAR or EAR file, include the plugin.xml file in the WEB-INF folder. When you use a JAR file, include the plugin.xml in the root of the JAR file.
```
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.example.content.url"
       name="Sample content URL generation filter"
       version="1.0.0"
       provider-name="IBM">

 <extension
    point="com.ibm.workplace.wcm.api.ContentUrlGenerationFilter"
    id="SampleContentUrlGenerationFilter">
    <factory class="com.example.SampleContentUrlGenerationFilterFactory" 
             weight="1"/>
 </extension>

</plugin>
```
When you create plug-ins, note the following characteristics:
- Each plug-in is represented by a single <extension> tag.
- The value of the extension point attribute must be com.ibm.workplace.wcm.api.ContentUrlGenerationFilter.
- Provide an ID value of your choice.
- Specify the filter factory class for your plug-in.
- The weight parameter overrides the value of the getFilterChainWeight method. Naming conventions:
If you create a new plug-in application with the same names and IDs as an existing plug-in, the new plug-in might override the first. When you create plug-in applications ensure that the following elements are unique across your system:
- The plug-in ID, plug-in name, and extension ID of the plugin.xml file.
- The fully qualified class name and path of all classes within the application.
- The file path of any files within the application.
Example 1: Append a prefix to a content URL
This example demonstrates a content URL generation filter that appends a prefix to each content URL that is written. This type of content URL generation filter is useful when used with an HTTP server that dynamically rewrites incoming URLs.
Example 2: Generate a friendly URL for web content
This example demonstrates a content URL generation filter that generates a friendly URL for web content.