vgndeveloper.com The vignette developer community

Hi! You can find a complete guide in VCM Extensibility SDK Dev Guide 7.4 Section: "Content Extensibility > Extending Widgets". All VCM doc versions in are linked in Vignette V7 Content Managment Technical Documentation

To extend or add a new widget, you must do the folowing:

1. Content Type Definition Component Extension

   To add a new widget for use in the Content Type Definition component, you need to provide an implementation of a Widget class, an implementation of a PageService class, and a configuration JSP file.

   • Widget class

     The widget class collects input from the configuration JSP and acts as a gateway on behalf of the widget.

     It is a simple form Bean used to collect the information provided by the fields of the configuration JSP. In addition, the Widget class provides a gateway to the other classes that need to interact with and persist the widget. You create a widget by extending one of the existing Widget classes.

     Widgets have two parent classes:

     • com.vignette.as.ui.cm.ctm.shared.widgets.VCMWidget

       General-purpose abstract class that contains methods for setting and getting the configuration space values, as well as methods you can override to achieve custom behavior.

     • com.vignette.as.ui.cm.ctm.shared.widgets.VCMAbstractInputElement

       Abstract subclass of VCMWidget that is used specifically to model input-based HTML widgets. This subclass handles default values and names

   • PageService class

     This class acts as the translator between request data and the widget. Its edit method catches request parameters and populates the widget Bean’s members. Your PageService implementation should extend VCMWidgetPageService (com.vignette.as.ui.cm.ctm.ui.beans.VCMWidgetPageService) class.

     The main purpose of your implementation is to override one of the edit methods:

     void edit(IVCMWidget widget, HashMap data, ActionErrors errors) -> Provides an entry point for sub-classes to handle the edit command using a HashMap.

     void editBasedOnRequest(IVCMWidget widget, HttpServletRequest request, ActionErrors errors) -> Provides an additional level of indirection to allow widgets to hook into the request parameters if they need them.

     Which method you override depends upon whether you want to process the posted values as a HashMap or directly from the request object. In the HashMap-based method, the request attributes are pulled out of the request for you and are identified by name. However, only single-valued request attributes are supported by this HashMap method.

     If your form is posting back an array of values (such as a check box array), you need to use the editBasedOnRequest method. This request-based method provides an additional level of indirection to allow widgets to hook into the request parameters as needed. This method enables any PageService class to get the request parameters directly from the HttpServletRequest instance.

     Note that the form and product branding are already provided to the page by an outer "shell" JSP. Your configuration JSP provides only the bracketed area (Widget Configuration fieldset) of the Widget Definition dialog box.

     The shell supplies the common lookand-feel, sets up your VCMWidgetPageService instance in the session, and creates useful variables. These variables are available to your JSP—you can use them within your JSP without having to initialize them.

     Variables available to configuration JSPs:

     pageKey

     String holding the unique key for retrieving session data.

     selectedWidget

     IVCMWidget variable pointing to the currently selected widget.

     attributeName

     Name of the content type attribute that this widget is for. (Note that this is not the XML name.)

     attributeType

     Data type of the content type attribute that this widget is for.

     You can use these variables as-is, or you can recreate them inside your JSP if need be as follows (not recommended unless you have a reason to do so):

     String pageKey = request.getParameter (CTMConstants.CTM_PAGE_KEY);

     IVCMWidget selectedWidget = (IVCMWidget)PropertyUtils.getAttribute(request, pageKey, CTMConstants.SELECTED_WIDGET);

     String attributeName = (String) PropertyUtils.getAttribute(request, pageKey, CTMConstants.ATTRIBUTE_NAME);

     String attributeType = (String)PropertyUtils.getAttribute(request, pageKey, CTMConstants.ATTRIBUTE_DATA_TYPE);

     You should always use the PropertyUtils class to set and retrieve your session variables. This class helps manage and maintain session-unique names.

     Note that any JSP page you intend to use with the Content Type Definition component must include the vgn-appsvcs-cma.tld taglib directive as well as the Application Services (appsvcs) transfer tag near the top of the file, as follows:

     <%@ taglib prefix="appsvcs" uri="/WEB-INF/vgn-appsvcs-cma.tld"%>

     <appsvcs:transfer/>

     The transfer tag ensures that the session data is available across WAR file boundaries.

   • JSP file

     The JSP file contains the form fields used by the widget’s PageService instance to populate the Widget instance.

     Each widget implementation contains its own configuration parameters. You need to create a JSP file for configuring your widget. This JSP file provides the form fields to be consumed by your widget’s PageService class for storing into the defined fields of your widget subclass.

2. Content Input Form Extension

   To display a widget input field in the Content Input Form, you need to provide a custom XSLT script that retrieves the serialized XML stored in the database and converts it into HTML. This HTML is rendered in the Content Input Form (the General tab for the content instance).

   Additionally, you can supply an optional TransformingWidget subclass to provide custom transformation during the XSLT processing phase. If you do not supply a custom TransformingWidget class for your widget, the default TransformingWidget class (com.vignette.as.ui.common.widgets.TransformingWidget) is used.

   The XSLT script retrieves and converts XML stored in the database. This XML is the serialized data from the widget, sent to the database on a save command. The source for the XSLT is the output from the toXML method on the widget class, enclosed within the <widget> and </widget> tags.

   Your XSLT script has access to the XSLT parameters. These parameters are set by the TransformingWidget class or by its subclass:

   considerDefault

   Boolean value signalling whether the widget should display a default value, if one exists.

   contextPath

   Context in which to launch the hierarchy browser.

   clientLocale

   Java Locale object.

   disable

   Boolean signalling whether the widget should be disabled (to prevent the user from changing its value).

   formInputName

   Name of the HTML form element that the widget uses.

   formInputValue

   Value of the input value being passed in. NOTE: This value is available only when the body is rendered.

   formInputValueType

   Data type of the input value being passed in.

   outputContext

   String value of head or tail to signal which part of the widget is being transformed. NOTE: This value is available only when the body is rendered.

   vgnSessionKey

   Key for the current session.

   visible

   Boolean value signalling whether the widget’s label and help text should be displayed.

   Any additional parameters that you provided in your TransformingWidget subclass should also be included.