Creating Multi-Lingual Apps
- Marty Lechleider
Changing Item Labels - A Multi-lingual Form Example
There have been many requests to be able to change an item's label dynamically. A common use case might be creating a multi-lingual form where you can change the item labels to the user's selected language.
Currently FEB does not offer any javascript functions to be able to do this. However, if you are operating on a server where the secureJS property is set to false (in the Builder_config.properties) then you can use the functions that I have written. I have bundled them all up into a single javascript file that can be included in your application.
I have actually taken this one step further; using services and custom JavaScript I have created a mechanism where you could create multi-lingual forms. There are several components to this sample but what I will document here is simply how to use it with your forms.
**Changes due to NEW 8.6.1 Features**
In 8.6.1 we have expanded the JavaScript API greatly simplifying this example. Now, many of the objects have a getTitle() and setTitle() function which can be used regardless of the server setting "secureJS". There are a few items that did not get updated in 8.6.1 and we still have to use the original code provided in this post, those items are navigation buttons, tab labels and survey column headers. A defect was also found in the setTitle for the section object which we are investigating.
I have uploaded a new version of the MultiLangCode.js. If you are testing this on 8.6.1, replace the js file and you will be able to leverage the new API functions.
Note: make sure to import the application with data if you want to see the sample work correctly with sample strings.
The first set of steps are things that you will need to add to your form:
1. Add the MultiLangCode.js file to your application. Click the Settings tab...then Files...then click the Add button. Browse to the location of the file and click OK to add it.
2. Create a few temporary fields that will be used. Create a section and then place the following inside of it:
Single Line Entry which will contain the appID
Single Line Entry which will contain the formID.
Multi-Line Entry which will contain all the strings returned from a service call.
In the onShow of the section add the following javascript:
item.setVisible(false);
In the form properties...onShow event place the following code:
//set appID
BO.F_SingleLine.setValue(get(form, "__widget")._applicationUID); //if 8.0, otherwise remove
BO.F_SingleLine.setValue(app.getUID()); //if 8.5, otherwise remove
//setFieldID
BO.F_SingleLine0.setValue(form.getId());
//callservice to get strings
form.getServiceConfiguration('SC_GetStrings').callService();
3. Create a Service that calls the “Host” application.
Click the Settings Tab...Services...Form, 1 and click the Add Service Configuration button.
One the Service Tab, change the Catalog to Forms Experience Builder Application
Search for Multi Language Form and select the service called Multi Language Form / MultiLangStrings / Retrieve
On the Inputs tab:
Link the appID field with Retrieve by Application ID
Link the formID field with the Retrieve by FormID
On the Outputs tab:
Link the Array Content with the Contains Strings field
On the Details tab change the service ID to SC_GetStrings
4. Add a listener that will initiate the language change once the service from step 3 is finished.
In the Form onLoad event add:
var srv = form.getServiceConfiguration('SC_GetStrings');
srv.connectEvent("onCallFinished", function(success)
{
if(success) {
app.getSharedData().strings = JSON.parse(BO.F_Paragraphtext.getValue());
}
});
You will have to change 'SC_GetStrings' to the ID of your service, if you change it from this instruction.
You will have to change the 'BO.F_Paragraphtext' to the ID of the text field if you change it from this instruction.
5. Determine how you are going to toggle the language and call the function to cause the labels to change. The example below sets the titles based on a language passed to the function as the result of toggling a radio selection.
app.getSharedData().setLanguage(BOA.getValue());
You could also change the language by reading a URL parameter:
var lang = "English"; //defaults to English
var urlP = app.getUrlParameter("lang");
if(typeof urlP !== "undefined") {
lang = urlP;
}
app.getSharedData().setLanguage(lang);
The second set of steps will require that you enter all of your language strings into the “host” application that has been provided with this example. I will provide a few comments on how the form is used.
1. Deploy the Multi Language Form application (this must be completed before step 3 above).
2. Launch the MultiLangStrings form
3. Each form will contain its own instance of this form. Enter the applicationID, formID and pageID for the form you want to enter language strings.
4. Enter the and item id of the first item you want to enter strings.
5. Select the item type. If the specific type is not listed then assume that it is field.
Some types will require you to enter an index. Note that the index starts with zero (0) and if the type is pageNavigator then the index will be either next or previous to define which button you are providing strings
6. Enter the language selection and then Enter the label for that language.
7. Click Add Label Text
8. Repeat until all the strings have been entered for all the items on your form.
9. Click Generate Array Content, this may take some time depending on how many strings you entered.
10. Click Submit to complete the form.