aBPM – Create Custom UI-Element

Here is a guide to create a custom ui-element. If aBPM doesn’t provide a specific ui5 element or a specific functionality for the provided ui-element in the excel sheet, you could easily implement a custom UI5 element within the aBPM Framework.

aBPM provides a functionality using the ui-element “CID” in combination with the datatype “String” to easily implement a custom ui-element. This blog will give you a step-by-step guide to implement a custom ui-element.

Prior Knowledge:

SAP UI5 Basics
Java
aBPM Basics (aBPM Cookbook V31)

Scenario:

We want to implement the sap.m.CheckBox with extended alert functionality in the aBPM Framework.

STEP 1: Check SAPUI5 Version of your solution

Open abpm cockpit (<host:port>/abpmui5/cockpit/index.html) and open the inspector (CTRL + SHIFT + I in Chrome) and type “sap.ui.version” in the console to check your latest sap-ui-version of your aBPM Solution (for example 1.52).

STEP 2: Check API Reference for Knowing how to implement your ui-element

Go to website https://sapui5.hana.ondemand.com in the API reference to search for the specific UI-Element you want to implement. In this case, it is sap.m.CheckBox. Then on the right side above the corner change the ui5 version accordingly to your aBPM sapui5 version. In this example, it is 1.52 (Fig. 1 & 2).

Fig. 1: Change Version of SAPUI5 API Site

Fig. 2: Select the right version

On the API reference you can also switch to Control Sample to see implementation examples of the CheckBox. You can also go directly to the library site of your current version with the URL https://sapui5.hana.ondemand.com/<your sapui-verision>/ . For example: https://sapui5.hana.ondemand.com/1.52.12/#/api.

Fig. 3: Control Sample

In the API of sap.m.CheckBox under Constructor it shows how to create a new sap.m.CheckBox (see Fig. 4) with “new sap.m.CheckBox(sId?, mSettings?)”.

Fig. 4: API Reference

In Addition, we want to extend the checkbox and create an alert, if the user clicks on the checkbox. In the Events section, we can find an event named “select”. There we can add our custom functionality with “.attachSelect()”.

Fig. 5: Event Section

STEP 3: Implement Custom CheckBox

After having all the information, how to create a new CheckBox, go to the NWDS on your Java EE perspective and add the following method in your <projectname>ExtBase:

	public Object queryInterface(AbstractWrappedCallbackContext<Test0002> ctx, InterfaceType type) {

        if (InterfaceType.ICustomRendererFactory.equals(type)) {
			return new CustomRendererFactory();
		} 

		// TODO Auto-generated method stub
		return super.queryInterface(ctx, type);
	}

This will return the CustomRenderFactory class if it is needed.

Then create a new package in your ejb project with “<namespace>.custom” and create two classes. One class with the name CustomRenderFactory.java and the other one called CustomCheckBoxRenderer.java (see Fig. 6).

Fig. 6: Additional Package with two new classes

In the CustomRendererFactory add following code:

public class CustomRendererFactory extends AbstractCustomRendererFactory{

	private final static String CUST_CHECKBOX = "CUST_CHECKBOX";
	
	public CustomRendererFactory() {
		super();
	}

	@Override
	protected void addDesktopCustomRenderer(Map<String, IRenderer> mapping) {
		mapping.put(CUST_CHECKBOX, new CustomCheckBoxRenderer());
	}

	@Override
	protected void addPhoneCustomRenderer(Map<String, IRenderer> mapping) {
		mapping.put(CUST_CHECKBOX, new CustomCheckBoxRenderer());
	}

	@Override
	protected void addTabletCustomRenderer(Map<String, IRenderer> mapping) {
		mapping.put(CUST_CHECKBOX, new CustomCheckBoxRenderer());
	}
}

The CustomRendererFactory inherits from AbstractCustomRendererFactory. There you are able to create 3 different Renderer for Desktop, Phone and Tablet Version. In this example, we are using for all 3 views one renderer.

After that add following code in your CustomCheckBoxRenderer class:

public class CustomCheckBoxRenderer extends UI5AbstractValueElementRenderer {

	private static final Location LOG = Location.getLocation(CustomCheckBoxRenderer.class);

	final static String VALUE_STATE_FRAME_CONTAINER = "ValueStateFrame";

	@Override
	public void render(RenderContext ctx, PrintWriter writer, UI5ValueElementParameters params) {
		
		AttributeMetaData amd = params.getAmd();
		//get params from Excel
		UIElementParam param = this.getParams(ctx, amd, UIElementParam.class);
		//get Field Name from Excel
		String fieldName = UI5RenderUtils.generateValueItemName(params, amd);
		//get standard LayoutData
		String layoutDataForCheckBox = this.getLayoutData(ctx, amd, param);

		//render Label from Excel
		this.renderLabel(ctx, writer, fieldName, params);
		
		//add custom ui-element
		writer.append("var ").append(fieldName).append("= new sap.m.CheckBox('").append(fieldName).append("',{").append("width:'100%',").append(
		layoutDataForCheckBox).append("});");
		
		//add extended Functionality to fieldName
		writer.append(fieldName).append(".attachSelect(function(){alert('Your Text...');}); ");

		//add addtional css
		this.renderAdditionalCssClasses(ctx, writer, amd, fieldName);

		//add the ui-element in the Renderer
		this.renderAdd2Container(ctx, writer, params, fieldName);

	}

}

Now we created the 2 classes. In The ExtBase Class, the queryInterface method will look into the CustomRendererFactory if the ui-element exist, which were defined in the excel and if its exists it will return the specific class to create the renderer.

In your excel sheet add a new line to create a new ui element, the custom checkbox. Following information has to be included:

TechnicalName: <yourChoice>

DataType: String

DataTypeExtension: CUST_CHECKBOX

UIElement: CID

The DataTypeExtension has to be the same name as the one we defined in the CustomRendererFactory.java Class.

Then export an XML-Version of the Excel in your package folder, where your Excel File is saved. After that run the AntScript, refresh your ejb-package and then deploy it to your PO system. Finally, you will see the new ui-element with the extended functionality in your abpm scenario: