Tutorial - Building Custom Widgets

This tutorial describes how to build your own custom widgets for the Insert/Edit form. In this example, we will create a simple TextArea widget. More complex widgets can simply build on the concepts covered in this tutorial. If you wish to build more complex widgets, I recommend reviewing the existing widgets in the console. This tutorial is meant to demonstrate the extensibility concepts.

1. Create Widget Class

   All widgets must implement the interface org.scrashmeow.ojb.console.ui.control.widget.Widget. It is preferred that the appropriate base class is chosen depending on what kind of field the widget is targeted for. For example: FieldDescriptorBasedWidget, CollectionDescriptorBasedWidget, ObjectReferenceDescriptorBasedWidget are all available in addition to the base class of all widgets BaseWidget.

   For the textarea widget, this widget is targeted torwards FieldDescriptors, so we will extend the FieldDescriptorBasedWidget.

   Our textarea widget will allow for certain properties to override the look and feel of the widget. We have chosen to support the rows and cols properties that correspond the the rows,cols attributes of the <textarea> html tag. In order to support these attributes, we must simply provide JavaBean getter/setters for each of the attributes.

   Here is the sample Java code for the widget:

   
   
   package org.scrashmeow.ojb.console.ui.control.widget;
   
   /**
    * A Sample Text Area Widget
    *
    * @author Alexander_Bibighaus
    */
   public class TextAreaWidget extends FieldDescriptorBasedWidget
   {
       public TextAreaWidget()
       {
           super();
       }
   
       /**
        * The getter for the cols attribute
        *
        * @return Integer
        */
       public Integer getCols()
       {
           if (getAttribute("cols") == null)
               return null;
   
           return Integer.valueOf((String) getAttribute("cols"));
       }
   
       /**
        * The getter for the rows attribute
        *
        * @return Integer
        */
       public Integer getRows()
       {
           if (getAttribute("rows") == null)
               return null;
   
           return Integer.valueOf((String) getAttribute("rows"));
       }
   
       /**
        * The setter for the rows attribute 
        *
        * @param rows 
        */
       public void setRows(Integer rows)
       {
           setAttribute("rows", rows.toString());
       }
       /**
        * The setter for the cols attribute
        *
        * @param cols
        */
       public void setCols(Integer cols)
       {
           setAttribute("cols", cols.toString());
       }
   }
   

2. Creating the Widget Tile

   Each widget is displayed using a Tile These tiles are usually very simple to write and simply contain the presentation view of the widget.

   Each tile is passed a bean under the name widget. You may access the bean properties of these widgets using the Struts HTML tags. Each widget should pass the value the widget collected via the value found in the formName attribute.

   Below is an example of our TextArea tile

   
   <!-- include the global include that all console jsp's should include -->
   <%@ include file="/includes/all.jsp" %>
   
   <!-- import our widget's bean (ie the class we just implemented ) -->
   <tiles:importAttribute name="widget" />
   
   <!-- display our widget using the Struts-EL HTML Tag lib -->
   <html-el:textarea rows="${widget.rows}" 
                     cols="${widget.cols}" 
                     property="${widget.formName}" />
   
   
   

3. Defining the Widget's Tile Definition

   Next, you must tell define a tiles definition for your widget. Please refer to the Tiles Documentation for more information. The tiles-defs.xml is found in src/web/WEB-INF.

   The TextArea's tile definitions looks like the following:

   <definition name=".textareaWidget" path="/widgets/textarea.jsp"></definition>
   

4. Defining Widget in the Console (OJBC.xml)

   The OJBC.xml contains all of the widget definitions available to the console. You must add an entry in this file to enable your widget. The OBJC.xml is found in etc/ojbc/OJBC.xml.

   The following snippet demonstrates how to define our Text Area widget.

   <widget-definitions>
   ...
       <widget-definition id="textarea"        
                             definition=".textareaWidget" 
                             className="org.scrashmeow.ojb.console.ui.control.widget.TextAreaWidget" 
                     />
   ...
   </widget-definitions>
   

5. Associating your widget with a datatype (Optional)

   If you would like your widget to be the default widget for a given data type, you may add an additional line in the OJBC.xml file.

   	<widget-associations>
   	 <widget-association type="LONGVARCHAR" widgetId="textarea" />
   	</widget-associations>
   

6. Associating your widget with a specific field on a class (Optional)

   You may associate your widget with any field on a class by modifying the ui_repository.xml configuration file found in etc/ojbc. In addition, you may set the values of the parameters your widget defineds.

   <class-descriptor name="org.scrashmeow.ojb.content.News">
   	
   	<field-descriptor name="body">
   		
   		<widget-descriptor id="textarea">
   			<widget-param>
   				<name>rows</name>
   				<value>10</value>
   			</widget-param>
   			<widget-param>
   				<name>cols</name>
   				<value>40</value>
   			</widget-param>
   				
   		</widget-descriptor>
   			
   	</field-descriptor>
   </class-descriptor>
   

7. Review Javadocs

   The API Docs for existing widgets may contain some helpful information. Please read over this documentation in addition to this tutorial.

   ---

   Copyright © 2003 Alexander Bibighaus et al. All rights Reserved.