Interface IElementHandler<TData,TElement extends IWorkflowElementEntity>
-
- Type Parameters:
TData
- Type of the properties model for the workflow element. UseJSONObject
if you want to get the raw data and possibly perform serialization / deserialization yourself. SeegetDataModelClass()
.TElement
- Type of the workflow element, i.e. a node or trigger.
- All Superinterfaces:
ICustomParametersUpdateable
,IResourceBundleLocator
,IWorkflowElementTypeProviding
- All Known Subinterfaces:
IBaseActionClientHandlerNode<TData>
,IBaseActionNode<TData>
,IBaseConditionClientHandlerNode<TData>
,IBaseDoUntilLoopClientHandlerNode<TData>
,IBaseTrigger<TData>
,IBaseWhileLoopClientHandlerNode<TData>
,IBeanValidatingElement<TData,TElement>
,IBeanValidatingNode<TData>
,IBeanValidatingTrigger<TData>
,IBuiltinNodeType<TData>
,IBuiltinResourcesHandler<TData,TElement>
,IBuiltinTriggerType<TData>
,IDefaultClientHandlerNode<TData>
,IDefaultClientHandlerTrigger<TData>
,IExecutingLikeActionNode<TData>
,IExecutingLikeBinarySelectionNode<TData>
,IExecutingLikeControlTransferNode<TData>
,IExecutingLikeExceptionHandlerNode<TData>
,IExecutingLikeMultiSwitchNode<TData>
,IExecutingLikePostTestLoopNode<TData>
,IExecutingLikePreTestLoopNode<TData>
,IExecutingLikeReturningActionNode<TData>
,IExecutingLikeReturnNode<TData>
,IExecutingLikeSequenceNode<TData>
,IExecutingLikeThrowNode<TData>
,IFileProviding<TData>
,IHierarchyValidatingNode<TData>
,IKeyValueSummarizableElement<TData,TElement>
,IKeyValueSummarizableNode<TData>
,IKeyValueSummarizableTrigger<TData>
,ILoopStatementMustLoopValidating<TData>
,IMultipleCheckPropertiesNode<TData>
,INodeHandler<TData>
,IOfficialHelpPageElement<TData,TElement>
,IOfficialHelpPageNode<TData>
,IOfficialHelpPageTrigger<TData>
,IPluginActionNodeHandler<TData>
,IPluginConditionNodeHandler<TData>
,IPluginDoUntilLoopNodeHandler<TData,TState>
,IPluginTriggerHandler<TData>
,IPluginWhileLoopNodeHandler<TData,TState>
,IResultlessNode<TData>
,ISemverUpdating<TData,TElement>
,ISemverUpdatingNode<TData>
,ISemverUpdatingTrigger<TData>
,ISequentialUpdating<TData,TElement,TVersion>
,ISingleBaseActionBuiltinNodePrototype<TData>
,ISingleBaseActionNodePrototype<TData>
,ISingleBaseBuiltinTriggerPrototype<TData>
,ISingleBaseConditionNodePrototype<TData>
,ISingleBaseDoUntilLoopNodePrototype<TData>
,ISingleBaseTriggerPrototype<TData>
,ISingleBaseWhileLoopNodePrototype<TData>
,ISingleBuiltinNodePrototype<TData>
,ISingleBuiltinTriggerPrototype<TData>
,ISingleElementPrototype<TData,TElement>
,ISingleNodePrototype<TData>
,ISingleTriggerPrototype<TData>
,ISpecificTriggerListener<TData>
,ITriggerHandler<Model>
- All Known Implementing Classes:
APluginActionNodeHandler
,APluginConditionNodeHandler
,APluginDoUntilLoopNodeHandler
,APluginTriggerHandler
,APluginWhileLoopNodeHandler
,FcBreakHandler
,FcCatchErrorHandler
,FcChangeFormAvailabilityHandler
,FcChangeFormValueHandler
,FcChangeStateHandler
,FcCompressAsZipHandler
,FcContinueHandler
,FcCopyFormRecordHandler
,FcCounterHandler
,FcCreateTextFileHandler
,FcDecodeBase64Handler
,FcDeleteAttachmentHandler
,FcDeleteFormRecordHandler
,FcDoiInitHandler
,FcDoiVerifiedHandler
,FcDoUntilLoopHandler
,FcEmailHandler
,FcEmptyHandler
,FcEncodeBase64Handler
,FcExperimentHandler
,FcExportToPersistenceHandler
,FcExportToXmlHandler
,FcFillPdfHandler
,FcFillWordHandler
,FcForEachLoopHandler
,FcFormRecordMessagePostedHandler
,FcFormRecordMessageUploadRequestFulfilledHandler
,FcFormSubmitButtonHandler
,FcHttpRequestHandler
,FcImportFormValueFromXmlHandler
,FcInvitationErrorHandler
,FcInvitationSentHandler
,FcLdapQueryHandler
,FcLogEntryHandler
,FcManualHandler
,FcMoveFormRecordToInboxHandler
,FcMultipleConditionHandler
,FcProcessHistoryPdfHandler
,FcProcessLogPdfHandler
,FcProvideResourceHandler
,FcQualifiedFormSubmitButtonHandler
,FcQueueTaskHandler
,FcRedirectHandler
,FcRenewProcessIdHandler
,FcReturnFileHandler
,FcReturnHandler
,FcSaveToFileSystemHandler
,FcSaveToWebDavHandler
,FcSendFormRecordMessageHandler
,FcSequenceHandler
,FcSetSavedFlagHandler
,FcShowTemplateHandler
,FcSqlStatementHandler
,FcStateTimerHandler
,FcSwitchCaseHandler
,FcSwitchDefaultHandler
,FcSwitchHandler
,FcThrowExceptionHandler
,FcTimePointHandler
,FcUserInvocationHandler
,FcWhileLoopHandler
,FcWriteFormRecordAttrHandler
public interface IElementHandler<TData,TElement extends IWorkflowElementEntity> extends IWorkflowElementTypeProviding, ICustomParametersUpdateable, IResourceBundleLocator
All element handlers must be thread-safe. Usually you should not have any instance fields in your handler.Interface for registering workflow elements. Each workflow element is of a given type, and a handler needs to be registered for each type. The handler is responsible for processing the workflow element during execution, for displaying the node during editing, and for validating the node.
For plugins, it is strongly recommended that you override
getVersion()
and use the version of the plugin instead.- Since:
- 7.0.0
- Author:
- XIMA MEDIA GmbH
-
-
Field Summary
Fields Modifier and Type Field Description static String
CURRENT_HANDLER_VERSION
The version string of the current formcycle application, as returned by default bygetVersion()
.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description default String
extractDescription(TData data)
Retrieves the name that will be stored asAWorkflowElement.getDescription()
.default String
extractName(TData data)
Retrieves the name that will be stored asAWorkflowElement.getName()
.default Map<String,List<String>>
extractSearchTerms(IExtractSearchTermsParams<TData> params)
Each workflow element may have one or more search terms that are used in database queries to filter the applicable elements.This methods lets you define custom search terms based on the properties of the workflow element.default IResourceDescriptor
getCascadingStyleSheet(boolean devMode)
Deprecated.ImplementgetCascadingStyleSheet(Locale, boolean)
instead.default IResourceDescriptor
getCascadingStyleSheet(Locale locale, boolean devMode)
Retrieves the CSS resources required by elements of this kind, when this node is displayed in the workflow designer.Class<? extends TData>
getDataModelClass()
Returns the class of the custom properties used by the elements handled by this element logic handler.default String
getDisplayLabel(IGetDisplayLabelParams<TData> params)
Retrieves the display label for a workflow element.default Serializable
getElementSummaryModel(IGetElementSummaryParams<TData> params)
When the user clicks on the info icon of a node or trigger, an panel with a quick summary of that node or trigger opens.default URL
getElementSummaryXhtml()
When the user clicks on the info icon of a node or trigger, an panel with a quick summary of that node or trigger opens.default IFastJsonConverter
getFastJsonConverter()
Finds the converter that is used to convert between the properties model (getDataModelClass()
) and its JSON representation.default de.xima.cmn.criteria.FilterCriterion
getFilterCriteriaForEntities(IGetFilterCriteriaForEntitiesParams params)
Similar toreadEntityReferences(IReadEntityRefsParams)
, but on a database level.default IElementHelpLocation
getHelpPageLocation(Locale locale)
default IResourceDescriptor
getJavaScript(boolean devMode)
Deprecated.ImplementgetJavaScript(Locale, boolean)
instead.default IResourceDescriptor
getJavaScript(Locale locale, boolean devMode)
Retrieves the JavaScript resources required by elements of this kind.String
getLocalizedTypeName(Locale locale)
default Class<? extends IElementPropertiesBean<TData,TElement>>
getPropertiesBeanClass()
Returns the class of the bean that should be used when editing the properties of a workflow element.URL
getPropertiesViewXhtml()
This method must return the path to the XHTML page for the custom user interface.default ResourceBundle
getResourceBundle(Locale locale)
Retrieves the resource bundle that should be used, for example, for custom validation messages generated during validation.default String
getVersion()
Finds the current version of this element handler.default boolean
isAvailable(IIsAvailableParams<TData> params)
Checks whether this workflow element is available to the given client.default boolean
isHasUserVisibleName()
Checks whether this workflow element has a user-facingextractName(Object)
.default Iterable<IEntityReferenceDescriptor>
readEntityReferences(IReadEntityRefsParams<TData> params)
Extracts all entity references from the given properties model.default Iterable<IPlaceholderProperty<?,?>>
readPlaceholders(IReadPlaceholdersParams<TData> params)
Finds and returns all placeholders that are contained in the given properties model.default void
validateGlobal(IElementGlobalValidationParams<TData,TElement> params)
Similar tovalidateLocal
, but performs validations that require knowledge about other workflow elements.IWorkflowElementValidationResult
validateLocal(IElementLocalValidationParams<TData,TElement> params)
Performs a local validation of the given workflow workflow element properties.default int
writeEntityReferences(IWriteEntityRefsParams<TData> params)
Writes all given entity references back to the given properties model.default void
writePlaceholders(IWritePlaceholdersParams<TData> params)
Writes all placeholders to the given properties model.-
Methods inherited from interface de.xima.fc.interfaces.workflow.ICustomParametersUpdateable
updateCustomParams
-
Methods inherited from interface de.xima.fc.interfaces.workflow.IWorkflowElementTypeProviding
getType
-
-
-
-
Field Detail
-
CURRENT_HANDLER_VERSION
static final String CURRENT_HANDLER_VERSION
The version string of the current formcycle application, as returned by default bygetVersion()
. Does not include suffixes etc., only major, minor, and patch.
-
-
Method Detail
-
extractDescription
default String extractDescription(TData data)
Retrieves the name that will be stored asAWorkflowElement.getDescription()
. For example, actions may let the user enter a description for the action, which would be returned by this method. A condition node may an explanation of the test condition as the description.The default implementation checks whether the
getDataModelClass()
implementsIDescriptionProviding
and if it does, returnsIDescriptionProviding.getDescription()
. Otherwise returns an empty string.- Parameters:
data
- The data of the workflow element for which to retrieve the description.- Returns:
- The description of the workflow element with the given data.
-
extractName
default String extractName(TData data)
Retrieves the name that will be stored asAWorkflowElement.getName()
. For example, actions may let the user enter the name of the action, which would be returned by this method. A condition node may use a summary of the test condition as the name. A button trigger event may use the name of the button.The default implementation checks whether the
getDataModelClass()
implementsINameProviding
and if it does, returnsINameProviding.getName()
.- Parameters:
data
- The data of the workflow element for which to retrieve the name.- Returns:
- The name of the workflow element with the given data.
-
extractSearchTerms
default Map<String,List<String>> extractSearchTerms(IExtractSearchTermsParams<TData> params)
Each workflow element may have one or more search terms that are used in database queries to filter the applicable elements.This methods lets you define custom search terms based on the properties of the workflow element. These search terms are saved asIElementSearchTermsProviding.getSearchTerms()
and may be used in a database query.The default implementation scans for entity references via
readEntityReferences(IReadEntityRefsParams)
and adds a search terms for each entity reference that was found with a default search term name obtained fromISearchTermHandler.entitySearchTerm(de.xima.fc.interfaces.workflow.reference.IEntityReference)
. When you override this method, you may also need to overridegetFilterCriteriaForEntities(IGetFilterCriteriaForEntitiesParams)
.- Parameters:
params
- Parameters with the data of the trigger for which to retrieve the search terms and some helper methods for querying the default search term names for entity references. When these names are used,getFilterCriteriaForEntities(IGetFilterCriteriaForEntitiesParams)
does not need to be overridden.- Returns:
- The search terms for the given trigger data. This map should not be modified by callers, unless the caller is a subclass implementation of this method.
-
getCascadingStyleSheet
@Deprecated default IResourceDescriptor getCascadingStyleSheet(boolean devMode) throws URISyntaxException, MalformedURLException
Deprecated.ImplementgetCascadingStyleSheet(Locale, boolean)
instead.Retrieves the CSS resources required by elements of this kind, when this node is displayed in the workflow designer. The CSS is added globally to the document - make sure to use unique class names. We recommend you keep to the conventions as laid out by BEM.- Parameters:
devMode
-true
if the application is started in development mode. May be used to deliver uncompressed files with a inline source maps for development.- Returns:
- The resource descriptor for the required CSS files. When no CSS resource is required, you may return
either
EmptyResourceDescriptor.INSTANCE
ornull
. - Throws:
URISyntaxException
- This exception is declared for convenience. Usually you want to create a new URI from a fixed path that is known to exist. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.MalformedURLException
- This exception is declared for convenience. You may want to create an URI from a fixed URL. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.
-
getCascadingStyleSheet
default IResourceDescriptor getCascadingStyleSheet(Locale locale, boolean devMode) throws URISyntaxException, MalformedURLException
Retrieves the CSS resources required by elements of this kind, when this node is displayed in the workflow designer. The CSS is added globally to the document - make sure to use unique class names. We recommend you keep to the conventions as laid out by BEM.- Parameters:
locale
- The current language of the workflow designer. You can use this parameter to include localized message in the script.devMode
-true
if the application is started in development mode. May be used to deliver uncompressed files with a inline source maps for development.- Returns:
- The resource descriptor for the required CSS files. When no CSS resource is required, you may return
either
EmptyResourceDescriptor.INSTANCE
ornull
. - Throws:
URISyntaxException
- This exception is declared for convenience. Usually you want to create a new URI from a fixed path that is known to exist. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.MalformedURLException
- This exception is declared for convenience. You may want to create an URI from a fixed URL. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.
-
getDataModelClass
Class<? extends TData> getDataModelClass()
Returns the class of the custom properties used by the elements handled by this element logic handler.The custom properties of a workflow element are internally stored as JSON. To ease the development work, you can specify a model class, and the JSON is automatically converted to an instance of that model class. Please note that the model class must be compatible with serialization mechanism used by
JSON
.See
getVersion()
for how custom properties are updated.If you need more control over serialization and deserialization, specify
JSONObject
as the type parameter and returnJSONObject.class
. You will then receive the raw JSON data and may perform the serialization in whatever way you like.- Returns:
- The class corresponding to the type parameter
TData
.
-
getDisplayLabel
default String getDisplayLabel(IGetDisplayLabelParams<TData> params)
Retrieves the display label for a workflow element. Compared withextractName(Object)
, this label may depend on the locale and is not saved in the database. Furthermore, the display label may depend on the context, such as the name of a workflow state etc. While not every element may have a name, every element should have a display label.The default implementation delegates to
extractName(Object)
.- Parameters:
params
- Parameters with the element's deserialized properties model, the locale and additional context data.- Returns:
- The display label of the element in the given locale.
-
getElementSummaryModel
default Serializable getElementSummaryModel(IGetElementSummaryParams<TData> params) throws Exception
When the user clicks on the info icon of a node or trigger, an panel with a quick summary of that node or trigger opens. By default, this panel only shows the available values returned by the node and which errors it can throw. You can implementgetElementSummaryXhtml()
to include a custom summary of the element's current properties. If you do, you should also override this method. It must create the view model for the XHTML page. The value returned by this method is passed to the XHTML page via the expression language variablemodel
.If you wish to display a quick summary as a list of key value pairs derived directly from the properties model, consider using the mixin
IKeyValueSummarizableElement
.- Parameters:
params
- The current properties model of the node or trigger.- Returns:
- The view model for the summary. When
null
, no summary is displayed. - Throws:
Exception
- When anything goes wrong. This is caught and logged, and no summary gets displayed.
-
getElementSummaryXhtml
default URL getElementSummaryXhtml() throws MalformedURLException
When the user clicks on the info icon of a node or trigger, an panel with a quick summary of that node or trigger opens. By default, this panel only shows the available values returned by the node and which errors it can throw. You can implement this method to include a custom summary of the element's current properties. If you do, you should also overridegetElementSummaryModel(IGetElementSummaryParams)
.This method should return the path to the XHTML page for the custom workflow element summary that is shown in an overlay when the user click on the info icon on a node or trigger. Usually the XHTML file is part of the JAR resources of the module or plugin. In this case, you should return an URL to a JAR file resource (
jar:file:/...
) like so:@Override public URL getXhtmlView() { return getClass().getResource("/path/to/view.xhtml"); }
The XHTML page should be a passive view without any interaction. The following to variables are made available to the XHTML page:
model
- The value that was returned bygetElementSummaryModel(IGetElementSummaryParams)
msg
: The localized messages as returned bygetResourceBundle(Locale)
. Empty when that method returnsnull
. For example, if the resource bundle contains the keymail.label
, you can access the localized message via the EL expression['mail.label']
- Returns:
- The XHTML page for the custom element summary. When
null
, no summary is displayed. - Throws:
MalformedURLException
- When the URL could not be created. When this exception is thrown, it is treated as ifnull
had been returned.
-
getFastJsonConverter
default IFastJsonConverter getFastJsonConverter()
Finds the converter that is used to convert between the properties model (getDataModelClass()
) and its JSON representation. The default implementation uses a JSON converter without any special custom serializers or configuration and should be sufficient for most cases. Please note you can influence how objects are serialized and deserialized via annotations, such asJSONField
, which should be sufficient in most cases.The default implementation returns a JSON converter that can convert most basic Java types; and makes use of the class loader of that loaded the class of this handler implementation.
The converter returned by this method must not be thread-safe, the system must guarantee it is not shared between threads.
- Returns:
- The JSON converter to use for converting between the properties model and its JSON representation.
-
getFilterCriteriaForEntities
default de.xima.cmn.criteria.FilterCriterion getFilterCriteriaForEntities(IGetFilterCriteriaForEntitiesParams params)
Similar toreadEntityReferences(IReadEntityRefsParams)
, but on a database level. Called when the system needs to search for referencing entities, but without reading all elements from the database first.A filter for the standard entity reference search terms is added automatically. When
extractSearchTerms(IExtractSearchTermsParams)
is not overridden or returns the standardISearchTermHandler.entitySearchTerms(IEntityReference)
, then you do not have to implement this method. This method is provided for non-standard cases when you need to add a custom filter.When this method returns
null
, no special separate filter for elements of this type is added. When this returns a non-null value, a separate filter for elements of this type that also match the returned filter is added to the database query. The filter criterion returned by this method is used for a query forAWorkflowElement
entities, i.e. all attribute names in filter criteria must be relative to that entity.To illustrate what the default filter that is added automatically looks like, assume an
inbox
is given. Then, to limit the result to elements which have a search term with the default entity reference key set to the UUID of the inbox, use:if (params.getEntity() instanceof Postfach.class) { return params.searchTermExists(params.entitySearchTerm(Postfach.class), params.entitySearchTerm(params.getEntity())); } return null;
To add a custom filter that matches elements which have a keycustomKey
set to a custom value, use:return params.searchTermExists("customKey", "customValue");
To create a complex filter, useor
/and
etc.Basic restrictions such as the
element type
, the form record and project are applied automatically by the system and do not need to be included in the returned filter.- Parameters:
params
- Params with the entity for which to scan for references.- Returns:
- A filter criterion to restrict the list of matching element for this handler type. When
null
is returned, no special filters for this element type are added. - Throws:
RuntimeException
- Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and treated as ifnull
had been returned.
-
getHelpPageLocation
default IElementHelpLocation getHelpPageLocation(Locale locale) throws IOException
- Parameters:
locale
- Locale for which the help page was requested.- Returns:
- The location of the help page for this element. This is used to show a help link to the user with more details on how they can use the workflow element.
- Throws:
IOException
- Provided for convenience when you wish to create newURLs
or read files from the classpath. When this method throws an exception, it is treated as if this method had returnednull
, e.g. no help page will be shown.
-
getJavaScript
@Deprecated default IResourceDescriptor getJavaScript(boolean devMode) throws URISyntaxException, MalformedURLException
Deprecated.ImplementgetJavaScript(Locale, boolean)
instead.Retrieves the JavaScript resources required by elements of this kind.The JavaScript code is loaded automatically by the flowchart and executed in a local function scope. The variable
Flowchart
is made available in that scope and contains the public client-side API of the flowchart. The JavaScript must (synchronously!) register the appropriate element handler either via a call toFlowchart.registerNode(nodeType: string, nodeHandler: Object): void; Flowchart.registerTrigger(triggerType: string, triggerHandler: Object): void;
See the TypeScript declaration file shipped in the NPM modulefc-workflow-flowchart
for an exact description of the node and trigger handler object. It also contains all available methods exposed on theFlowchart
object. We recommend you build your plugin against the declaration file to prevent errors when updating the formcycle version (removed or deprecated methods etc.)- Parameters:
devMode
-true
if the application is started in development mode. May be used to deliver uncompressed files with a inline source maps for development.- Returns:
- The resource descriptor for the required JavaScript files. When no CSS resource is required, you may
return either
EmptyResourceDescriptor.INSTANCE
ornull
. - Throws:
URISyntaxException
- This exception is declared for convenience. Usually you want to create a new URI from a fixed path that is known to exist. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.MalformedURLException
- This exception is declared for convenience. You may want to create an URI from a fixed URL. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.
-
getJavaScript
default IResourceDescriptor getJavaScript(Locale locale, boolean devMode) throws URISyntaxException, MalformedURLException
Retrieves the JavaScript resources required by elements of this kind.The JavaScript code is loaded automatically by the flowchart and executed in a local function scope. The variable
Flowchart
is made available in that scope and contains the public client-side API of the flowchart. The JavaScript must (synchronously!) register the appropriate element handler either via a call toFlowchart.registerNode(nodeType: string, nodeHandler: Object): void; Flowchart.registerTrigger(triggerType: string, triggerHandler: Object): void;
See the TypeScript declaration file shipped in the NPM modulefc-workflow-flowchart
for an exact description of the node and trigger handler object. It also contains all available methods exposed on theFlowchart
object. We recommend you build your plugin against the declaration file to prevent errors when updating the formcycle version (removed or deprecated methods etc.)- Parameters:
locale
- The current language of the workflow designer. You can use this parameter to include localized message in the script.devMode
-true
if the application is started in development mode. May be used to deliver uncompressed files with a inline source maps for development.- Returns:
- The resource descriptor for the required JavaScript files. When no CSS resource is required, you may
return either
EmptyResourceDescriptor.INSTANCE
ornull
. - Throws:
URISyntaxException
- This exception is declared for convenience. Usually you want to create a new URI from a fixed path that is known to exist. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.MalformedURLException
- This exception is declared for convenience. You may want to create an URI from a fixed URL. In case this exception is thrown, the resource will not be loaded and an appropriate error is shown to the user.
-
getLocalizedTypeName
String getLocalizedTypeName(Locale locale)
- Parameters:
locale
- Locale for which the type name should be returned.- Returns:
- A human-readable name of this element type in the given locale.
-
getPropertiesBeanClass
default Class<? extends IElementPropertiesBean<TData,TElement>> getPropertiesBeanClass()
Returns the class of the bean that should be used when editing the properties of a workflow element. May benull
if you do not require any bean or custom logic. When you only wish to access the properties of yourgetDataModelClass()
, you do have to use a custom bean - the model is available via the expression language variablemodel
. SeegetPropertiesViewXhtml()
for further details.The default returns
null
, which uses no extra bean. An extra bean may not be required for simple UIs if you only need to access the properties model of the workflow element - seegetPropertiesViewXhtml()
.- Returns:
- The class of the bean to use for editing a workflow node's properties.
- See Also:
getPropertiesViewXhtml()
-
getPropertiesViewXhtml
URL getPropertiesViewXhtml() throws MalformedURLException
This method must return the path to the XHTML page for the custom user interface. Usually the XHTML file is part of the JAR resources of the module or plugin. In this case, you should return an URL to a JAR file resource (jar:file:/...
) like so:@Override public URL getXhtmlView() { return getClass().getResource("/path/to/view.xhtml"); }
The contents of this XHTML page is included in the properties panel, without a fieldset or container around it, but already inside a form (i.e. do not use a
h:form
as that would result in an error). You should wrap your custom UI in a naming container to ensure unique IDs that do not clash with other plugins or actions. The following is a recommended template on which you may base your UI:<ui:composition xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://xmlns.jcp.org/jsf/html" xmlns:f="http://xmlns.jcp.org/jsf/core" xmlns:ui="http://xmlns.jcp.org/jsf/facelets" xmlns:o="http://omnifaces.org/ui" xmlns:p="http://primefaces.org/ui" xmlns:xi="http://www.xima.de/taglib/xfc"> <!-- Enable bean validation (when #validateLocal is implemented via the bean validator)--> <o:validateBean value="#{model}" showMessageFor="@violating" method="validateActual" /> <xi:namingContainer id="myAwesomeWorkflowElement"> <!--Base info with name and description (when TData extends BaseActionProps) --> <xi:newWorkflowActionBase id="base" value="#{model}" legend="#{msg['wf.node.myawesomelememnt']}" /> <!-- Remove when TData does not have a
ISingleFileProviding
field --> <xi:singleFile id="resource" value="#{model.singleFile}" required="true" /> <!-- Remove when TData does not have aIMultiFileProviding
field --> <xi:multiFile id="resource" value="#{model.multiFile}" required="true" /> <!-- Remove when TData does not implement IProviding --> <xi:fileProvision id="providing" value="#{model.fileProvision}" /> <!-- Custom section with editors specific to your workflow element --> <p:fieldset legend="#{msg['MyAwesomeWorkflowElementProps.fieldset.base']}" styleClass="fc-fieldset"> <!-- A simple input field bound to the mail property of your properties model --> <xi:inputText id="mail" label="#{msg['MyAwesomeWorkflowElementProps.mail']}" formPlaceholder="true" value="#{model.mail}" forceIndicateRequired="true" > <p:ajax event="change" partialSubmit="true" listener="#{elementPropertiesBean.storeCurrent}" process="@this" update=":flowchartForm:flowchart" global="false" /> </xi:inputText> </p:fieldset> </xi:namingContainer> </ui:composition>The XHTML page may access the following expression language variables:
- model: The deserialized custom properties of the workflow element, of the type
TData
. - provider: An object that implements
IWorkflowProvider
, for accessing various data, such as a list of all users or text templates. - msg: The localized messages as returned by
getResourceBundle(Locale)
. Empty when that method returnsnull
. For example, if the resource bundle contains the keymail.label
, you can access the localized message via the EL expression['mail.label']
To access the values of an enum or the constants defined by a class, consider using
<xi:importConstants type="my.fully.classified.path.MyEnum" var="MyEnum" loader="#{model}"/>
Theloader
argument is only required for plugins and ensures that the correct class loader is used that knows about the plugin class. Without the loader attribute, the above is equivalent to the PrimeFaces tag handler<p:importConstants />
.- Returns:
- Path to the XHTML view. If the action can be configured, this must not return
null
. If you do returnnull
, it will be treated as an error and an appropriate message is displayed to the user informing them that the properties panel could not be loaded. If the action cannot be configured (i.e. when the action is not selectable), this should returnnull
. - Throws:
MalformedURLException
- This exception is declared for convenience - normally you would usenew URL(String)
with a constant URL string that should not throw. In case an exception is thrown, it is treated the same as if this returnednull
.
- model: The deserialized custom properties of the workflow element, of the type
-
getResourceBundle
default ResourceBundle getResourceBundle(Locale locale)
Retrieves the resource bundle that should be used, for example, for custom validation messages generated during validation. If you useIWorkflowBeanValidator
for validation, the bean validator will use this bundle by default.When this resource bundle has no messages for a certain key, or when this returns
null
, the default resource bundles of formcycle are used as a fallback. This also means you do not have to include validation messages for common validation constraints such asNotEmpty
(but you can if you wish to override the defaults).- Specified by:
getResourceBundle
in interfaceIResourceBundleLocator
- Parameters:
locale
- A locale, for which a resource bundle shall be retrieved. Must not benull
.- Returns:
- The resource bundle to use for localized messages.
-
getVersion
default String getVersion()
Finds the current version of this element handler. The properties of the workflow element are stored as JSON, and this version is stored along with it. Later (such as after the software was updated), this JSON needs to be retrieved again, the version is compared against the current version. When the versions are not equal,ICustomParametersUpdateable.updateCustomParams(IUpdateCustomParametersParams)
is called on the raw JSON data, giving you a chance to update the properties before they are deserialized.By default, this returns the current version of formcycle. For plugins, it is strongly recommended that you use the version of the plugin.
- Returns:
- The current version of this workflow element handler.
- See Also:
ICustomParametersUpdateable
-
isAvailable
default boolean isAvailable(IIsAvailableParams<TData> params)
Checks whether this workflow element is available to the given client. If this returnfalse
, this action cannot be used in the workflow designer. When attempting to execute a workflow with an unavailable action, an error of typeNODE_UNAVAILABLE
is thrown. The default implementation always returnstrue
.- Parameters:
params
- The node's data, the entity context, and the current client.- Returns:
- Whether the workflow element is available to the given client.
-
isHasUserVisibleName
default boolean isHasUserVisibleName()
Checks whether this workflow element has a user-facingextractName(Object)
. If so, the name should usually be editable on the UI. If not, the name is a technical name that should not be shown to the user.- Returns:
true
if theextractName(Object)
can be visible to the user.
-
readEntityReferences
default Iterable<IEntityReferenceDescriptor> readEntityReferences(IReadEntityRefsParams<TData> params)
Extracts all entity references from the given properties model. These entity references are used are required, for example, when exporting a form or importing a form into the system. Entities in the export file need to be checked against existing entities, and possibly need to be updated.The default implementation scans for all entity references via reflection. This assumes that (a) you are not using
JSONObject
as thedata model class
; and (b) that you always useUuidEntityRef
in your properties model. Nested properties and entity references withinList
s andMap
s are supported.When you override this method, you should also implement the corresponding
updateEntityReferences
method.- Parameters:
params
- Query to get the entity references for- Returns:
- All
IEntityReferenceDescriptor
contained in the given model.null
is treated as if no descriptors had been returned.
-
readPlaceholders
default Iterable<IPlaceholderProperty<?,?>> readPlaceholders(IReadPlaceholdersParams<TData> params)
Finds and returns all placeholders that are contained in the given properties model. The descriptors returned by this method may (but are not always) later be passed towritePlaceholders(IWritePlaceholdersParams)
.The default implementation scans via reflection for the standard formcycle placeholder pattern in all fields of type string. When the properties model is a
JSONObject
, all strings inside that JSON object are scanned.- Parameters:
params
- Parameters with an element's properties model from which to read the placeholders.- Returns:
- All placeholders that are contained in the properties model. No guarantees are required regarding the
order in which the placeholders are returned.
null
is treated as if no placeholders had been returned. - See Also:
writePlaceholders(IWritePlaceholdersParams)
-
validateGlobal
default void validateGlobal(IElementGlobalValidationParams<TData,TElement> params) throws WorkflowValidationException
Similar tovalidateLocal
, but performs validations that require knowledge about other workflow elements. As such, this method is given access to the entireWorkflowProcess
and the list of all workflow elements of the process. This method is then responsible for iterating over all applicable workflow elements, using methods such asgetTriggersByType
orgetNodesByType
, and adding the appropriate validation failures viaaddGlobalValidationMessage
andmarkGlobalValidationFailed
.- Parameters:
params
- The workflow task and all workflow elements to validate.- Throws:
WorkflowValidationException
- When the validation could not be performed. Please note that this is meant for unexpected errors only - you should not throw an exception if a workflow element is simply just invalid.
-
validateLocal
IWorkflowElementValidationResult validateLocal(IElementLocalValidationParams<TData,TElement> params) throws WorkflowValidationException
Performs a local validation of the given workflow workflow element properties. This method should only validate the properties of the given workflow element, without respect to any other workflow elements.This method allows you to implement custom validation logic. Consider using
IBeanValidatingElement
and annotating your properties model class with the annotation from the bean annotation APIjavax.validation
. This also offers the advantage that it can be integrated into JSF, allowing you to use the same validations for the UI view as well.- Parameters:
params
- The properties to validate. Also provides access to the project, client etc.- Returns:
- The result of the validation, i.e. whether the workflow element is valid, and a list of messages to
display to the user. If this returns, this is treated as if a valid result without messages had been
returned. You may use use params.
getValidationContext()
.resultBuilder()
to create the result, or implement the interface yourself. To indicate that the validation was performed, but no validation constraints were violated, simply callbuild
on the result builder and return that, without adding any messages. - Throws:
WorkflowValidationException
- When the validation could not be performed. Please note that this is meant for unexpected errors only - you should not throw an exception if a workflow element is simply just invalid.
-
writeEntityReferences
default int writeEntityReferences(IWriteEntityRefsParams<TData> params)
Writes all given entity references back to the given properties model. This method is the complement toreadEntityReferences(IReadEntityRefsParams)
. The references passed to this method use the same key as returned byreadEntityReferences(IReadEntityRefsParams)
.The default implementation writes the entity references via reflection. This assumes that (a) you are not using
JSONObject
as thedata model class
; and (b) that you always useUuidEntityRef
in your properties model. Nested properties and entity references withinList
s andMap
s are supported.When you override this method, you should also implement the corresponding
readEntityReferences
.- Parameters:
params
- The current properties model and the updated references that should be set on the properties model.- Returns:
- The number of references were set.
-
writePlaceholders
default void writePlaceholders(IWritePlaceholdersParams<TData> params)
Writes all placeholders to the given properties model. The data that is passed to this method is the data that was previously returned byreadPlaceholders(IReadPlaceholdersParams)
. Implementors may assume that the properties model was not changed between the call toreadPlaceholders(IReadPlaceholdersParams)
and this method call.The default implementation scans via reflection for the standard formcycle placeholder pattern in all fields of type string. When the properties model is a
JSONObject
, all strings inside that JSON object are scanned.- Parameters:
params
- Parameters with the properties model and the placeholders that should be written to that properties model.
-
-