Suggested Pages

Friday, April 27, 2012

Example Custom Widget OpenCMS


Before describing how to write custom widget for OpenCMS, i make a brief summary on the role of widgets in OpenCMS.
OpenCMS uses Widgets to perform interaction between administrators/editors and the CMS. An example of a tipical widget is TextAreaWidget. This widget allows editors to insert long descriptions inside a Structured Content. An other example of widget is Calendar Widget that allows the redactors to select a date in a calendar.

Create a Custom Widget consists of three steps:

  1. Create a Java class inside your custom modules
  2. Add the new widget in the configuration file opencms-vfs.xml
  3. Use the widget within the Structured Content

Step 1: Extends an existing Java Class available from the API of OpenCMS


The developer should extend functionality of an existing widget. In this example I have extended the class CmsCalendarWidge because I want to inherit behaviour and a part of the HTML code of the existing widget.

package custom.simple.widget;

....

public class CmsCalendarCustomWidget extends CmsCalendarWidget {
 
   
 public CmsCalendarCustomWidget() {
  super();
 }
 

 public CmsCalendarCustomWidget(String configuration) {
  super(configuration);
 }

 
 @Override
 public I_CmsWidget newInstance() {
  return new CmsCalendarCustomWidget(getConfiguration());
 }

 
 
 @Override
 public String getDialogWidget(CmsObject cms, I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter param) {
  
  StringBuffer result = new StringBuffer();
   result.append("");

   /*  In this method,  developer can put code to implement  specific functions of the widget.
the developer can write HTML to realize graphic components
   */ 
 
  result.append("
"); return result.toString(); } }

Step 2: Modify opencms-vfs.xml


OpenCMS uses many files of configuration as opencms-vfs.xml. This file is located at the path /WEB-INF/config/opencms-vfs.xml. The developer has to insert the class that implements the new widget and give it an alias in order to reuse the alias in the definition of the Structured Content.
<xmlcontent>
      <widgets>
        ...
        <widget class="custom.simple.widget.CmsCalendarCustomWidget" alias="MyWidget"/>
        ...
      </widgets>
      <schematypes>
          ...
      </schematypes>
</xmlcontent>

Step 3: Use new Widget in the Structured Content


The developer can use the alias given to the widget in the previous step and associate it with an Element defined in the structured content. As we can see the right position to give this inform ation is the <xsd:annotation> tag
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

 <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
 
 <xsd:element name="Videoleziones" type="OpenCmsSimpleStructuredContents"/>
 
 <xsd:complexType name="OpenCmsSimpleStructuredContents">
  <xsd:sequence>
   <xsd:element name="SimpleStructuredContent" type="OpenCmsSimpleStructuredContent" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="OpenCmsSimpleStructuredContent">
  <xsd:sequence>
   <xsd:element name="Titolo" type="OpenCmsString" />
   <xsd:element name="Data" type="OpenCmsDateTime" />
  </xsd:sequence>
 </xsd:complexType>
 <xsd:annotation>
  <xsd:appinfo>
   <layouts>
    <layout element="Titolo" widget="StringWidget" />
    <layout element="Data" widget="MyWidget" />
   </layouts>
  </xsd:appinfo>
 </xsd:annotation>  
</xsd:schema>
I hope this mini guide could help developers to know the elements he needs to write a custom widget in OpenCMS.

No comments :

Post a Comment

Suggested Pages