SAPUI5 Tutorial - Fragments

Webforms with fragments

In this post we will be using fragments to create a webform that allows the user to easily view and edit the information in the form.

Fragments are just like partials if you are familiar with Ruby, they are constituent parts of a view. That is to say that they are a tiny part of a view, that can be re-used. For instance if you had one element that appears on every page no matter what e.g. navbar, then you could put all of the relevant code for the navbar into a fragment and then import that fragment on every page.

In this tutorial we will build a webform and then create two fragment files that will allow us to view and edit the form information, respectively.

Step 1: Building the form

As we did in our first tutorial, we create a new project from template, the template of SAPUI5 application. Now we're going to edit our view to show us some basic form information, delete everything in your view file and paste the code below:

Remember to update the controller name, it follows the format of `projectname.controller.view-file`.

Now if you run the project you should see something very similar to the screenshot below:

Note:In this post the examples will be using i18n variables for form labels. You must either create the labels in i18n yourself or remove the reference and type your own labels to make text appear in labels! If you want to use i18n labels, read the next section. Otherwise skip it!

Extra step: i18n labels

Go into your i18n.properties file and add the variables for each of the form labels, I pre-fixed all of my labels with form_ and then the label name. e.g. form_name.

You can then invoke these variables in your view like so: {i18n>form_name}. You use the i18n model and then you pull the variable from it, in this example we're pulling the form_name variable, from the i18n model. You should do this for all of your labels!

Step 2: JSON model for our data

You may have noticed that in the various form inputs I used some variable references to nothing, that's because we're going to use a JSON model for our form data. We can use a JSON model to store the information we enter and to display it.

Create a new json file in your models folder and call it whatever you would like, it will store the data for your form. In my case it's going to be some information about your job such as your role, team and base location.

Now that you've created your JSON, populate it with some key-value pairs that you want to use in your webform, here's my JSON:

What we're going to do now, is write a controller that will take our JSON model and bind it to our application. The first step to achieving this is adding the namespaces we need to our UI definition. So where we had 'sap/ui/core/mvc/Controller' we will add the following items:

'jquery.sap.global'

'sap/ui/core/Fragment'

'sap/ui/model/json/JSONModel'

You must then bring each of these namespaces to our controller instantiater, that's the opening function. Where previously we only had Controller as a parameter, we will now add each of the following to the function as parameters:

jQuery

Fragment

JSONModel

Note: We won't be using all of them right now, in fact we'll only be using the JSONModel.. But soon we're going to need our fragment and jquery!

Now that we've added our namespaces we can get to writing our controller. We're going to be a little more neat than what we start with, so you can delete the whole return statement in our last code example and we will write a new controller:

var PageController = Controller.extend("webform.controller.View1", {
onInit: function (oEvent) {
//module path follows the same format as other SAP imports, project_name.folder... until we get to our model e.g. data.json
var oModel = new JSONModel(jQuery.sap.getModulePath("webform.model", "/data.json"));
//once we've created the model in the application, we set this to the view and then bind an element of the model to the current view.
this.getView().setModel(oModel);
//PeopleCollection is the top-level element in my JSON model, it is an array of elements which is why I am binding the first element in the array to the page
this.getView().bindElement("/PeopleCollection/0");
}
});
return PageController;

Note: Binding the model to the view means that we don't need to prefix the model's variables with the model name, it is our default model. You can of course set it up as a named model, which will be covered at a later tutorial.

Step 3: Displaying our model data

Now that the model is linked with the application, we want to use the data in our form.

Note: For those using i18n labels, this is where we need to back into our i18n.properties file and update/add our labels. If you're using my JSON model then you will want to add the following variables to your file:

To invoke a variable from your JSON model, it's as simple as wrapping the variable name in curly braces and because the controller bound the model to our view, there's no need to prefix it with the model:

Now that we've added our functions for displaying fragments in the page, we need to show a fragment on page-load as default. To do this we add this._showFormFragment("Display"); to our controller instantiation, after binding a specific element to our view. Your controller's onInit function should now look like this:

You can check to see if you've done it right, by going into the controller and changing this._showFormFragment("Display"); to the name of your second fragment, e.g. my second fragment is called Edit and so this line now reads: this._showFormFragment("Edit");.

Fragment swap controls

Now that we have both of our fragments ready, we need to add some controls to the page to swap between them and also to save changes we make to the form.

Additional controls to the view

The controls for changing which fragment we view will need to be accessible on this view no matter what, so we won't use another fragment for this because it means loading an additional fragment when it should just be a part of the base-page.