Introduction
WebRatio Mobile Platform lets you extend the set of components that can be used inside projects to add new functionalities. In this lesson you learn how to create a new custom component for DataService Projects that allows to convert a string.
How to Define the "StringsFunction" Custom Operation
Let's suppose you want to create a DataService Component that lets you to do the uppercase and the lowercase of a string.
To create a new custom component for a DataService Project you need a Components Project. Click on "File" menu, choose the "New" and then "Components Project" option. Give a meaningful name for the Components Project, such as "CostumComponents" and press the "Finish" button to confirm the procedure.
Let's now create the StringsFunction component. Click on the "File" menu, choose the "New" and then "Component" option. In the dialog, select a target project in which the component resources will be stored, in this example the "CustomComponents" project, give a meaningful name for the Component, such as "StringsFunction" and then press the "Next" button. At last press the "Finish" button to complete.
Component.xml editor
General tab
In the "Component.xml" editor you can define the component structure.Let's choose the main properties for the "StringsFunction" component.Check the "Data Flow Source" property, the "Success Flow Source" property and the "Error Flow Source" property.Click on the "16x16" icon to choose the icon, select the "16" image then click the "Open" button to load the image. Use the same procedure to choose the second icon.
Sub-Elements tab
The "StringsFunction" component has a specific structure.In our example, the component gives the possibility to choose for the "Mode" property, two option: uppercase and lowercase.
Let's open the "Sub-Elements" section for this purpose. Right-click on the "Component" node, choose the "Add Enumeration Property" option and then type a name for the property, such as "mode".
Right-click on the "Mode" node to add the options, choose the "Add Enumeration Item" option and then type a name for the item, such as "uppercase".
Right-click again on the "Mode" node, choose the "Add Enumeration Item" option and type a name for the item, such as "lowercase".
The Logic.template file
The defined Sub-Elements must be retrieved at runtime by the component. For this reason we need to declare them in component descriptor, generated by the "Logic" template. Click on "Logic.template" tab to open it. Let's add the XML code to retrieve the value of Mode property:
[%=component["mode"]%]
The Input.template file
In order to receive the string to convert as input parameter of the component, let's open the "Input" template and define the "string" input parameter. Double-click on the "Input.template" node in the Outline View. Set the "name" property, such as "string" and set the "label" property, such as "String".
<InputParameter name="[%=componentId%].string" label="String" />
The Output.template file
In order to return the result of conversion as output parameter of the component , let's open the "Output" template and define the "result String" output parameter. Double-click on the "Output.template" node in the Outline View to open it. Set the "name" property, such as "resultString" and set the "label" property to "Result String".
<OutputParameter name="resultString" label="Result String" />
The StringFunctionComponentService.java file
Finally, let's specify the component runtime behavior in the dedicated file.
Click on the "Show List" tab and then click on the "StringFunctionComponentService.java" to open it. WebRatio Mobile Platform creates a skeleton for the component service with Java code.
- Declaration of the new service for the component
public class StringsFunctionComponentService extends AbstractService implements OperationService
The constructor that let's you retrieve information from the descriptor (descr) file.
public StringsFunctionComponentService(String id, RTXManager rtx, Element descr) throws RTXException {
super(id, rtx, descr);
// TODO Initialize service
}
- The "execute" method specifies the component behavior
public Object execute(NavigationContext context) throws RTXException {
DefaultOperationBean bean = new DefaultOperationBean();
// fill result bean;
return bean;
}
- The final service of the component
public class StringsFunctionComponentService extends AbstractService implements OperationService{
private static final String MODE_UPPER_CASE_STRING = "uppercase"
private static final String MODE_LOWER_CASE_STRING = "lowercase";
private final String mode;
public StringsFunctionComponentService(String id, RTXManager rtx, Element descr) throws RTXException {
super(id, rtx, descr);
this.mode = DescriptorHelper.getChildValue(descr, "Mode", true, this);
}
@Override
public Object execute(NavigationContext context) throws RTXException {
DefaultOperationBean bean = new DefaultOperationBean();
try {
if (MODE_UPPER_CASE_STRING.equals(mode)) {
bean.put("resultString", StringUtils.upperCase(context.getString(getId() + ".string", Scope.REQUEST)));
} else if (MODE_LOWER_CASE_STRING.equals(mode)) {
bean.put("resultString", StringUtils.lowerCase(context.getString(getId() + ".string", Scope.REQUEST)));
}
} catch (Exception e) {
logError("Unable to execute the function component service", e);
bean.setResultCode(RTXConstants.ERROR_CODE);
bean.put("errorMessage", e.getMessage());
bean.put("exception", e);
throw new RTXException(e);
}
return bean;
}
}
Finally, let's add the required libraries for the service. Select the "StringUtils" library and press the "Next" button. Then select the "Score" library and press the "Finish" button.
How to Model a Sample Project
Let's create a sample DataService Project to test the "StringsFunction" component.
Click on "File" menu, choose the "New" then "DataService Project" option. Give a meaningful name for the DataService Project, such as "StringsFunctionSample". Press the "Finish" button.
Now let's add the Components Project as a dependency in order to see the "StringsFunction" component in the toolbar. Press on the "Add.." button. Choose the Component Project, in this example the "CustomComponents" project and press the "OK" button. Then press the "Yes" button.
Let’s suppose you want to expose two Web Service methods that contain an operation chain for converting a string to uppercase or lowercase. The methods receive the string and gives back the string in uppercase or the string in lowercase.
Let's now add a Service View to start model the web services. Press the "Add Service View..." button, type a name for the "Service View", such as "Functions" and press the "Finish" button to confirm.
First of all, let's add a "Service Port" service container where you model the web service. Click on the "Service Containers" section of the toolbar, choose the "Service Port" item and click inside the work area to add it. Type a meaningful name for the "Service Port", such as "StringsFunctions".
To model the REST Web Service, let's configure the entry point, which is the "Solicit" operation. Double-click on the solicit component to change the name. Give a name for the solicit component, such as "uppercase". In its Properties View, set the "REST" value to the "Invocation Style" property and then set the "GET" value as Request Method.
Let's suppose that the Web Service receives the string to convert to uppercase. Let's add a "Query String Parameter" by right-clicking on the "uppercase" solicit component, choose the "Add" and then on the "Query String Parameter" option. Type a name for it, such as "string". Press the "Edit" button next to the "XSD Type" property to choose the type, choose the "String" type and press the "OK" button.
To convert the string to uppercase, let's use the "StringsFunction" component. Choose the "StringsFunction" in the toolbar and click inside the Service Port to add it. In the Properties View, set the "Mode" property to "Uppercase" value.
To provide the input string to the "StringsFunction" component, let’s use a "Success Flow". Click in the "Flows" section of the toolbar and choose the "Success Flow" item. Click first on the "Solicit" component and then on the "StringsFunction" component.
Double-click on the "Success Flow" to see the "Parameters Binding" dialog and provide the string. Press the "Guess Binding" button and then press the "OK" button.
Finally, let's add the Web Service Response. Click on the "Service Components" section of the toolbar, choose the "Response" component and click inside the Service Port to add it. Give a meaningful name for the "Response Component", such as "UpperCaseResponse". In its Properties View, set the "JSON" value as Content Type.
Let's add to the Response Component the result string. Right-click on it, choose the "Add" and then on the "Body Parameter" option. Type a name to the Body Parameter, such as "resultString". In its Properties View, press the "Edit" button next to the "XSD Type/Element" property to define the type. Choose the "string" type and then press the "OK" button.
Finally, to retrieve the result string to the "Response" component, let’s use a "Success Flow". Click on the "Flows" section of the toolbar and choose the "Success Flow" item. Click first on the "StringsFunction" component and then on the "Response" component.
Double-click on the "Success Flow" to see the "Parameters Binding" dialog and provide the result string. Press the "Guess Binding" button and press on the "OK" button.
Now, let's model the web service for the lowercase function. The logic is the same of the uppercase method, for this reason copy the web service and change the behavior to the lowercase method.
Click on the "uppercase" solicit component, use the CTRL (on PC) or CMD (on Mac) button to select the elements, click on the "StringsFunction" component, finally, click on the "Response" component. Copy and paste in the Service Port.
Let's change the name to the components and the method of the "StringsFunction". Double-click on the solicit component. Change the name of the component with "lowercase".
Double-click on the "StringsFunction" component. Change the name of the component with "StringsFunction LowerCase". In the Properties View, set the "Mode" property to "Lowercase" option.
Finally, double-click on the Response Component. Change the name of the component with "LowerCaseResponse".
How to Emulate the Custom Component Behavior
Generate and Run on Cloud the "StringsFunctionSample" project. You can see the Web Service in the "swagger" page.
The two methods are present in the "StringsFunctions" section.
Expand the "StringsFunctions" node.
Test the "uppercase" function
Now, let's test the methods by invoking the Web Service.
Click on the "/Functions/StringsFunctions/uppercase" service. Set the "string" parameter, such as "test".
To call the web service press the "Try it out!" button. You can see in the response that the string is correctly convert in uppercase.
Test the "lowercase" function
Click on the "/Functions/StringsFunctions/lowercase" service. Set the "string" parameter, such as "TEST".
To call the web service press the "Try it out!" button. You can see in the response that the string is correctly convert in lowercase.