Custom components

Custom components can be created and added in the studio’s palette.

Component’s declaration in the properties

Warning

For the versions lowers than Process15.3.0, it’s necessary to add the following configuration key to the instance’s properties (via CustomResource.properties for example) : com.axemble.vdoc.customElement.formLibrary=custom.forms.filecenter-element-selector

XML’s declaration of the component

The custom component are declared in custom/forms/components.

At the root level we have the package tag that contains the components:

<package name="custom.forms" provider="visiativsoftware.com" version="1.0">
	...
</package>

Attribute	Mandatory
name	true
provider	true
version	true
path	false

Sub-tag	Description
label	The package’s label (a translation key)
description	The package’s description (a translation key)
depends	The dependencies
components	The components list, that only contains `element` tags
lists	The lists declared in the components

Depends

Element and definition

The components are the package’s element and declare inside the tag components in the form of a tag element:

<package>
	<components>
		<element name="custom.forms.input-myElement" componentName="MyElementInput" childOf="sys.forms.*" unindexed="true">
			<def field="true">
			...
			</def>
		</element>
	</components>
</package>

The attribute’s name is important to be able to indicate the activation of this component later. It must start with custom.forms to take advantage of the alternateView. The attribute childOf must be valuated at sys.forms.* .

Attribute	Mandatory
name	true
unindexed	false
componentName	false
generation	false
childOf	false

Sub-tag	Description
def	The definition of the element

The def tag is composed with:

Attribute	Mandatory
extends	false
hidden	false
abstract	false
field	false

Sub-tag	Description
label	The label of the component, only a tag containing a string. By default, the label is a translation key at the format: `ezs.component.ELEMENT_NAME.label`.
description	The description of the component, only a tag containing a string. By default, the label is a translation key at the format: `ezs.component.ELEMENT_DESCRIPTION.label`.
extension	The extension of the component.
widget	The widget of the component.
alternateView	The alternate view of the component.
type	The type of the component.
configuration	The configuration of the component.

Extension

Under the tag def, we set with the tag extension the class acting as editor for our component.

<package>
	<components>
		<element>
			<def>
				<extension type="editor" className="com.visiativ.custom.navigation.components.extensions.editor.MyElementEditorExtension"/>
				...
			</def>
		</element>
	</components>
</package>

Attribute	Mandatory
type	true
className	true

This class must inherit from BaseFieldEditorExtension.

For example:

package com.moovapps.custom.navigation.components.extensions.editor;

import com.axemble.easysite.components.forms.sys.forms.BaseFieldEditorExtension;
import com.axemble.vdoc.sdk.interfaces.IOptionList;
import com.axemble.vdp.ui.framework.document.AbstractField;
import com.axemble.vdp.ui.framework.widgets.list.Option;

import java.util.ArrayList;
import java.util.List;

public class MyElementEditorExtension extends BaseFieldEditorExtension {

	/**
	 * method run after data loading
	 * @return true on success or false
	 * SDKException can be thrown to alert the user
	 **/
	@Override
	public boolean onAfterLoad() {
		//Fill selectable element combo box
		List<IOptionList.IOption> elementTypes = new ArrayList<>();
		elementTypes.add(new Option("MyType1", getWorkflowModule().getStaticString("LG_TYPE_1")));
		elementTypes.add(new Option("MyType2", getWorkflowModule().getStaticString("LG_TYPE_2")));
		AbstractField elementTypeField = getDocument().getAbstractFieldByName("elementType");
		elementTypeField.setList(elementTypes);

		return super.onAfterLoad();
	}
}

Under the tag def, we set with the tag widget the uses as graphical interface for our component. This class must extend com.axemble.vdp.ui.framework.foundation.Widget.

<package>
	<components>
		<element>
			<def>
				<extension/>
				<widget>com.moovapps.custom.navigation.components.MyElementInputComponent</widget>
				...
			</def>
		</element>
	</components>
</package>

For example :

package com.moovapps.custom.navigation.components;

import com.axemble.vdp.ui.framework.widgets.components.sys.forms.SelectorInputComponent;

public class MyElementInputComponent extends SelectorInputComponent {

	private String elementType;

	@Override
	protected void initAdditionalParameters() {
		addParameter("screen", "myElementNode");
		addParameter("method", "select");
		addParameter("selectable", getElementType());

		super.initAdditionalParameters();
	}

	/**
	 * get {@link MyElementInputComponent#elementType} property
	 *
	 * @return get the elementType property
	 **/
	public String getElementType() {
		return elementType;
	}

	/**
	 * set {@link MyElementInputComponent#elementType} property
	 *
	 * @param elementType set the elementType property
	 **/
	public void setElementType(String elementType) {
		this.elementType = elementType;
	}
}

Alternate view

Under the tag def, we set with the tag alternateView the image for the representation of our component in a form. The search for the image starts under the directory wildfly\standalone\deployments\vdoc.ear\vdoc.war.

<package>
	<components>
		<element>
			<def>
				<extension/>
				<widget/>
				<alternateView>studio/skin/images/form/custom/custom-forms-my-element.png</alternateView>
				...
			</def>
		</element>
	</components>
</package>

Type

Under the def tag, we set with the tag type the datatype used by our component (used by the formula field to know what element is manipulated).

<package>
	<components>
		<element>
			<def>
				<extension/>
				<widget/>
				<alternateView/>
				<type isMultiple="false" label="LG_PROPERTY_TYPE_com.axemble.vdoc.sdk.supports.IProtocolSupport" javaClass="com.axemble.vdoc.sdk.supports.IProtocolSupport"/>
				...
			</def>
		</element>
	</components>
</package>

Attribute	Mandatory
label	true
javaClass	true
isMultiple	false

Configuration

Under the def tag, we declare with the tag configuration the elements to present for the configuration of our component. We find under this tag a breakdown with the tag section, which can be repeated. Under each section, the fields used for the configuration of the component are positioned via fields tags.

<package>
	<components>
		<element>
			<def>
				<extension/>
				<widget/>
				<alternateView/>
				<type/>
				<configuration>
						<section name="properties" label="LG_PROPERTIES">
							<fields>
								<field name="propertytype" label="ezs.component.sys.forms.input.propertytype.label" description="ezs.component.sys.forms.input.propertytype.description" ctrl="textselectlist" throw-events="true" allowreset="false" string-value="assignmentfield"/>
								<field name="property" label="ezs.component.sys.forms.input.property.label" description="ezs.component.sys.forms.input.property.description" ctrl="selector" screen="Property" method="select" mandatory="false" type="string" protocolUriType="single" quick-create="Field.quickCreate" quick-create-type="string"/>
								<field name="temporarypropertyname" label="ezs.component.sys.forms.input.temporarypropertyname.label" description="ezs.component.sys.forms.input.temporarypropertyname.description" ctrl="text"/>
								<field name="editable" reversedValue="true" label="ezs.component.sys.forms.input.read.label" description="ezs.component.sys.forms.input.read.description" ctrl="checkbox" throw-events="true"/>
								<field name="mandatory" label="ezs.component.sys.forms.input.required.label" description="ezs.component.sys.forms.input.required.description" ctrl="checkbox" preview="true" fd-context="write"/>
								<field name="elementType" label="ezs.component.sys.forms.input.elementType.label" description="ezs.component.sys.forms.input.elementType.description" ctrl="textselectlist" mandatory="true"/>
							</fields>
						</section>
						...
				</configuration>
			</def>
		</element>
	</components>
</package>

The section’s attributes are:

Attribute	Mandatory
name	true
label	false
description	false

The field’s attributes depend on their declaration.

The “quick-create” field is a special field that need particular attention.

Lists

Next to the components tag, a lists tag can be added to declare the lists used in the XML file:

<lists>
	<list name="sys.forms.input-myElement.myField">
		<item>
			<label>ezs.component.sys.forms.input-myElement.myField.value1</label>
			<value>value1</value>
		</item>
		<item>
			<label>ezs.component.sys.forms.input-myElement.myField.value2</label>
			<value>value2</value>
		</item>
		<item>
			<label>ezs.component.sys.forms.input-myElement.myField.value3</label>
			<value>value3</value>
		</item>
	</list>
</lists>

The name attribute of the list is mandatory.

To use the list in a field, the list’s name must be used in a listName attribute:

<field name="myField" label="myField.label" description="myField.description" ctrl="textselectlist" mandatory="true" listName="sys.forms.input-text.size" />

Info

The list may also be declared directly in the field (but it can not be used by another element):

<field name="myField" label="myField.label" ctrl="textselectlist" mandatory="true">
	<options>
		<option key="value1" labelid="ezs.component.sys.forms.input-myElement.myField.value1"/>
		<option key="value2" labelid="ezs.component.sys.forms.input-myElement.myField.value2"/>
		<option key="value3" labelid="ezs.component.sys.forms.input-myElement.myField.value3"/>
	</options>
</field>

Example

As an example here is the XML declaration of the client selection component for Workplace:

<?xml version="1.0" encoding="UTF-8"?>
<!--This document defines default configuration for *sys.forms* plugin.-->
<package name="custom.forms" provider="visiativsoftware.com" version="1.0">
	<components>
		<element name="custom.forms.filecenter-element-selector" componentName="FileCenterElementSelectorInputComponent" childOf="sys.forms.*" unindexed="true">
			<def field="true">
				<extension type="editor" className="com.moovapps.custom.navigation.components.extensions.editor.FileCenterElementSelectorEditorExtension"/>
				<widget>com.moovapps.custom.navigation.components.FileCenterElementSelectorInputComponent</widget>
				<alternateView>studio/skin/images/form/custom/custom-forms-filecenter-element-selector.png</alternateView>
				<type isMultiple="false" label="LG_PROPERTY_TYPE_com.axemble.vdoc.sdk.supports.IProtocolSupport" javaClass="com.axemble.vdoc.sdk.supports.IProtocolSupport"/>
				<configuration>
					<section name="properties" label="LG_PROPERTIES">
						<fields>
							<field name="propertytype" label="ezs.component.sys.forms.input.propertytype.label" description="ezs.component.sys.forms.input.propertytype.description" ctrl="textselectlist" throw-events="true" allowreset="false" string-value="assignmentfield"/>
							<field name="property" label="ezs.component.sys.forms.input.property.label" description="ezs.component.sys.forms.input.property.description" ctrl="selector" screen="Property" method="select" mandatory="false" type="string" protocolUriType="single" quick-create="Field.quickCreate" quick-create-type="string"/>
							<field name="temporarypropertyname" label="ezs.component.sys.forms.input.temporarypropertyname.label" description="ezs.component.sys.forms.input.temporarypropertyname.description" ctrl="text"/>
							<field name="editable" reversedValue="true" label="ezs.component.sys.forms.input.read.label" description="ezs.component.sys.forms.input.read.description" ctrl="checkbox" throw-events="true"/>
							<field name="mandatory" label="ezs.component.sys.forms.input.required.label" description="ezs.component.sys.forms.input.required.description" ctrl="checkbox" preview="true" fd-context="write"/>
							<field name="elementType" label="ezs.component.sys.forms.input.elementType.label" description="ezs.component.sys.forms.input.elementType.description" ctrl="textselectlist" mandatory="true"/>
						</fields>
					</section>
					<section name="display" label="LG_DISPLAY_SETTINGS">
						<fields>
							<field name="size" label="ezs.component.sys.forms.input.size.label" description="ezs.component.sys.forms.input.size.description" ctrl="textselectlist" mandatory="true" listName="sys.forms.input-selector.size" string-value="medium" allowreset="false" fd-context="write,hide-mobile"/>
							<field name="maxDisplayedItems" label="ezs.component.sys.forms.input-date.maxDisplayedItems.label" description="ezs.component.sys.forms.input-date.maxDisplayedItems.description" ctrl="textselectlist" listName="sys.forms.input-combo.list.maxDisplayedItems" string-value="10" allowreset="false" fd-context="write,hide-mobile"/>
							<field name="maxFilteredItems" label="ezs.component.sys.forms.selector.maxFilteredItems.label" description="ezs.component.sys.forms.selector.maxFilteredItems.description" ctrl="textselectlist" listName="sys.forms.selector.list.maxFilteredItems" string-value="10" allowreset="false" fd-context="write,hide-mobile"/>
							<field name="displaySelectionOutside" label="ezs.component.sys.forms.input.displaySelectionOutside.label" description="ezs.component.sys.forms.input.displaySelectionOutside.description" ctrl="checkbox" boolean-value="false" fd-context="write,hide-mobile"/>
						</fields>
					</section>
					<section name="accessibilities" label="LG_ACCESSIBILITY">
						<fields>
							<field name="tabindex" label="ezs.component.sys.forms.input.tabindex.label" description="ezs.component.sys.forms.input.tabindex.description" ctrl="integer" min="0" fd-context="write"/>
						</fields>
					</section>
					<section name="additionalParameters" label="ezs.component.sys.forms.input.additionalParameters.label" description="ezs.component.sys.forms.input.additionalParameters.description">
						<fields>
							<field name="throw-events" label="ezs.component.sys.forms.input.throwevents.label" description="ezs.component.sys.forms.input.throwevents.description" ctrl="checkbox" fd-context="write"/>
							<field name="additionalParameters" label="ezs.component.sys.forms.input.additionalParameters.attributes.label" description="ezs.component.sys.forms.input.additionalParameters.attributes.description" ctrl="textarea">
								<rules>
									<rule>additionalParameters</rule>
								</rules>
							</field>
							<field name="additionalParametersNodes" ctrl="com.axemble.vdoc.sdk.document.fields.LightBoxField" targetLabel="ezs.component.sys.forms.input.additionalParameters.nodes.label" targetInformation="ezs.component.sys.forms.input.additionalParameters.nodes.description" label="ezs.component.sys.forms.input.additionalParameters.nodes.label" description="ezs.component.sys.forms.input.additionalParameters.nodes.description">
								<targetField ctrl="com.axemble.vdp.ui.core.document.fields.ScriptEditorField" type="xml"/>
								<rules>
									<rule>xml</rule>
								</rules>
							</field>
						</fields>
					</section>
				</configuration>
			</def>
		</element>
	</components>
</package>

Add in the palette

Adding the component in the palette

To make the component declaration active, it is necessary to add the component to the palette.

To do this, add a file in the custom/global folder for example custom-global-definition.xml.

<?xml version="1.0" encoding="UTF-8"?>
<definitions>
	<palette-definition>
		<palette-family name="custom" label="LG_CUSTOM" order="10000">
			<components>
				<component name="custom.forms.filecenter-element-selector" hideInMailForm="true"/>
				...
			</components>
			<layouts>
			</layouts>
		</palette-family>
	</palette-definition>
</definitions>

It is possible to hide components according to the context with the attributes:

hideInTransitionInletForm : hide the fields in the step change form
hideInLinkedResourceForm : hides the field in the dynamic table form
hideInMailForm : hide the field in the mail forms
hideInStorageResourceForm : hides the component in the data store form
hideInTaskForm : hides the component in the context of the step, document, document sub form forms

Note

It should be noted that for the moment this XML file does not support the “extends” nor the “override”. You will not be able to import components in the same section from multiple XML files

Add the icon to use for the palette

You need to add a 20*20px image in the /webapp/studio/skin/images/palette/ folder, the name of the image must match the name of the element in our case custom-forms-filecenter-element-selector.

Warning

“.” in the element’s name are replaced with “-”.