Create a rendering plug-in class

A rendering plug-in is a reusable class that we create to perform a task at render time. It can be referenced within web content using a plug-in tag. For example, we could write a plug-in that uses attributes from the current user's profile to determine whether the body of the plug-in tag is rendered or not. A rendering plug-in class requires you to reference has a set of web content API methods.

Create a plug-in class

1. Create a Java class that implements the interface com.ibm.workplace.wcm.api.plugin.rendering.RenderingPlugin . This class must implement the following methods:

   • public String getName() .

     This is the name used in the "pluginname" parameter of the plug-in tag. See Create a plug-in tag for further information.

   • public Boolean render(RenderingPluginModel p_model) throws RenderingPluginException

2. Implement render()method. This method contains the code that is run when the plug-in is invoked during rendering of a layout containing a "plug-in" tag that references the custom plug-in. Returning true renders the body markup defined in the plug-in tag. If false is returned, the body of the plug-in tag is skipped. If the plug-in tag has no body markup then the return value is ignored.

3. Methods inherited from com.ibm.portal.Localized must also be implemented.

   public String getTitle(Locale displayLocale) {}

   This method returns the title for the rendering plugin that will be used to allow selection of the rendering plugin.

   public ListModel<Locale> getLocales()

   This method returns a list of locales that are supported by this rendering plugin.

   public String getDescription(Locale p_arg0)

   This method returns a description of the rendering plugin.

   See the Javadoc documentation for further information.

For example:

package test;

import java.io.IOException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;

import com.ibm.portal.ListModel;
import com.ibm.portal.ModelException;
import com.ibm.workplace.wcm.api.plugin.rendering.RenderingPlugin;
import com.ibm.workplace.wcm.api.plugin.rendering.RenderingPluginException;
import com.ibm.workplace.wcm.api.plugin.rendering.RenderingPluginModel;

/**
 * A simple rendering plugin to demonstrate the use of the <code>RenderingPlugin</code> API.
 */
public class SimpleRenderingPlugin implements RenderingPlugin
{
   /**
    * A simple list model holding locales.
    */
   protected static class SimpleLocaleListModel<K> implements ListModel<Locale>
   {
      /** the list of locales of this list model */
      final List<Locale> m_localeList = new ArrayList<Locale>();

      /**
       * Constructs this simple list model holding the given locales.
       * 
       * @param locales
       *           the locales of this list model. May be <code>null</code>.
       */
      public SimpleLocaleListModel(final Locale[] p_locales)
      {
         if (p_locales != null)
         {
            for (int i = 0; i < p_locales.length; ++i)
            {
               m_localeList.add(p_locales[i]);
            }
         }
      }

      /*
       * (non-Javadoc)
       * 
       * @see com.ibm.portal.ListModel#iterator()
       */
      @Override
      public Iterator<Locale> iterator() throws ModelException
      {
         return m_localeList.iterator();
      }
   }

   /** a list model that only contains the English language locale */
   private static final ListModel<Locale> ENGLISH_ONLY = new SimpleLocaleListModel<Locale>(new Locale[]{Locale.ENGLISH});

   /*
    * (non-Javadoc)
    * 
    * @see com.ibm.portal.Localized#getDescription(java.util.Locale)
    */
   @Override
   public String getDescription(final Locale p_locale)
   {
      return "This is a simple rendering plugin.";
   }

   /*
    * (non-Javadoc)
    * 
    * @see com.ibm.portal.Localized#getLocales()
    */
   @Override
   public ListModel<Locale> getLocales()
   {
      return ENGLISH_ONLY;
   }

   /*
    * (non-Javadoc)
    * 
    * @see com.ibm.workplace.wcm.api.plugin.rendering#getName()
    */
   @Override
   public String getName()
   {
      return "SimpleRenderingPlugin";
   }

   /*
    * (non-Javadoc)
    * 
    * @see com.ibm.portal.Localized#getTitle(java.util.Locale)
    */
   @Override
   public String getTitle(final Locale p_locale)
   {
      return "SimpleRenderingPlugin";
   }

   /*
    * (non-Javadoc)
    * 
    * @see com.ibm.workplace.wcm.api.plugin.AuthoringPlugin#isShownInAuthoringUI()
    */
   @Override
   public boolean isShownInAuthoringUI()
   {
      return false;
   }

   /*
    * (non-Javadoc)
    * 
    * @see
    * com.ibm.workplace.wcm.api.plugin.rendering.RenderingPlugin#render(com.ibm.workplace.wcm.api
    * .plugin.rendering.RenderingPluginModel)
    */
   @Override
   public boolean render(final RenderingPluginModel p_model) throws RenderingPluginException
   {
      final Map<String, List<String>> params = p_model.getPluginParameters();

      // determine whether the inner contents of the plugin should actually be rendered       final boolean renderBody;
      final List<String> renderBodyList = params.get("renderbody");
      if (renderBodyList != null && renderBodyList.get(0).equals("false"))
      {
         renderBody = false;
      }
      else
      {
         renderBody = true;
      }

      // render the output of the plugin to the writer provided by the RenderingPluginModel
      final Writer writer = p_model.getWriter();
      try
      {
         writer.write("<b>Simple RenderingPlugin</b>");

         final Set<String> keys = params.keySet();

         final Iterator<String> iter = keys.iterator();
         while (iter.hasNext())
         {
            String key = iter.next();
            writer.write("<br>" + key + " = " + params.get(key));
         }

         writer.write("<br><br>");
      }
      catch (IOException e)
      {
         e.printStackTrace();
      }

      return renderBody;
   }
}

Create a plugin.xml file

A plugin.xml file is needed whether the deployment is done using a WAR or EAR, or using a loose jar. If deploying an application in a WAR or EAR, include the plugin.xml file in the application's "WEB-INF" folder. When using a jar, include the plugin.xml in the root of the jar.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plug-in
   id="Test"
   name="Simple Rendering Plug-in Test"
   version="1.0.0"
   provider-name="IBM">
   
   <extension
     point="com.ibm.workplace.wcm.api.RenderingPlugin"
     id="SimpleRenderingPlugin">
     <provider class="test.SimpleRenderingPlugin"/>
   </extension>                      
</plugin>

• Each plug-in is represented by a single <extension></extension> tag.

• The value of the point attribute must be "com.ibm.workplace.wcm.api.RenderingPlugin".

• Provide an ID value of the choice.

• Specify the provider class for the plug-in.

Naming conventions:

If we create a plug-in application with the same names and IDs as an existing plug-in, the new plug-in may override the first. When creating plug-in applications ensure that the following are unique across the system:

• The plug-in ID, plug-in name, and extension ID of the plugin.xml file.

• The fully qualified class name plus path of all classes within the application.

• The file path of any files within the application.

Parent: Create custom plug-ins