Creating custom widgets with Vaadin Visual Designer - bluesoft-rnd/aperte-workflow-core GitHub Wiki

Aperte Workflow provides wide range of customizable widgets, and it is advised to build user interfaces using that set. However, sometimes it is not possible to customize any widget to suit your needs. In that case you need to create a widget with custom behaviour.

This tutorial describe creation of such a widget, which displays data of currently signed in Liferay's user. In this example we will use Eclipse with Vaadin Visual Designer.

Table of contents

1. Prerequisties
2. Create project in Eclipse
3. Create layout in Visual Designer
4. Add widget's logic
5. Build with maven and deploy
6. Create test process in Aperte Modeler to test widget

#Prerequisties

This tutorial assumes that you have successfuly installed:

• Aperte Workflow with Aperte Modeler
• Eclipse with Vaadin plugin

#Create project in Eclipse

1. From the menu bar, select File -> New -> Other....
2. In the opened window select Maven -> Maven Project.
3. Select desired project name and location
4. Select archetype org.aperteworkflow:custom-widget-archetype:1.0.1 If the archetype's artifact is not on the list, you can add it manually:
5. Configure archetype parameters. Additional parameter widgetName is widget's name that will be displayed in modeler.
   
6. Generated project should look like this:

#Create layout in Visual Designer

1. In the Package Explorer right-click on SampleWidgetComponent and select Open with -> Vaadin editor

2. Create layout as on the picture:

   

Tip: if a desired component is not available from Components palette, i.e. FormLayout, you can set it's type directly in the code

In order to provide access to SampleWidgetComponent class fields, you have to whether generate getters for them or make them protected. In the second option, please not that after any change, Visual Designer will make them private back.

#Add widget's logic

1. Open SampleWidget class in standard Java Editor
2. Implement setContext and render methods as on code listing below:

package org.aperteworkflow.custom.mywidget;

[imports...]

@AliasName(name = "Sample Widget")
@ChildrenAllowed(value = false)
public class SampleWidget extends BaseProcessToolVaadinWidget {

	private static final SimpleDateFormat DF = new SimpleDateFormat("dd-MM-yyyy hh:mm");
	private User liferayUser;

	@Override
	public void setContext(ProcessStateConfiguration state,
			ProcessStateWidget configuration, I18NSource i18nSource,
			ProcessToolBpmSession bpmSession, Application application,
			Set<String> permissions, boolean isOwner) {

//		get user from context
		UserData user = bpmSession.getUser(ProcessToolContext.Util.getThreadProcessToolContext());
		try {			
//		load associated liferay user 
			liferayUser = UserServiceUtil.getUserByEmailAddress(
					user.getCompanyId(), user.getEmail());
		} catch (SystemException e) {
			e.printStackTrace();
		} catch (PortalException e) {
			e.printStackTrace();
		}
		super.setContext(state, configuration, i18nSource, bpmSession,
				application, permissions, isOwner);
	}

	@Override
	public Component render() {
		return new SampleWidgetComponent() {			
			
			@Override
			protected void loadData() {
//				fill labels with user data
				label_1.setValue(liferayUser.getFullName());
				label_2.setValue(liferayUser.getEmailAddress());
				label_3.setValue(liferayUser.getScreenName());
				label_4.setValue(liferayUser.getGreeting());
				label_5.setValue(DF.format(liferayUser.getLastLoginDate()));
//				fill table with user roles
				try {
					Container container = new BeanItemContainer<Role>(Role.class, liferayUser.getRoles());
					table_1.setContainerDataSource(container);
					Object[] visibleColumns = {"descriptiveName"};
					table_1.setVisibleColumns(visibleColumns );
					String[] columnHeaders = {"Role name"};
					table_1.setColumnHeaders(columnHeaders );
				} catch (IllegalArgumentException e) {
					e.printStackTrace();
				} catch (SystemException e) {
					e.printStackTrace();
				}
			}
		};
	}

	@Override
	public void addChild(ProcessToolWidget child) {
		throw new UnsupportedOperationException();
	}
}

#Build with maven and deploy

1. Open console and change directory to the project's root

2. Type:

   mvn clean package
   

3. Copy bundle jar file into running Aperte Workflow instance's osgi-plugins directory

#Create test process in Aperte Modeler to test widget

1. Enter Aperte Modeler
2. Create new design as on the picture:
3. Edit step: drag and drop Sample Widget from available widgets list
4. Set it's permissions:
5. Deploy process
6. Sign in to liferay and test - you should see something like this:

Code for this sample is available in samples/custom-widget-sample (since version 1.1).