DEV Community: Dumitru Corini

Development of a UI Designer page as done at Bonitasoft, Part Two

Dumitru Corini — Mon, 10 May 2021 10:37:12 +0000

This article is a continuation of the article Development of a UI Designer page as done at Bonitasoft, Part 1 in which I talked about general page design choices, and then specifically about a list-styled page. I suggest reading that first before you read this.

In this article, I will detail the edit group modal. I chose to focus on this as it has most of the things you can find in other modals - and more.

Modal general decisions

To talk about modals, we first need to talk about the widget itself. The modal widget cannot be included inside another container in the whiteboard, which means that a UI Designer developer needs to choose where to put the container. When we started using the modal widget, our team decided to put modal widgets at the bottom of the editor, just as the UI Designer recommends.

Embed modal containers

Our team made a choice early in the development process to not allow a modal to be opened by another modal, so we had to look for other options when we had to decide how to edit something inside a modal. We wanted to simplify the user flow, because opening a modal inside another one raises questions about what would happen in the case of partial changes.

Keep the page consistent with changes made inside a modal

To keep the page consistent with the changes that are made inside a modal, we usually append a timestamp to the url that needs to be called. This way, if we update information in the groups list, all we have to do is modify the timestamp to trigger the API call again and get the recent changes.

Opening and closing a modal

Next up is our way of handling the closing and reopening of a modal. In the current UID state, there is no way of closing the modal easily since a modal can be closed in two different ways: with a button, and by clicking outside of it. Thus, there is no way to clean the modal state when closing the modal window. This causes problems when, for example, you have a modal state that is specific to an item; you close it and then open a modal for a second item. The state of the second modal will carry over some information from the first modal. Our solution was to clean the state of the modal upon opening.

Modal mock-up

Since the edit group modal is similar to the ones that we have already designed in other pages, we decided to not create a mock-up for this one in particular. Nonetheless, here’s a mockup of what we usually do for a modal:

Modal structure

To style the modal and separate its parts, we use three different containers in the modal and add the css classes “modal-header”, “modal-body” and “modal-footer” to the top, middle and bottom containers. That lets us separate the modal into three sections as you can see on the image above. I should mention that these are bootstrap classes and thus we don’t need to create css specially for them. In rare cases, if needed, we can tweak the style to, for example, add a bigger edge on the sides of the modal. In the case of the edit group modal, we didn’t change anything in the default bootstrap styles.

The edit group modal

This modal will be used by the end-user to modify a specific group. The fields that we let the end-user modify are the name, display name, description of the group, as well as the parent group.

Implement the edit group modal

As explained in Development of a UI Designer page as done at Bonitasoft, Part 1, whenever we work on a feature we try to use up to four variables. In this case, we will only create two : editGroupData and editGroupCtrl.

For the API call variable, we tried using one to get the information of the current parent, but as it was a bit too complex to manage, it became its own modular feature. I will talk about this feature later in the article.

The fourth variable type is a handler. I’m going to talk about it later as well since we decided to merge it with handlers of other page features.

And lastly, we have the two buttons at the bottom of the modal. I will talk about these at the end of the article.

How to open the modal

To avoid problems with states that persist after reopening a modal, initialize the modal with the item to edit when the modal is opened. This is then passed to the modal when it opens. To do this, add a function in the controller editGroupCtrl.

The function will look like this:

return {
    initEditGroupModal: function($item) {
        $data.editGroupData.selectedGroup = $item;
        return "editGroupModal";
    }
};

Also add the selected group to the data variable editGroupData, which will look like this:

return {
    selectedGroup: {}
};

Next, use the initEditGroupModal function in the edit button, in the repeatable container list created in part one. Set the action of the button to Open modal, use an expression for the Modal id property, and then use editGroupCtrl.initEditGroupModal($item) as the value. Now, whenever we click the edit button in the list, it will call the initEditGroupModal function and pass the row item from the list as a parameter.

Use this selected group to show the display name of a group inside the modal-header container:

{{"Edit group"|uiTranslate}} {{editGroupData.selectedGroup.displayName}}

This should be good for the modal title.

Edit the group’s simple fields

Since we want to make the modal the same as the one in the current portal, we will provide the end user with the ability to modify fields like name, display name, description and parent group. The first two will be simple input fields, and we decided to use a text area for the description since it would display better. I will go into detail about the parent group a bit later since modifying it is a bit more complex.

Let’s backtrack a bit and talk about the editGroupData variable again and its use in the above mentioned fields. The variable will be used to keep the values of the input fields during the runtime. Thus, its updated value will be:

return {
    name: "",
    displayName: "",
    description: "",
    selectedGroup: {}
};

Use the editGroupData.name for the name input, and name the other inputs accordingly.

The initEditGroupModal function also needs to be updated to show the values of the display name, name and description when the user opens the modal. To do this, add these lines:

$data.editGroupData.name = $item.name;
$data.editGroupData.displayName = $item.displayName;
$data.editGroupData.description = $item.description;

Another way to do this would be to use the fields of the object selectedGroup instead of three individual fields (name, displayName, description).

Let’s talk about the parent group now. Since the API request for the group returns an id for the parent group and we want the display name, we will need to do an API call currentParentUrl to get the information. Since the parent of our group is another group, the API call will look something like this: ../API/identity/group/{{editGroupData.selectedGroup.parent_group_id}}

Add an input field and use the currentParentUrl.displayName to display the current parent group.

You should have something like this:

Edit the parent group

What we have done so far is display the current parent group, and now we want to be able to edit it. Since we already made a decision to not open a modal by another modal, our team next decided to go with an input that has two states (view and edit). We also wanted to let the user be able to go back to the current parent group if they changed their mind midway through the choice of a new parent group.

To make this modular, we created three variables (currentParentUrl, currentParentData and currentParentHandler). For the currentParentData, we used:

return { 
    currentParentId: undefined,
    timestamp: 0
}

We also changed the currentParentUrl to ../API/identity/group/{{currentParentData.currentParentId}}?t={{currentParentData.timestamp}} and added $data.currentParentData.currentParentId = $item.parent_group_id; to the initEditGroupModal
to reset the current parent when opening a new modal and $data.currentParentData.timestamp = new Date().getTime(); to get the information for the new parent.

If the currentParentId is the same when we enter the modal, there is no need for an API call to get the parent information.

Switch between the view and edit states

Next add the second (edit) state, and a button next to each one of the inputs to switch between the two states. You should have something like this:

For these buttons to change the state, we will use a collection of actions. Whenever the end user clicks on one of the buttons, we will add a value into this collection. The handler will then catch and treat the action that was added.

First add the array to the currentParentData. We also need a variable that will keep the current state (editingParentGroup). After these additions, the data variable should look something like this:

return {
    currentParentId: undefined,
    actions: [],
    editingParentGroup: false
};

Now, set the button actions to Add to collection. The position in the array where you add the value doesn’t really matter, but the value to add should be edit for the first one and cancel for the second one.

Let’s talk about the last piece of the puzzle, the handler.

Its value will be this:

if ($data.currentParentData.actions[0] === "edit") {
    $data.currentParentData.editingParentGroup = true;
    $data.currentParentData.actions = [];
}

if ($data.currentParentData.actions[0] === "cancel") {
    $data.currentParentData.editingParentGroup = false;
    $data.currentParentData.actions = [];
}

This changes the state, and empties the actions array to execute the action only once.

For these values to be taken into account, use this field in the two input field containers. Use currentParentData.editingParentGroup as an expression for the hidden property value of the first button, and !currentParentData.editingParentGroup for the second.

Don’t forget to change the initEditGroupModal function to reset the values of the above fields when the user opens the modal. Simply add these lines to the function:

$data.currentParentData.currentParentId=$item.parent_group_id;
$data.currentParentData.editingParentGroup = false;

Implement the edit state

Now that you can change between the view and edit state, make the edit state work. As there is an autocomplete in the portal, we wanted to have something similar here. The catch is that the autocomplete widget that is provided in the UID doesn’t support returning an entire object - it only returns one field from the object.

Returning an entire object is important since we want to have both the id of the selected item and the display name to display. (Note that there is a fix in the 2021.1 version of the UI Designer that will let you return an entire object. We will update the pages accordingly.)

Since this fix is not yet here, the current implementation of a custom autocomplete uses a repeatable container. To do this, put the two parent group inputs into a single container and add another container for the autocomplete suggestions of possible parent groups. Display a text widget title with the value <strong>{{"Name" | uiTranslate}}</strong> to tell the end user to choose between the names of the parent groups. The container added under the Name title will be a repeatable container and, thus, it will have one option per row, just like we did with the list in part one. We will set the value of the collection property for this container later.

You should have something like this:

Get the list of possible parent groups

Now, for the functional part. We created a full-fledged feature module here since it will also be used by the create group modal.

The first variable is parentDropdownData. Its value is:

return {
    searchParentValue: "",
    selectedParentDisplayName: undefined,
    selectedParentId: undefined,
    selectedParent: []
};

searchParentValue is used as the value of the input. The selectedParent acts as a sort of action array when a parent is selected, from which selectedParentDisplayName and selectedParentId are extracted.

We extract these because we found it easier to work with $data.parentDropdownData.selectedParentDisplayName instead of $data.parentDropdownData.selectedParent.displayName, but you can use the the second option if you want.

Since we have the data, we can use parentDropdownData.searchParentValue as the value of the edit state input.

The second variable is the parentDropdownUrl. Its value is ../API/identity/group?p=0&c=20&o=name&s={{parentDropdownData.searchParentValue}}.

When the value is defined in the variable itself, an API call will be made when the page is opened and there will be no value for parentDropdownData.searchParentValue. So to fix this, create the third variable, parentDropdownCtrl and add a function:

getParentSearchUrl: function() {
    if ($data.parentDropdownData.searchParentValue && 
        $data.parentDropdownData.selectedParentDisplayName !== 
        $data.parentDropdownData.searchParentValue) {
            return "../API/identity/group?p=0&c=20&o=name&s="+$data.parentDropdownData.searchParentValue;
    }
    return undefined;
}

If an API call variable has undefined in it’s value then the API call is not made. So, first check if there is a value in the input; if there is no value, there is no need to do an API call. Next check if the value entered is the same as the one that is selected, so the API call is not made again.

(Imagine you want to look for Acme and you type A. An API call will be made to search for A. When you select Acme from the returned values, there is no need to redo an API call with Acme.)

Use {{parentDropdownCtrl.getParentSearchUrl()}} as the value for parentDropdownUrl.
Now that there is an API call, there is another thing to consider before displaying the result. Displaying the full list of possible parents could introduce possible performance issues, so we went with displaying only 20 and then telling the user to type more. To do this, append the Or type more to the list of 20 elements. We can add this to parentDropdownCtrl:

getFullSearchParentList: function() {
    var fullParentList = $data.parentDropdownUrl;
    if (fullParentList && fullParentList.length == 20) {
        fullParentList.push({
            displayName: uiTranslate("Or type more...")
        });
    }
    return fullParentList;
}

To display the list of parents, use parentDropdownCtrl.getFullSearchParentList() as the collection property value of the repeatable container.

Select a parent group from the list

Now add a button in the repeatable container that, when clicked, triggers the selection of a parent group. To make it prettier, we went with a style property link. Like the other action trigger, the button has Add to collection as the action property. The collection would be parentDropdownData.selectedParent and the value is an expression with the value $item. This lets you add the selected parent group object into the array. For the label, use {{$item.name}} to display the name of each item in the repeatable container.

Then, create the fourth and last variable parentDropdownHandler. Like the one for switching between the view/edit states, this one will catch a variable state, perform an action and clean the variable so the action is done only once. To do this:

if ($data.parentDropdownData.selectedParent && 
    $data.parentDropdownData.selectedParent.length > 0) {
        $data.parentDropdownData.searchParentValue=$data.parentDropdownData.selectedParent[0].displayName;
        $data.parentDropdownData.selectedParentDisplayName=$data.parentDropdownData.searchParentValue;
        $data.parentDropdownData.selectedParentId=$data.parentDropdownData.selectedParent[0].id;
        $data.parentDropdownData.selectedParent = [];
}

This sets the input field to the value selected, extracts the two fields that we want and cleans the selected parent, so the action is not re-triggered.

Now for the finishing touches for the autocomplete. Since the user should not be able to click on Or type more, add a function that will make the option unclickable. To add into the parentDropdownCtrl:

isSearchParentMore: function(item) {
    return item.name === uiTranslate("Or type more...");
}

Use this function by using a disabled expression with the value parentDropdownCtrl.isSearchParentMore($item). This will check if the item has the value of the field name equal to Or type more and disable it.

If you run this, you should see a small problem: the dropdown is always visible. To fix this, use an expression for the hidden property of the repeatable container with the value parentDropdownCtrl.hideDropdownMenu(). This function checks if there has been no API call response for the parentDropdownUrl. If the response is empty (no parents are available with the current search value) or if the current search value is empty (nothing in the input):

hideDropdownMenu: function() {
    return !$data.parentDropdownUrl
           || $data.parentDropdownUrl.length === 0
           || $data.parentDropdownData.searchParentValue === "";
}

Then clean the parentDropdownUrl when a value is selected so the suggestion box disappears. Add $data.parentDropdownUrl = undefined; to the parentDropdownHandler.

And you should be good for the autocomplete. The end result will look like this:

Style of the autocomplete

Before continuing, let’s look at the styling of what was just done. Let’s start by adding the css classes. If you look at the image above, the bottom container uses the class dropdown dropdown-parent-group, while the container that displays the names of the possible parents uses dropdown-menu. We use the dropdown and dropdown-menu classes from bootstrap and add dropdown-parent-group to be able to override the default definition with a more specific CSS class.

Also add this to the style.css file:

.dropdown-parent-group .dropdown-menu {
    /* so that it stays on screen and avoids a scrollbar in the modal */
    position: relative;     
    display: block;
    /* to make it’s width the same as the input width*/
    width: 95%;
    /* to align it with the parent group input */
    margin-left: 15px;
    padding-left: 10px;
}

.dropdown-parent-group .dropdown-menu button {
    /* ellipsis */
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
    text-align: left;
    /* for it to not surpass the size of the entire container */
    width: 98%;
}

.dropdown-parent-group .dropdown-menu button:hover {
    /* so that it shows which item is selected */
    background: #2c3e50;
    color: #fff;
    /* so that some things are removed */
    text-decoration: none;
}

The action buttons

There are two action buttons in the modal footer. Let’s look at the first one, the Save button. This button will be used to make a PUT API call with the URL ../API/identity/group/{{currentParentData.currentParentId}}. Next, create the payload that will be sent when the end user clicks on the button. Create a function in editGroupCtrl called getEditGroupPayload:

getEditGroupPayload: function() {
        return {
            name: $data.editGroupData.name,
            displayName: $data.editGroupData.displayName,
            description: $data.editGroupData.description,
            parent_group_id:$data.parentDropdownData.selectedParentId
        };
}

This function will create a json object with the values that have been input by the end user. You can now use this function (editGroupCtrl.getEditGroupPayload()) in the Data sent on click property of the button. Don’t forget to set it as an expression, since the value needs to be calculated instead of being interpreted as text. Two things should be done when we get a response. The first is to show an appropriate message depending on the response of the API call. The second is to refresh the list in the background.

Tackle these one at a time. For the first one, add statusCode: “” to the editGroupData and use it in the HTTP status code property field (editGroupData.statusCode). You can then add text fields that will be hidden if the value of the statusCode is different than the one for the message.

For example, here are three uses of this variable:

Use in case of a success. The hidden value should be editGroupData.statusCode !== 200. The message will be hidden if the API call response status code is not 200.
Use in case of an error. The hidden value is editGroupData.statusCode === "" || editGroupData.statusCode === 200. It will be hidden if there is no statusCode (when no API call was made) or when the API call is a success.
Use in case of a specific error code, but where multiple errors are possible. For example, the group API returns a 403 if the user is not authorized to access the API and if a group already exists with the same name. To treat this, use a variable failedResponse in the failed response value and a function getErrorMessageFor403 that will take the failed response and return an error message. It will look like this:

getErrorMessageFor403: function(failedResponse) {
    if (failedResponse
        && (failedResponse.exception.indexOf(‘AlreadyExistsException’) > -1
        || failedResponse.message.indexOf('AlreadyExistsException') > -1)) {
            return uiTranslate("A group with the same name already exists.");
    }
    return uiTranslate("Access denied. For more information, check the log file.");
}

All this does is check if the error is of type AlreadyExistsException, by checking if that text exists in the exception or the message of the failed response. The text can be customized as you please. To use it in a text widget, use
{{editGroupCtrl.getErrorMessageFor403(editGroupData.failedResponse)}} as the value.

Refresh the list of items after an API call

Let’s backtrack a bit and talk about refreshing the list of groups that should happen behind the modal. Just as the parentDropdownHandler treats the response of the API call for the possible parents, create a refreshHandler that will allow editing a group. First, add a timestamp field in the groupsData and add &t={{groupsData.timestamp}} at the end of the groupsUrl. As explained at the beginning of this article, updating this timestamp will trigger the API call again. The rest should be simple - when there is a successful API call for the save button, change the groupsData.timestamp:

if ($data.editGroupData.statusCode === 200) {
    $data.groupsData.timestamp = new Date().getTime();
}

This implementation has a huge flaw though: it will cause an infinite loop of refreshing the page when the group has been successfully edited. This is because the value of the field statusCode in editGroupData stays at 200, and the timestamp keeps changing every time there’s an action on the page (like, for example, an API call response that arrives). The easiest way that we found to fix this is to have an additional variable that will see if a group has been updated recently. Add hasRecentlyBeenEdited to the editGroupData. Change the refreshHandler code to take this field into account:

if ($data.editGroupData.statusCode === 200 && !$data.editGroupData.hasRecentlyBeenEdited) {
    $data.groupsData.timestamp = new Date().getTime();
    $data.editGroupData.hasRecentlyBeenEdited = true;
}

And, again, don’t forget to reset it’s value in the initEditGroupModal function:

$data.editGroupData.hasRecentlyBeenEdited = false;

You can disable the button when the name value is empty. Add editGroupData.name === "" as an expression for the disabled property of the Save button. You can also disable all the fields after an update by checking that the hasRecentlyBeenEdited value is true.

The last thing to consider for this modal is the cancellation button in the modal footer. If there is a successful update of the group, the label Cancel might make the end user think the update could be cancelled, so change the label to Close. This is done, once again, with the use of a function:

getChangeButtonLabel: function(statusCode) {
    return statusCode === 200 ? uiTranslate("Close") : uiTranslate("Cancel");
}

We added this to the groupsCtrl since it’s also used in other modals.

This is how the full modal looks in the end on our side.

And this in the preview:

Conclusion

So, now you know how we develop a modal with the UI Designer and you can do the same, with all the tips and tricks that we employed, like how to use a UID button to trigger an action on the page, how to create an autocomplete widget custom implementation, and how we treat errors using an API call response.

And, as mentioned in Part 1, the next step is to create tests. You can find more information about how to test a Bonita UI Designer page in this article. You can also find everything about this development and more in our web pages project.

Development of a UI Designer page as done at Bonitasoft

Dumitru Corini — Thu, 18 Feb 2021 15:28:38 +0000

This article is intended to provide insight into the internal development process of a user interface page and to explain some of the design choices that we have made at Bonitasoft. These page design choices should drive you towards more maintainable code and also give you some insight on best practices when creating Bonita UI Designer pages.

In this article, I will provide a step-by-step explanation, with examples, of how user interface pages are developed by the Bonitasoft team. Our work is aimed at replacing some of the existing pages of the current Bonita Portal.

Since we work in agile, our design choices are not set in stone - we update them when we decide it’s appropriate to do so, and then apply the changes to all the pages. But, generally speaking, the choices explained here are ones that apply to pretty much every page that we create.

And before I start, I’ll note that if you are using a 2021.1 version of the Bonita development suite, you can import the pages we’re developing from the open source web pages project. They can be used as examples, and customized to your own needs.

Before starting development

When we start developing a page, we first create a mockup of what we want the finished page to look like. This is mostly done in Paint.NET, and sometimes in Balsamiq, the Bonita UI Designer, or even using pen and paper. The benefits of specifying the page needs this way, before the development starts, fully outweigh the cost of the time and effort it takes to do this. For one thing, it lets us discuss the feasibility of new features. We have developed two types of pages that cover most use cases - list and details - so we choose the appropriate page type (skeleton) at the start.

General UI Designer standards

There are three standards that we apply with each new page that are useful to know before we proceed.

First, we always version our pages with a V* suffix and update the version after each release. This way, someone that is external to Bonitasoft can import any page and modify it as they please, knowing that it won’t be overwritten when they upgrade to another version of the product.

Next, it’s useful to understand the way we work with variables in the Bonita UI Designer. We always try to have four variables per feature:

The external API to retrieve the data
A JavaScript variable that will hold the data - for example, the filter values or actions to be made
A controller JavaScript variable containing utility functions or those that change the state of the data
An event handler JavaScript variable. This listens to the data and prompts action depending on changes in it

And then, there are the page offsets. Depending on the size of the screen, we use an offset of 0/1/1/2 for xs/sm/md/lg screen sizes. These were chosen for two reasons:

The first is the look and feel of the application. Our application uses AngularJS pages in addition to the UI Designer pages that we are developing. We wanted to keep a consistent look and feel between the two types of pages without having to change much in the AngularJS pages.
The second reason comes from experimentation and is a subjective one. We tried 1/1/2/3 and 0/1/2/3 sizes, but neither of these looked as good to us as our current choice.

Now I’ll illustrate the page design process, using the Groups page as an example.

Overview of the Groups page

The Groups page is useful to integrate into an admin application, as its purpose is to show the groups of people in an organization. Some examples of groups might be the “North America” group or the “Research & Development” group. Each group will have a number of users associated with it, and might have sub-groups. For example, the North America group might have a Research & Development sub-group, and Walter Bates could be a member of that sub-group. (The mockup for this page, shown below, was done with the help of Paint.NET.).

As mentioned above, we usually start by creating the skeleton of the page in the Bonita UI Designer. Since this is a page of the type list, we will get a collection of items from the API call and then use the repeatable container to display the information for each item. Getting the information in the Bonita UI Designer is easy and straightforward. We create an external API variable, called groupsUrl with the value ../API/identity/group?c=10&p=0&o=displayName ASC. This is everything needed to get the information from the API and save it in the groupsUrl variable.

Displaying the list of groups

Now of course we want to display this information. As mentioned above, our team usually uses page offsets. To apply the aforementioned offsets, the current solution is to drag and drop a container, change its size to 1, add a second container next to it, change its size to 10, and then add a third container to its right. This will create offsets of 1 for the page. Next, go through each one of the xs/sm/md/lg sizes and change the left and right containers accordingly.

For the data, we can drop a container in the middle container and use groupsUrl as a value in the collection property of the new container. For each item in the list to have a delimiter, we can add group-item as a CSS class for this container. For the fields to display, from the mock file, we see from the mockup that we want to show the data for Display name, Name, Parent group, Created on and Updated on. We also want the user to see the description at the bottom of each item. Since we will also have some buttons to the right, we start by adding a container that has size 9 inside the repeatable container. We can drop an additional container to the right of it in which we will put the buttons later.

For readability purposes, we usually put each field in a separate container. The sizes for each field is for you to define; we went with 2, 2, 3, 2, 3 because we thought it looked good on the page. In each container, we added two text widgets: the first acts as a label, and the second holds the value. These also have item-label and item-value CSS classes respectively so they are styled accordingly. The item labels are taken from the mockup image. They can be simply written as the text widget values. For the item values, we usually look at the API call to know which json object property to display, and we use the standard angularjs interpolation. For example, since we want to display the name of a group, we use {{$item.name}}.

There are three special cases that don’t follow this item-label/item-value formula.

The first is when trying to display a date. Even though dates have the item-label/item-value CSS classes, the values need to use a specific formatting. This is done by using the uiDate AngularJs directive, so the value of the item-value text widget will be {{$item.creation_date.replace(" ", "T") | uiDate:'short'}}, which formats the creation date here with the short style.

The second specific case is the description. As we can see on the mockup, there is no item label, and the third and fourth group have no description. To create this we add two text fields with the item-label CSS class. The first text field has the value {{$item.description}}, and the second one has No description. We can now use the hidden property on each of the text widgets to display depending if the description property is empty.

The third specific case is the parent group. As we can see on the mockup for the first group, the parent group value is --. We will need a function to know if there is no parent group. As I said earlier, our team usually puts this kind of function in a controller variable. So, we create the groupsCtrl variable with the value:

return {
    isInformationEmpty(information) {
       if (!information) {
           return "--";
       }
       return information;
    }
};

We can then use this function in the item value field for the parent group.

Another important thing to note about this parent group is that it has the potential to have a really long value. We use a tooltip to display the entire value, so the value for this field would be something like this:

<div title="{{groupsCtrl.isInformationEmpty($item.parent_path)}}">
   {{groupsCtrl.isInformationEmpty($item.parent_path)}}
</div>

To style everything, we went with this CSS, which not only creates a delimiter between each item, but also creates specific styles for the item values and the item labels. The last thing it does is create a hover effect on each item.

.group-item {
    border-bottom: 1px solid lightgray;
    overflow: hidden;
    transition: 0.3s;
    padding-top: 0.5rem;
}

.group-item p  {
    margin-bottom: 0;
}

.group-item:hover {
    box-shadow: 0 0 5px;
    margin-top: 0px;
}

.item-label p,
.item-label.component {
    font-size: 11px;
    opacity: 0.7;
    margin: 0;
    padding-right: 0;
    word-wrap: break-word;
    word-break: break-word;
}

.item-value,
.item-value a,
.item-value p {
    font-size: 12px;
    margin: 0 0 3px 0;
    padding-right: 0;
    word-wrap: break-word;
    word-break: break-word;
}

In the end, it looks something like this in the Bonita UI Designer whiteboard for a lg screen.

With something like this in the preview.

After displaying the list of groups, what remains to do are the filters, the load more items button and the action buttons. There are also still some small improvements to do to the page itself, like adding a title, showing the number of displayed items for when we will use load more and also adding a message to display when there are no groups available.

We add the buttons first, and will implement them later. For the three small improvements, they are pretty straightforward, so I will not go into detail here. Just keep in mind that after we finish the load more button, there will be some small changes to when we display the number of items shown and the no more groups message.

Filters

Let’s start with the filters and specifically, with the data that we need to create for the filters. We can add a new Javascript variable, groupsData, that will contain the following:

return {
    sortByOptions: [   
        { displayKey: "Display name (Asc)", returnKey: "displayName+ASC" },
        { displayKey: "Display name (Desc)", returnKey: "displayName+DESC" },
        { displayKey: "Name (Asc)", returnKey: "name+ASC" },
        { displayKey: "Name (Desc)", returnKey: "name+DESC" }
    ],
    filters: {
        sortOrder: "",
        searchValue: ""
    }
};

The sortByOptions array contains the “sort by” possibilities. As you can see, each object contains a displayKey and a returnKey. The first is what the user will see, and the second is what will return from the select box when the user chooses the value. The filters object contains the values of the sort select box and the search input. We usually add a container for the filters and a CSS class to leave a small space between the title and the filters. With this data created, we can now add the two filters. To take into account the values of the filters, we create a function that will use the filter values. We also need to use this function in the external API. Add the following to the groupsCtrl variable:

groupsQueryParameters: function() {
    var queryParameters = "c=10&p=0”;
    if ($data.groupsData.filters.sortOrder) {
        queryParameters += "&o=" + $data.groupsData.filters.sortOrder;
    } else {
        queryParameters += "&o=displayName ASC";
    }
    if ($data.groupsData.filters.searchValue) {
        queryParameters += "&s=" + $data.groupsData.filters.searchValue;
    }
    return queryParameters;
}

We can then use the function in the external API, with the new value for groupsUrl : ../API/identity/group?{{groupsCtrl.groupsQueryParameters()}}

Load more items button

The current implementation of the load more button follows a specific algorithm. When the page is loaded, there is an API call for 20 items (2 pages of groups). If there are more than 20 groups, we will get 10 items (the third page of groups) as a result of the button click, but the second page from the first API call is displayed. Clicking the button again, we will do a third API call to get 10 items and display the 10 items of the second API call.

To know when to disable the button, we need to be able to display a page from memory and get the next page of items from the API. When there are no more results in the API, we will know that the button should be disabled. To implement this load more button, we found that we need at least 4 variables.

We also created 2 variables that we found useful, but are not absolutely necessary.

For the 4 variables that are necessary:
An array that will keep the groups that are displayed currently
An array with the result from the API for page 3 and after
An array that keeps the next results to concatenate to the current displayed ones
A variable that keeps the current page

And, the 2 other variables that are useful are:

One that keeps the number of groups to request per page in case we want to switch to another number
One that saves the number of groups that we will have for the page in the memory

So, in the end, our groupsData will look like this:

return {
    groupsInMemory: [],
    pageId: 0,
    groupsFromAPI: undefined,
    displayedGroups: [],
    numberOfGroupsPerPage: 10,
    numberOfgroupsInMemory: 0,
    sortByOptions: [   
            { displayKey: "Display name (Asc)", returnKey: "displayName+ASC" },
            { displayKey: "Display name (Desc)", returnKey: "displayName+DESC" },
            { displayKey: "Name (Asc)", returnKey: "name+ASC" },
            { displayKey: "Name (Desc)", returnKey: "name+DESC" }
    ],
    filters: {
            sortOrder: "",
            searchValue: ""
    }
};

The implementation

Let’s start by setting up the API calls. To keep them generic, we modify the query parameters function in the controller by passing the page number. At the start of the page it will be 0 and we should get 20 elements. After the first call, we pass a page number to the query parameters function. The function in the end should look something like this:

groupsQueryParameters: function(pageNumber) {
        var groupsPerPage = $data.groupsData.numberOfGroupsPerPage;
    if (pageNumber === 0) {
        //on first call we need to load two pages
        groupsPerPage *= 2;
    }
    var queryParameters = "c=" + groupsPerPage + "&p=" + pageNumber;
    if ($data.groupsData.filters.sortOrder) {
        queryParameters += "&o=" + $data.groupsData.filters.sortOrder;
    } else {
        queryParameters += "&o=displayName ASC";
    }
    if ($data.groupsData.filters.searchValue) {
        queryParameters += "&s=" + $data.groupsData.filters.searchValue;
    }
    return queryParameters;
}

We need to consider two more things: the load more button itself and the event handler.

The load more button should do an API call to get the groups after the first page, thus it will have ../API/identity/group?{{groupsCtrl.groupsQueryParameters(groupsData.pageId)}} as the url to call. The successful response will be stored in the groupsData.groupsFromAPI array. The button should be disabled when the number of groups displayed cannot be divided by the number of groups per page. For example, if there are 24 elements, there will be 4 groups left after the second page is shown.There is no fourth page. So after showing the third, we can disable the button. We also disable the button if there are no groups in the memory. So, the condition is: groupsData.displayedGroups.length % groupsData.numberOfGroupsPerPage > 0 || groupsData.numberOfgroupsInMemory === 0

We also want to hide the button if the displayedGroup array is empty, so we need to take into account if there are any groups to display. So, for the “groups shown” and the “no group to display” fields, we need to verify if the displayedGroup array contains data.

To complete the list feature, we configure the load more handler. There are three different data states which trigger it:

When the user first arrives on the page
When the user clicks on the load more button and there is another page to display
When the user clicks on the button and there are no more pages, but there is still something in the memory

Let’s tackle each one of these separately. After we get the first 2 pages from the API, we save the first page in the displayedGroup array and save the second page in the memory in groupsInMemory. We also set the number of groups for the next page to be equal to the size of groupsInMemory. Then we set the pageId to 2 in order to get the third page the next time we do the API call, and to set the groupsUrl to “empty” in order to do all of this only once. During the execution, we don’t need to reuse the groupsUrl.

The second part of the load more handler should add the page from memory to the displayed list of groups, and add the page returned by the API to the memory. We should also increment the pageId so the next API call will request the next page. Lastly, we make the result from the API request empty so this gets executed only once.

The third part of the load more handler adds the results from the memory, and then cleans those results from the memory, so we don’t execute the case multiple times.

In the end, the handler looks something like this:

if($data.groupsUrl) {
    $data.groupsData.displayedGroups = $data.groupsUrl.slice(0, $data.groupsData.numberOfGroupsPerPage);
    $data.groupsData.pageId = 2;
    $data.groupsData.groupsInMemory = $data.groupsUrl.slice($data.groupsData.numberOfGroupsPerPage);
    $data.groupsData.numberOfGroupsInMemory = $data.groupsData.groupsInMemory.length;
    $data.groupsUrl = undefined;
}

if($data.groupsData.groupsFromAPI && $data.groupsData.groupsFromAPI.length) {
    $data.groupsData.displayedGroups = $data.groupsData.displayedGroups.concat($data.groupsData.groupsInMemory);
    $data.groupsData.pageId++;
    $data.groupsData.groupsInMemory = $data.groupsData.groupsFromAPI;
    $data.groupsData.numberOfGroupsInMemory = $data.groupsData.groupsInMemory.length;
    $data.groupsData.groupsFromAPI = undefined;
}

if($data.groupsData.numberOfGroupsInMemory > 0 && $data.groupsData.groupsFromAPI && $data.groupsData.groupsFromAPI.length === 0) {
    $data.groupsData.displayedGroups = $data.groupsData.displayedGroups.concat($data.groupsData.groupsInMemory);
    $data.groupsData.groupsInMemory = undefined;
    $data.groupsData.numberOfGroupsInMemory = 0;
}

The end product looks something like this in the Bonita UI Designer whiteboard:

And something like this in the preview:

Conclusion

You now know how to develop a list styled page as us, at Bonitasoft do it!

And of course the next thing to do - which is very important - is to test the page. This article does not go into that, but you can find out more about how to test a Bonita UI Designer page using Cypress in this article. You can find the page I’ve described here, as well as others that were developed and tested, in the web-pages Github repository.

Thank you for reading and stay tuned for the next article about how the R&D at Bonitasoft develops the modals, which will be useful for modifying the list of groups.

How to test a Bonita UI Designer page using Cypress

Dumitru Corini — Tue, 15 Sep 2020 07:21:58 +0000

Once you’ve made a Bonita UI Designer page, testing it is very important.

To test pages made with the Bonita UI Designer, our team decided to move towards an e2e framework that is fast to set up and allows us to write tests efficiently.

We decided to use Cypress, an open-source, Javascript framework that lets you write Given-When-Then semi-structured tests.

Prerequisites

To fully grasp the power of this article, you need to familiarize yourself with a couple of technologies.

First, this article uses the Bonita UI Designer to create a simple page that lets you register a user.

Then, this article gives two test use cases of Cypress, without diving into the full potential of the tool. If you are interested in uncovering its other possibilities, I suggest checking out their documentation.

You can find everything discussed in this article in the github repository.
The two tests that I will talk about aren’t the only ones that you will find in the repository, so if you want to see more examples, you can clone the repository and then check them out.

Diving into the page structure

Let’s start with the page. It has a form container with multiple fields that will ask for different information in order to create a new user. You can see some messages that will be displayed in case of errors and success, as well as a loading message. There is also a hidden functionality that makes the success or error messages disappear after three seconds if the user takes any action on the page. We usually use this feature in order to mimic a toast and thus not clog the user's screen.

The test choices

Without further ado, let’s talk about tests.

Cypress tests are made from two distinct parts. The first is about writing the test scenarios in one file and the second is about explaining with code what each line of the scenario will do.
The cypress-cucumber-preprocessor library is used in order to write scenarios in the Given-when-then style.

The two tests that I am going to talk about are :

A failure in the creation of the user because the passwords don’t match
The loader being displayed while the user is being created

I chose the first because it is a test that we have done and redone multiple times in our pages, but with a little subtlety. In most of the cases, we are checking that a correct API call is made, with the correct parameters and the correct response. In this case, none of that is necessary because the test for password equality is made client-side. Thus the additional thing that is checked is if no API call is made because none is needed.

The second was chosen because it depicts an use-case that seemed pretty interesting to me, and also because the building blocks of the scenario might be useful in a variety of situations, as, for example, the test for checking if the message disappears after three seconds.

Testing user creation failure because the password is not the same

Let’s talk about the first test scenario.

Given The server is started
And API call response for "user creation should not be called" is mocked
When I visit the index page
And All inputs are filled
And I modify the password field
And I try to create the user
Then I see the message about "Passwords don't match."

The idea for this test is to both verify that there is no API call that is made to the user API, and also that there is a message saying that passwords don't match.

To verify that there is no API call that is made, we can make a route to the user API without actually creating a response, but only by throwing an error.

cy.route({
   method: "POST",
   url: userAPI,
   onRequest: () => {
       throw new Error("This should have not been called");
   }
});

In order to verify that everything works according to plan, we visit the page.

cy.visit(url);

After that, we fill all inputs with information.

cy.get("input").eq(0).type("walter.bates");
cy.get("input").eq(1).type("bpm");
cy.get("input").eq(2).type("bpm");
cy.get("input").eq(3).type("Walter");
cy.get("input").eq(4).type("Bates");

Followed by modifying the password to not match the confirm password value.

cy.get("input").eq(1).type("incorrect");

And the last action on the page being that of creating the user.

cy.contains("button", "Create").click();

After we have setup this specific situation, we want to test that the "Passwords don't match." message is present on the page.

cy.contains("p", message).should("be.visible");

After launching the test runner, we can see that the test is executed and is successful.

Testing the loader being displayed while the user is being created

The scenario for this test is based on the display of a loader and checking that it disappears after five seconds.

Given The server is started
And API call response for "user created after delay" is mocked
When I visit the index page
And All inputs are filled
And I try to create the user
Then The loader is shown
When I wait for 5000 delay
Then I see the message about "User successfully created."
And The loader is not shown

As you can see, some parts of this test are the same as in the first test. The main things that are different are the definition of the API mock, checking that the loader is shown, waiting for 5 seconds and checking the end-state of the page.

Mocking the API response after 5 seconds lets us have a moment during which the response has not arrived from the user API and thus the loading would be shown.

The response is the same as the one that you would get from the Portal, which lets us be very close to reality.

cy.fixture("json/userCreatedResponse.json").as("userCreated");
cy.route({
   method: "POST",
   url: userAPI,
   delay: 5000,
   response: "@userCreated"
}).as("userCreatedRoute");

While the user is created, we verify that the loader is shown.

cy.get(".glyphicon.glyphicon-cog.gly-spin").should("be.visible");
cy.contains("p", "Creating user.").should("be.visible");

After which we wait for 5 seconds.

cy.wait(time);

And after 5 seconds, when the response arrives, we check that the message disappears.

cy.get(".glyphicon.glyphicon-cog.gly-spin").should("not.be.visible");
cy.contains("p", "Creating user.").should("not.be.visible");

As you can see, these tests don't take a long time to write and can be very powerful.
Awesome! Now you know how to test a UI Designer page with Cypress! You can also check our web-pages project containing pages that we are currently developing.