+

Search Tips   |   Advanced Search

Create an item validation plug-in class

An item validation plug-in is used to validate a TemplatedDocument prior to it being committed to the repository. It is invoked as part of the standard item validation step. For example, saves occurring in the authoring interface, public API or REST API.

Possibly usages of this extension point include:

  • Validating cross field relationships

  • Complex custom field validation

  • Workflow validation for an item based on type and location in the repository


Create the item validation plug-in class

  1. Create a Java class that implements the interface com.ibm.workplace.wcm.api.extensions.validation.ItemValidationPlugin . This class implement the following methods:

    • DocumentId<? extends AbstractAuthoringTemplate>[] validationScope()

    • ItemValidationResult validate(ItemContext context)

    The validate method returns a ItemValidationResult which will report back any errors to be shown to the current user.

  2. Within the validate method any field of the item can be modified. After all validation plug-ins have been invoked the standard item and template validation will be performed. See the WCM Javadoc for further information. For example:
    package com.sample;
     import java.util.ArrayList;
    import java.util.Iterator;
    import java.util.List;
    import java.util.Locale;
     import com.ibm.portal.ListModel;
    import com.ibm.portal.Localized;
    import com.ibm.portal.ModelException;
    import com.ibm.workplace.wcm.api.AbstractAuthoringTemplate;
    import com.ibm.workplace.wcm.api.AuthoringTemplate;
    import com.ibm.workplace.wcm.api.Content;
    import com.ibm.workplace.wcm.api.Document;
    import com.ibm.workplace.wcm.api.DocumentId;
    import com.ibm.workplace.wcm.api.DocumentLibrary;
    import com.ibm.workplace.wcm.api.DocumentTypes;
    import com.ibm.workplace.wcm.api.RichTextComponent;
    import com.ibm.workplace.wcm.api.WCM_API;
    import com.ibm.workplace.wcm.api.Workspace;
    import com.ibm.workplace.wcm.api.exceptions.ComponentNotFoundException;
    import com.ibm.workplace.wcm.api.exceptions.OperationFailedException;
    import com.ibm.workplace.wcm.api.exceptions.ServiceNotAvailableException;
    import com.ibm.workplace.wcm.api.extensions.validation.ItemContext;
    import com.ibm.workplace.wcm.api.extensions.validation.ItemValidationPlugin;
    import com.ibm.workplace.wcm.api.extensions.validation.ItemValidationResult;
     /**
     * A simple item validation plug-in  */
    public class SampleItemValidator implements ItemValidationPlugin
    {
       /** Validate all items created from this authoring template */
       private DocumentId<AuthoringTemplate> m_templateId = null;
                /**
        * 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 item validation plugin.";
       }
        /*
        * (non-Javadoc)
        * @see com.ibm.portal.Localized#getLocales()
        */
       @Override
       public ListModel<Locale> getLocales()
       {
          return ENGLISH_ONLY;
       }
        /*
        * (non-Javadoc)
        * @see com.ibm.portal.Localized#getTitle(java.util.Locale)
        */
       @Override
       public String getTitle(final Locale p_locale)
       {
          return "SimpleItemValidationPlugin";
       }
           /**
        * @see com.ibm.workplace.wcm.api.extensions.validation.ItemValidationPlugin#validate(com.ibm.workplace.wcm.api.extensions.validation.ItemContext)
        */
       @Override
       public ItemValidationResult validate(ItemContext p_itemContext)
       {
          boolean isValidItem = true;
          String error = null;
          try       {
             // Perform a very simple validation. Check for the Body element, and return an error if the string "BAD BAD BAD" is        
             // found in the field.
             Document document = p_itemContext.document();
             if (document instanceof Content)
             {
                Content content = (Content) document;
               RichTextComponent body = (RichTextComponent)content.getComponent("Body");
               if (body == null)
                {
     error = "Item validation failed: Content has no body element";
     isValidItem = false;
                }
                else             {
     if (body.getRichText().contains("BAD BAD BAD"))
     {
        error = "Item validation failed: BAD BAD BAD message found in Body field.";
        isValidItem = false;
     }
                }
             }
          }
          catch (IllegalStateException e)
          {
             throw e;
          }
          catch (ComponentNotFoundException e)
          {
             error = "Item validation failed: Content has no body element";
             isValidItem = false;
          }
      final boolean isValidResponse = isValidItem;
          final String errorMessageResponse = error;     /**
           * @see com.ibm.workplace.wcm.api.extensions.validation.ItemValidationResult
           *         * A very simple ItemValidationResult that only returns errors.         */
          return new ItemValidationResult()
          {     @Override
             public Localized[] errorMessages()
             {
                return new Localized[]{
     new Localized()
     {    public String getTitle(Locale locale)
        {
           return errorMessageResponse;
        }           public ListModel<Locale> getLocales()
        {
           return ENGLISH_ONLY;
        }
              public String getDescription(Locale locale)
        {
           return null;
        }
     }
                };
             }
         @Override
             public boolean isValid()
             {
                return isValidResponse;
             }
              @Override
             public Localized[] infoMessages()
             {
                return null;
             }
         @Override
             public Localized[] warningMessages()
             {
                return null;
             }
         @Override
             public Localized[] successMessages()
             {
                return null;
             }
          };
       }
        /**
        * @see com.ibm.workplace.wcm.api.extensions.validation.ItemValidationPlugin#validationScope()
        */
       public DocumentId<? extends AbstractAuthoringTemplate>[] validationScope()
       {
          try {
             // Find the Article authoring template in the sample out of the box library.
             Workspace workspace = WCM_API.getRepository().getSystemWorkspace();
             DocumentLibrary docLib = workspace.getDocumentLibrary("Web Content");
             workspace.setCurrentDocumentLibrary(docLib);
             DocumentId<AuthoringTemplate> templeId = workspace.findByName(DocumentTypes.AuthoringTemplate, "Article").next();
             m_templateId = templeId;
    
              // This plug-in will be invoked whenever a content item based on this template is saved.
             return new DocumentId[]{templeId};
          }
          catch (ServiceNotAvailableException e)
          {
             e.printStackTrace();
          }
          catch (OperationFailedException e)
          {
             e.printStackTrace();
          }
          return null;
       }
        @Override
       public boolean isShownInAuthoringUI()
       {
          return false;
       }
    }
    


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 via 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 Item Validation Plug-in"
   version="1.0.0"
   provider-name="IBM">
       <extension
     point="com.ibm.workplace.wcm.api.extensions.validation.ItemValidationPlugin"
     id="SimpleItemValidationPlugin">
     <provider class="com.sample.SampleItemValidator"/>
   </extension>         </plug-in>

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

  • The value of the point attribute must be com.ibm.workplace.wcm.api.validation.ItemValidationPlugin.

  • Provide an id value of the choice.

  • Specify the provider class for the plug-in.

Naming conventions:

If we create a new 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 the following 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 plus path of all classes within the application.

  • The file path of any files within the application.


Parent Create custom plug-ins