Custom components

How to include custom component in the studio’s palette ?

Component’s declaration in the properties (Process15.3.0 and lower)

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

Positioning the configuration xml file

The custom component are declared in custom/forms/components

Composition of the xml file

Package

At this level we describe the component storage hierarchy.

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

Component

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.filecenter-element-selector" componentName="FileCenterElementSelectorInputComponent" childOf="sys.forms.*" unindexed="true">
			<def field="true">
			...
			</def>
		</element>
	</components>
</package>

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

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.moovapps.custom.navigation.components.extensions.editor.FileCenterElementSelectorEditorExtension"/>
				...
			</def>
		</element>
	</components>
</package>

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 FileCenterElementSelectorEditorExtension extends BaseFieldEditorExtension {

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

		return super.onAfterLoad();
	}
}

Widget

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

<package>
	<components>
		<element>
			<def>
				<extension/>
				<widget>com.moovapps.custom.navigation.components.FileCenterElementSelectorInputComponent</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 FileCenterElementSelectorInputComponent extends SelectorInputComponent {

	private String elementType;

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

		super.initAdditionalParameters();
	}

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

	/**
	 * set {@link FileCenterElementSelectorInputComponent#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 JBoss\server\all\deploy\vdoc.ear\vdoc.war .

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

Type

Under the def tag, we set with the tag type the datatype used by our component.

<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>

Configuration

Under the def tag, we declare with the tag * configuration * the elements to present for the configuration of our component. We find under the tag * configuration * 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>

Example

As an example here is the xml declaration of the client selection component for moovapps-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 “-”.