Create 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, we 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 perform 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.

We 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 associated with each filter plug-in. To insert custom filters into the filter chain before the default filters, we 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 perform various actions:

• Modify parameters before calling the default URL generation filters.

• Modify the URL generated by the default filters.

• Handle exceptions that are generated by the default filters.

• Determine whether the default filters are invoked.

• Modify the content path used as input for the default URL generation filters.

• Generate any type of URL without using the default URL generation filters.

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

• A content URL generation filter used to create URLs.

• A content URL generation filter factory used to create new instances of the filter.

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

1. 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 applied to the content URL generation filter elements in the filter chain. The lower the weight, 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 returned by this method.

   For more information about this class, see the Javadoc documentation.

2. 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 invoked during content URL generation processing and is invoked once per content URL. The response parameter enables you 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 invoked when needed.

   public void dispose()

   This method is invoked by the filter chain after all URLs that appear in the rendered content items are written. The method enables filters to perform a cleanup of their internal state.

   For more information about this class, see the Javadoc documentation.

3. A plugin.xml file is needed whether the deployment is done using a WAR or EAR file, or 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 using 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 creating 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 the choice.

   • Specify the filter factory class for the 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 creating 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.

Parent: Create custom plug-ins

Related:

Friendly URLs and web content viewers