Jive Forums API (5.5.20.2-oracle) Core Javadocs

com.jivesoftware.forum.renderer
Interface RenderFilter

All Known Subinterfaces:
RenderMacro

public interface RenderFilter

A filter is an object that performs filtering on Strings. For example, a filter might look for newline characters in a string (\n, \r\n) and replace them with <br> or <p> tags.

It is recommended that each filter provide through the BeanInfo interface the following:

These values can then be internationalized as necessary using ResourceBundles. For example, say you create a filter com.foo.SampleFilter. You should also create a class named com.foo.SampleFilterBeanInfo that extends the JiveBeanInfo class. Then, create a resource bundle named bean_SampleFilter.properties and other property files for various locales as desired.

Filters have 0 or more properties that can be configured by an administrator. Each property may control any aspect of how the filter works -- for example, a property named "color" could control which color to format text in. All properties are configurable through the standard JavaBeans conventions. You should specify exactly which properties can be controlled by an administrator by using the BeanInfo interface and JiveBeanInfo class described above.

If end user documentation is pertinent to the filter (i.e. end users may need to know a tag syntax for the filter to function) documentation should be returned from the getUserDocumentation(String) method. The output of this method is expected to follow the guidelines outlined in the documentation distributed with the product.

Instantiating classes of this interface are required to have a zero argument constructor.

See Also:
JiveBeanInfo

Method Summary
 java.lang.String execute(java.lang.String string, com.jivesoftware.forum.renderer.RenderContext renderContext)
          Applies the filter to the passed in string and returns the filtered string.
 java.lang.String getName()
          Returns the unique name of the filter.
 java.lang.String[] getUserDocumentation(java.lang.String language)
          Returns a string array of [section,title, body] of xml formatted documentation that is targetted for end user usage.
 boolean isEnabled()
          Returns true if the filter is enabled, false otherwise.
 void setEnabled(boolean enabled)
          Sets whether the filter is enabled or disabled.
 

Method Detail

getName

java.lang.String getName()
Returns the unique name of the filter.

Returns:
the unique name of the filter.

isEnabled

boolean isEnabled()
Returns true if the filter is enabled, false otherwise.

Returns:
true if the filter is enabled, false otherwise.

setEnabled

void setEnabled(boolean enabled)
Sets whether the filter is enabled or disabled.

Parameters:
enabled - true if the filter should be enabled, false otherwise.

execute

java.lang.String execute(java.lang.String string,
                         com.jivesoftware.forum.renderer.RenderContext renderContext)
Applies the filter to the passed in string and returns the filtered string.

A typical implementation of this method would use the following pattern:

  1. Inspect the render context to see if the filter should execute. For example, If the RenderStrategy denotes that links should not be filtered and the current filter does nothing but change text to links, then the filter should just return the input string.
  2. Inspect the render context to determine the RenderTarget that the filter should target the output towards.
  3. Examine the string and filter all or portions of it as required.
  4. Reassemble the complete string and returns it.
    1. Filters should expect that further processing of the returned text will be done. Use the RenderedTextStore to store text snippets if no further rendering of the all or portions of the returned content should not be performed.

      Parameters:
      string - the String to filter
      renderContext - the context the filter is being executed within
      Returns:
      a filtered string

getUserDocumentation

java.lang.String[] getUserDocumentation(java.lang.String language)
Returns a string array of [section,title, body] of xml formatted documentation that is targetted for end user usage. Documentation on how this output should be formatted can be found in the documentation that is shipped with this product.

Parameters:
language - the language as an ISO-639 language code to return the documentation in.
Returns:
a string array of [section, title, body] or null if end user documentation is not relevant to the filter.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.