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

Interface IPluginFormElementWidget

  • All Superinterfaces:
    IFCPlugin, IFCRemoteSyncPlugin, INamedUiElement, INameProviding, ITransferable, Serializable
    public interface IPluginFormElementWidget
extends IFCRemoteSyncPlugin
    Interface for plugins to integrate own form element widgets within the form designer. These widgets are added to the drawer panel that usually contain the built-in standard items such as input fields and select elements.

    To create a form element widget, you need to create class that implements IXItemWidget. This class contains the server side logic of the plugin, such as how the HTML is rendered and how the data is validated. Optionally, you can also create a JavaScript file that will be loaded when the form designer is opened. This JavaScript file can contain custom client side logic. It can be used, for example, when you need to declare additional item properties or when you need custom property editors in the form designer.

    See the node module fc-form-designer (available via the custom XIMA npm registry) for more details regarding the contents of the JavaScript file. That module contains the TypeScript declaration files with the client side API.

    Author:
    XIMA MEDIA GmbH

    • Method Detail

      • getCssData

        @Deprecated
default String getCssData()
        Deprecated.
        Use getCssResource().
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the widget within the form designer. Note that these styles should apply only to the form widget element. If you need additional styles for the form designer UI, such as for custom editors, use getCssDataForDesignerUi().

        The default implementation reads the #getCssPath() via {getResourceAsString(String).

        Returns:
        The contents of the CSS to include in form when the form is edited within the form designer.

      • getCssDataForDesignerUi

        @Deprecated
default String getCssDataForDesignerUi()
                                throws IOException
        Deprecated.
        Use getCssForDesignerUiResource()
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the designer UI, such as for custom property editors. Styles from with CSS file are not available within the form, use getCssData() for styles that should apply to the widget form element.

        The default implementation returns null, which loads no additional styles.

        Returns:
        The contents of the CSS to include in the form designer UI context, outside the form.
        Throws:
        IOException - When the data could not be loaded.

      • getCssForDesignerUiResource

        @Deprecated
default IResourceDescriptor getCssForDesignerUiResource()
                                                 throws URISyntaxException
        Deprecated.
        Use getCssForDesignerUiResource(IPluginFormElementGetResourceParams).
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the designer UI, such as for custom property editors. Styles from with CSS file are not available within the form, use getCssResource() for styles that should apply to the widget form element.

        The default implementation returns null, which loads no additional styles.

        The returned resource may get cached with the IResourceDescriptor.getAbsoluteUri() as the cache key. We recommend you add e.g. the version as a cache parameter to the URI.

        Returns:
        The contents of the CSS to include in the form designer UI context, outside the form.
        Throws:
        URISyntaxException - When the resource descriptor could not be created due to an invalid URL.
        Since:
        8.0.0

      • getCssForDesignerUiResource

        default IResourceDescriptor getCssForDesignerUiResource​(IPluginFormElementGetResourceParams params)
                                                 throws URISyntaxException
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the designer UI, such as for custom property editors. Styles from with CSS file are not available within the form, use getCssResource() for styles that should apply to the widget form element.

        The default implementation returns #getCssForDesignerUiResource().

        The returned resource may get cached with the IResourceDescriptor.getAbsoluteUri(). We recommend you add e.g. the version of the plugin as a cache parameter to the URI.

        For example, if the resources exists as a class path resource, you can use: 

         return UrlResourceDescriptor.forClasspathResource(getClass(), "path/to/dir/style.css", UTF_8);
        Parameters:
        params - Parameters for obtaining the resource. The resource content should depend only on these parameters, as it may be cached.
        Returns:
        The contents of the CSS to include in the form designer UI context, outside the form.
        Throws:
        URISyntaxException - When the resource descriptor could not be created due to an invalid URL.
        Since:
        8.0.0

      • getCssPath

        @Deprecated
default String getCssPath()
        Deprecated.
        Use getJavaScriptResource()
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the widget within the form designer. Note that these styles should apply only to the form widget element. If you need additional styles for the form designer UI, such as for custom editors, use getCssDataForDesignerUi().

        The returned path must point to an existing resource in the classpath of this plugin.

        The default implementation expects the resource to be located at includes/designer/designer-min.css.

        Returns:
        The path where the CSS resource is located.

      • getCssResource

        default IResourceDescriptor getCssResource​(IPluginFormElementGetResourceParams params)
                                    throws URISyntaxException
        Return the path to the CSS file that is loaded when the form designer is opened. This file should contain additional styles required for the widget within the form designer. Note that these styles should apply only to the form widget element. If you need additional styles for the form designer UI, such as for custom editors, use getCssForDesignerUiResource().

        The default implementation returns #getCssResource().

        The returned resource may get cached with the IResourceDescriptor.getAbsoluteUri(). We recommend you add e.g. the version of the plugin as a cache parameter to the URI.

        For example, if the resources exists as a class path resource, you can use: 

         return UrlResourceDescriptor.forClasspathResource(getClass(), "path/to/dir/style.css", UTF_8);
        Parameters:
        params - Parameters for obtaining the resource. The resource content should depend only on these parameters, as it may be cached.
        Returns:
        The contents of the CSS to include in form when the form is edited within the form designer.
        Throws:
        URISyntaxException - When the resource descriptor could not be created due to an invalid URL.
        Since:
        8.0.0

      • getJavaScriptData

        @Deprecated
default String getJavaScriptData()
        Deprecated.
        Use getJavaScriptResource().
        Returns the contents of the JavaScript file that is loaded when the form designer is opened . This file should contain the setup logic for the designer, such as adding custom properties or editors.

        The default implementation reads the #getJavaScriptPath() via {getResourceAsString(String).

        See the node module fc-form-designer (available via the custom XIMA npm registry) for more details regarding the contents of the JavaScript file. That module contains the TypeScript declaration files with the client side API.

        Returns:
        The contents of the JavacScript to include in the form designer.

      • getJavaScriptPath

        @Deprecated
default String getJavaScriptPath()
        Deprecated.
        Use getJavaScriptResource()
        Returns the path to the JavaScript file that is loaded when the form designer is opened. This file should contain the setup logic for the designer, such as adding custom properties or editors. The returned path must point to an existing resource in the classpath of this plugin.

        The default implementation expects the resource to be located at includes/designer/designer-min.js.

        See the node module fc-form-designer (available via the custom XIMA npm registry) for more details regarding the contents of the JavaScript file. That module contains the TypeScript declaration files with the client side API.

        Returns:
        The path where the JavaScript resource is located.

      • getJavaScriptResource

        default IResourceDescriptor getJavaScriptResource​(IPluginFormElementGetResourceParams params)
                                           throws URISyntaxException
        Returns the contents of the JavaScript file that is loaded when the form designer is opened . This file should contain the setup logic for the designer, such as adding custom properties or editors.

        The default implementation returns #getJavaScriptResource().

        See the node module fc-form-designer (available via the custom XIMA npm registry) for more details regarding the contents of the JavaScript file. That module contains the TypeScript declaration files with the client side API.

        The returned resource may get cached with the IResourceDescriptor.getAbsoluteUri(). Use getJavaScriptRuntimeData if you need to provide custom data to the client-side JavaScript, such as a list of available entities. We recommend you add e.g. the version of the plugin as a cache parameter to the URI.

        For example, if the resources exists as a class path resource, you can use: 

         return UrlResourceDescriptor.forClasspathResource(getClass(), "path/to/dir/script.js", UTF_8);
        Parameters:
        params - Parameters for obtaining the resource. The resource content should depend only on these parameters, as it may be cached.
        Returns:
        The resource with the contents of the JavacScript to include in the form designer.
        Throws:
        URISyntaxException - When the resource descriptor could not be created due to an invalid URL.
        Since:
        8.0.0

      • getJavaScriptRuntimeData

        default Map<String,​Object> getJavaScriptRuntimeData​(IPluginFormElementWidgetGetRuntimeDataParams params)
        This method can be used to provide additional data to the getJavaScriptResource(IPluginFormElementGetResourceParams) () client-side JavaScript} code for the widget. The returned data is stringified as a JSON object and made available to the JavaScript code via window.Designer.instance().config.pluginData['plugin-name'], where plugin-name is IFCPlugin.getName().
        Parameters:
        params - Parameters with details about the current form designer context, such as the opened form.
        Returns:
        Additional data made available to the JavaScript code. Can be a JSONObject.
        Throws:
        RuntimeException - Exceptions are caught, logged, and ignored otherwise.

      • getResource

        @Deprecated
default InputStream getResource​(String path)
        Deprecated.
        This a helper method that does not belong to the plugin. Use getJavaScriptResource, getCssResource, or getCssForDesignerUiResource directly.
        Reads the resource at the given path. The default implementation simply reads the resource at the given path from the class loader of this plugin. Normally you should not have to override this method.
        Parameters:
        path - The path from which to load the CSS file.
        Returns:
        The data with CSS resource.

      • getResourceAsString

        @Deprecated
default String getResourceAsString​(String path)
        Deprecated.
        This a helper method that does not belong to the plugin. Use getJavaScriptResource, getCssResource, or getCssForDesignerUiResource directly.
        Reads the resource at the given path. The default implementation simply reads the resource at the given path from the class loader of this plugin. Normally you should not have to override this method.
        Parameters:
        path - The path from which to load the CSS file.
        Returns:
        The data with CSS resource.

      • getWidgets

        List<Class<? extends IXItemWidget>> getWidgets​(Locale locale)
        Parameters:
        locale - Current locale.
        Returns:
        The list of all available form element widgets.

      • isAvailableInDesigner

        default boolean isAvailableInDesigner​(IPluginFormElementWidgetIsAvailableInDesignerParams params)
        Optional method for checking whether a widget is available in the form designer. This method is called when a new form designer is opened, and is passed the current project being edited, as well as the widget to check. It is called once for each widget returned by getWidgets(Locale). When this method returns false, the widget is not shown in the list of available elements in the designer. When the form already contains an instance of the widget, an error message is shown to the user that the widget could not be found.

        This method lets you omit certain widgets under certain circumstances. The default implementation simply returns true.

        Parameters:
        params - Parameters with the widget to check and the current project being edited.
        Returns:
        Whether the widget is available.
        Since:
        7.0.0