Widgets

Modified on Mon, 17 Jul, 2023 at 9:16 AM

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 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 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(...). 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 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 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 formcycle server on submit.

String getPrefix()

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

String getLabel()

Defines the name of the widget in the element list of the 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 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>
          <!-- Providing resources for use in the rendered form -->
          <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>
 
          <!-- Providing CSS resources for use in the Designer -->
          <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>

          <!-- Providing JavaScript resources for use in the Designer -->
          <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