Package de.xima.fc.interfaces.plugin.retval.form

Interface IPluginFormElementTemplateDescriptor

  • All Superinterfaces:
    Serializable
    All Known Implementing Classes:
    DefaultPluginFormElementTemplateDescriptor
    public interface IPluginFormElementTemplateDescriptor
extends Serializable
    Descriptor for a form element template from a plugin. A form element template is a pre-configured form element which is available in the drawer panel on the left-hand side of form designer and can be added to the form. Once added, any modifications to the template are not reflected in the added form element. A template may also be a container or fieldset element that contains other elements.

    There are multiple sources for form element templates:

    • Templates that were created by a user from an existing form element and are available to all forms of the same client. See FormTemplate.
    • Templates from form element template plugins, which may be available only to certain forms.
    Since:
    8.0.1
    Author:
    XIMA MEDIA GmbH

    • Method Detail

      • getClassName

        String getClassName()
        The name of the type of the main form element represented by this template. For example, when the template is a fieldset, this should return XFieldSet (=XFieldSet.class.getSimpleName()).
        Returns:
        The class name of the form element.

      • getDescription

        String getDescription​(Locale locale)
        The localized description for the template that may be shown in the form designer.
        Parameters:
        locale - Locale for localizing the description.
        Returns:
        The localized description of the template.

      • getIcon

        IPluginFormElementTemplateIcon getIcon​(Locale locale)
                                throws URISyntaxException
        Get the icon with the URI for the icon's data. The URI is then passed to loadIcon.

        The icon is shown, for example, in the panel in the form designer with the available templates. May return null, in which case a generic icon is used.

        Parameters:
        locale - Locale for localizing the icon.
        Returns:
        An input stream with the icon for the template, or null when no custom icon is available.
        Throws:
        URISyntaxException - When an URI could not be resolved. If this exception is thrown, a generic icon is used instead.
        RuntimeException - If a runtime exception is thrown, a generic icon is used instead.

      • getId

        String getId()
        Gets the unique ID of the template. The ID must be unique only within the set of templates returned by the plugin.
        Returns:
        The ID of this template.

      • getName

        String getName​(Locale locale)
        The localized display name for the template.
        Parameters:
        locale - Locale for localizing the name.
        Returns:
        The localized name of the template.

      • getPersistJson

        URI getPersistJson()
            throws URISyntaxException
        Gets the URI for the persist JSON with the content of the template. The URI is then passed to loadPersistJson.

        The persist JSON is a JSON string representing a JSON object. The encoding of the persist JSON string must be UTF-8. It has the following structure: 

         {
   "charsetName": "UTF-8",
   "persist": "...",
   "versionsNummer": 1
 }
        The properties charsetName and versionsNummer should always be set to UTF-8 and 1, respectively. The property persist is another string representing a JSON object with the following structure: 
         {
   "items": [
     {
       "properties": { ... },
       "className": "XTextField"
     },
     // more items
   ],
   "version": {
     "time": "23:10:09",
     "date": "09.08.2023",
     "timestamp": 20230809231009,
     "version": "hippocamp-9.0.0-SNAPSHOT",
     "majorVersion": "9",
     "minorVersion": "0",
     "patchVersion": "0",
     "number": 0
   }
 }
        The version refers to the formcycle version where the template was created. This version is used to update existing templates when e.g. a later formcycle version adds new properties.

        The items are a list of items contained in the template. The first item is always the main item and must have its className set to the same value as getClassName(). All following items, if present, must be children of the main item, and must have their XPropertyEnum.parentid set to either the main item or another child of the main item.

        The property properties is an object with the configuration of the form element. The keys are Enum.name(), the values are the corresponding values for the XPropertyEnum.

        Note 1: The resource might be cached with the returned URI as the cache key. Plugins should append e.g. a version parameter (such as the plugin version) to the URI if needed.

        Note 2: If you simply want provide static templates with form elements that you have already configured in the form designer, you can simply select the form element in the form designer, press Ctrl+c to copy the form element, go to a text editor and press Ctrl+v to paste the JSON string with the form element into the editor. This is the JSON string that you need to return in this method.

        Returns:
        An input stream for the persist JSON content of the template.
        Throws:
        URISyntaxException - When a URI could not be resolved. If this exception is thrown, the template is skipped as if it had not been returned by the plugin.
        RuntimeException - If this exception is thrown, the template is skipped as if it had not been returned by the plugin.

      • getTags

        Set<String> getTags​(Locale locale)
        Gets the localized tags of the template. The tags are used, for example, to filter the available templates by their tag name.
        Parameters:
        locale - Locale for localizing the tags.
        Returns:
        The localized tags of the template, if any.