Data privacy notice

 

When this content is loaded, usage information is transmitted to Vimeo and may be processed there.

 

             

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

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article