Widgets

A widget is a form element or component, such as a input text field or a fieldset. By creating a widget plugin, you add your own, new, custom widgets to FORMCYCLE. Once the plugin is installed, users can select new widget in element selection of the Xima® Formcycle Designer and add them to the form.

Interface IXItemWidget

The interface IXItemWidget serves to define individual widget components. The interface IPluginFormElementWidget provides a way to make widgets available through plugin bundles.

Use cases

New HTML form components for common tasks such as captchas or cards
New components based on existing form elements that add a certain feature such as different looks or a different validation

Method signatures

void renderItem(Div container, XItemRenderData renderData, XItemRenderCtx renderCtx, IXFormRenderContext formRenderCtx)

This method takes a widget components and generates the HTML for that component.

parameters

This method takes the following parameters

container: The HTML DIV element which is the parent in the form element tree. The created HTML component needs to be inserted into the form element tree with container.appendChild(...).
renderData: Provides access to the render data via the interface XItemRenderData and thereby access to the following: :* The configured widget properties (Method: getProperties()). The returned properties may be default or newly created form element properties :* Central Properties of the form (Method: getXFormRenderConfig()) :* The currently transmitted form values (Methode: getValuesMap())
renderCtx: Provides access to methods which give support during the rendering process (via the interface XItemRenderCtx): :* registerParent(): Makes it possible to register the widget component in such a way that further child elements can be registered. :* addHtmlAttributes(): Add the defined attributes to the rendered HTML form :* addValidationAttributes(): Adds all attributes which are need for validation to the rendered element
formRenderCtx: Provides access to the form request sesseion attributes

default void renderItemPreview(Div container, XItemRenderData renderData, XItemRenderCtx renderCtx, IXFormRenderContext formRenderCtx)

By default, the widget is displayed the same way both in the form and in the Xima® Formcycle Designer. When you choose to implement this method, you can change how the form element look in the designer. The parameters this method takes are the same as for the method renderItem(...). Xima® Formcycle provides a default implementation for this method.

ArrayList<XItemPropertyDesc> getAvailableProperties(Locale locale)

Defines a list of configuration properties required by this widget. For each property, you can create an editor in the Xima® Formcycle Designer that lets users choose a value for the property. You can then access the values for each property when the item is rendered by the method renderItem(...). This method lets you define your own custom properties for the widget. When necessary, it is also possible to reuse existing property defined by Xima® Formcycle - the enum XPropertyEnum contains a list of all existing properties.

Parameters

This method takes the following parameters:

locale: Provides information about the current language and region

Sample implementation of the method getAvailableProperties(...) with typical settings

@Override
public ArrayList<XItemPropertyDesc> getAvailableProperties(Locale locale) {
  ArrayList<XItemPropertyDesc> PROPERTIES = new ArrayList<XItemPropertyDesc>() {
   {
     // Basis-Attribute
     add(new XItemPropertyDesc(XPropertyEnum.name));
      add(new XItemPropertyDesc(XPropertyEnum.aliasname));
      add(new XItemPropertyDesc(XPropertyEnum.id));
      add(new XItemPropertyDesc(XPropertyEnum.parentid));
      add(new XItemPropertyDesc(XPropertyEnum.rowid));
      add(new XItemPropertyDesc(XPropertyEnum.flex));
      add(new XItemPropertyDesc(XPropertyEnum.computedwidth));

      add(new XItemPropertyDesc(XPropertyEnum.textalign));
      add(new XItemPropertyDesc(XPropertyEnum.cssclasses));
      add(new XItemPropertyDesc(XPropertyEnum.helptext));
      add(new XItemPropertyDesc(XPropertyEnum.i18n));
      add(new XItemPropertyDesc(XPropertyEnum.statusdependent));
      add(new XItemPropertyDesc(XPropertyEnum.viewstatus));
      add(new XItemPropertyDesc(XPropertyEnum.usergrouppendent));
      add(new XItemPropertyDesc(XPropertyEnum.viewusergroup));

      add(new XItemPropertyDesc(XPropertyEnum.readonly_statusdependent));
      add(new XItemPropertyDesc(XPropertyEnum.readonly_viewstatus));
      add(new XItemPropertyDesc(XPropertyEnum.readonly_usergrouppendant));
      add(new XItemPropertyDesc(XPropertyEnum.readonly_viewusergroup));

     // Bedingungen
     add(new XItemPropertyDesc(XPropertyEnum.isdisabled));
      add(new XItemPropertyDesc(XPropertyEnum.attributes));

      add(new XItemPropertyDesc(XPropertyEnum.requiredif));
      add(new XItemPropertyDesc(XPropertyEnum.requiredifcomp));
      add(new XItemPropertyDesc(XPropertyEnum.requiredifvalue));

      add(new XItemPropertyDesc(XPropertyEnum.readonlyif));
      add(new XItemPropertyDesc(XPropertyEnum.readonlyifmode));
      add(new XItemPropertyDesc(XPropertyEnum.readonlyifcomp));
      add(new XItemPropertyDesc(XPropertyEnum.readonlyifvalue));

      add(new XItemPropertyDesc(XPropertyEnum.hiddenif));
      add(new XItemPropertyDesc(XPropertyEnum.hiddenifcomp));
      add(new XItemPropertyDesc(XPropertyEnum.hiddenifvalue));

      add(new XItemPropertyDesc(XPropertyEnum.ishidden));
      add(new XItemPropertyDesc(XPropertyEnum.isreadonly));

      add(new XItemPropertyDesc(XPropertyEnum.comment));
   }
};
return PROPERTIES;
}

boolean isSubmitsValues()

This Method declares whether or not the widget provides form input at runtime, which will be transmitted to the Xima® Formcycle server on submit.

String getPrefix()

Defines a prefix which will be added to the element name on use within the Xima® Formcycle Designer.

String getLabel()

Defines the name of the widget in the element list of the Xima® Formcycle Designer.

default XValidationResult validate(List<String[]> values, Locale locale, Map<Serializable, Serializable> frqSessionAttributes)

Provides a way to validate the submitted value for this widget. This way you can provide feedback to the user and reject submitted forms with invalid data.

Parameters

This method takes the following parameters:

values: A list of value submitted with the form
locale: Provides information about the current language and region
frqSessionAttributes: A map with values from the form request session

Return value

The return value is an XValidationResult object. When you create a new object of this class, you can pass a boolean value to indicate whether the submitted value is valid; and a message string with the error message.

Including JavaScript and CSS resources with the widget

Widgets may define their own JavaScript and CSS resources, which will be included on use in the designer as well as in the rendered form. To include these resources they have to be placed inside a predefined folder.

Resources that should be available in the Xima® Formcycle Designer need to be put in a specific sub directory in the plugin JAR:

CSS resources: includes/designer/designer-min.js
JavaScript ressources: Includes/designer/designer-min.css

Resources that should be available in the rendered form need to have the same name as the widget class.

CSS resources: includes/css/<Java class name of the widget implementation>.css
Example for widget implementation with class name XMyWidget:
includes/css/XMyWidget.css.
JavaScript resources: includes/js/<Java class name of the widget implementation>.js
Example for widget implementation with class name XMyWidget:
includes/js/XMyWidget.js.

Maven can help with its build processes to create this kind of target path structure and to minify the included JavaScript an CSS resources.

The following example assumes the following folder structure:

Example project structure

To create the folders and minify the CSS and JavaScript files, you can add the following maven plugin:

Maven plugin for minifying CSS and JS files

...
<build>
   <plugins>
     <plugin>
       <groupId>com.samaxes.maven</groupId>
       <artifactId>minify-maven-plugin</artifactId>
       <version>1.7.6</version>
       <configuration>
         <charset>UTF-8</charset>
         <closureWarningLevels>
           <misplacedTypeAnnotation>OFF</misplacedTypeAnnotation>
           <es5Strict>OFF</es5Strict>
           <unknownDefines>OFF</unknownDefines>
           <nonStandardJsDocs>OFF</nonStandardJsDocs>
           <uselessCode>OFF</uselessCode>
         </closureWarningLevels>
         <jsEngine>CLOSURE</jsEngine>
         <closureCreateSourceMap>false</closureCreateSourceMap>
         <closureDefine>
           <DEFINE_TEST>false</DEFINE_TEST>
         </closureDefine>
         <closureLanguageIn>ECMASCRIPT5</closureLanguageIn>
         <closureLanguageOut>ECMASCRIPT5</closureLanguageOut>
         <nosuffix>true</nosuffix>
         <webappSourceDir>/</webappSourceDir>
         <webappTargetDir>/</webappTargetDir>
       </configuration>
       <executions>
         
         <execution>
           <id>default-minify</id>
           <configuration>
             <skipMinify>false</skipMinify>
             <skipMerge>true</skipMerge>
             <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
             <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
             <jsTargetDir>${project.build.directory}/classes/includes/</jsTargetDir>
             <cssTargetDir>${project.build.directory}/classes/includes/</cssTargetDir>
             <jsSourceIncludes>
               <jsSourceInclude>js/**/*.js</jsSourceInclude>
             </jsSourceIncludes>
             <cssSourceIncludes>
               <cssSourceInclude>css/**/*.css</cssSourceInclude>
             </cssSourceIncludes>
           </configuration>
           <goals>
             <goal>minify</goal>
           </goals>
         </execution>

         
         <execution>
           <id>default-minify-designer-css</id>
           <configuration>
             <skipMinify>false</skipMinify>
             <skipMerge>false</skipMerge>
             <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
             <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
             <cssTargetDir>${project.build.directory}/classes/includes/designer/</cssTargetDir>
             <cssSourceIncludes>
               <cssSourceInclude>designer/widget.css</cssSourceInclude>
             </cssSourceIncludes>
             <cssFinalFile>designer-min.css</cssFinalFile>
           </configuration>
           <goals>
             <goal>minify</goal>
           </goals>
         </execution>

         
         <execution>
           <id>default-minify-desiger.js</id>
           <configuration>
             <skipMinify>true</skipMinify>
             <skipMerge>false</skipMerge>
             <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
             <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
             <jsTargetDir>${project.build.directory}/classes/includes/designer/</jsTargetDir>
             <jsSourceIncludes>
               <jsSourceInclude>designer/I18N.js</jsSourceInclude>
               <jsSourceInclude>designer/Properties.js</jsSourceInclude>
               <jsSourceInclude>js/XDatalistWidget.js</jsSourceInclude>
             </jsSourceIncludes>
             <jsFinalFile>designer-min.js</jsFinalFile>
           </configuration>
           <goals>
             <goal>minify</goal>
           </goals>
         </execution>
       </executions>
     </plugin>
      ...
   </plugins>
</build>
...

Interface IPluginFormElementWidget

The interface IPluginFormElementWidget serves to provide widget components from a plugin bundle.

Method signatures

The plugin interface IPluginProcessing references all methods provided by the base interface IFCPlugin and also the following:

List<Class> getWidgets(Locale locale)

Parameters

This method takes the following parameters:

locale ::Provides information about the current language and region

Return value

A list of objects that implements IXItemWidget