Custom Widgets

Revision as of 14:27, 23 November 2006

Custom Widgets

When creating XML content the input methods available with the existing widget types might not suffice for the desired content. The existing widget types are limited to the use cases required for OpenCms. For example, they do not support dynamic configuration.

An example custom widget could for example display a drop down selection of the company's employees which is retrieved from a database.

A new widget type is created by subclassing A_CmsWidget or one of the existing widget classes. It is a good idea to take a look at them as it can save a lot of work.

To decorate an XML element with the new widget it is referenced from the layout annotation in the XML Schema just as the existing widget types. The reference can be

• the FQCN (fully qualified class name) of the widget class or
• an alias name just like HtmlWidget etc

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">
  <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd" />
  ...
  ... your complexType definitions which include an element Manager and Developer
  ...
   <xsd:annotation>
     <xsd:appinfo>
       <layouts>
         <layout element="Manager" widget="AcmeEmployeeSelectionWidget" />
         <layout element="Developer" widget="com.acme.widgets.AcmeEmployeeSelectionWidget" />
       </layouts>
     </xsd:appinfo>
  </xsd:annotation> 
</xsd:schema>

Alias names are defined in opencms-vfs.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.opencms.org/dtd/6.0/opencms-vfs.dtd">
<opencms>
  <vfs>
     ...
     <xmlcontent>
       ...
       <widgets>
         ...
         <widget class="com.acme.widgets.AcmeEmployeeSelectionWidget"
           alias="AcmeEmployeeSelectionWidget" />
       </widgets>
       ...
     </xmlcontent>
  </vfs>
</opencms>

You need to restart OpenCms to activate the change.