Defining a view for managing orders

We are pretty close to having a complete set of views that do what we need for the basic user stories. We still need to provide some way to interact with the life-cycle of orders -  for example, to move an Order Status from Submitted to In Progress, Complete, or Cancelled.

Overview

As usual, we should think about the design of the view as a whole before we dive in to adding components.  In terms of layout, this one will be a lot simpler: it’s basically a list of orders.  Leon would expect to see the Dish and Restaurant record information brought right into the list. It would also be very nice to also have a list of employees who will be receiving the selected order, case there is a problem with it.

The result might look like this:

Also, we will introduce a new concept here: using a hidden record editor to directly modify the Status of the Order record on the click of a button; we will keep it out-of-sight in its own container at the bottom of the view.  As we have done before, let’s look at the underlying structure of the view diagrammatically:

To build this, the important things to know are that:

• Record grids can be automatically filtered to show associated records only.  You will see this in the employee list. In other words, to implement this, you do not need to worry about database joins or foreign key fields.
• The record grid has a built-in button bar that is automatically exposed whenever there are Action button components there, and only when there is a current selection in that record grid. Otherwise the button bar is not visible and is replaced by standard refresh and filtering controls. All this behavior is completely automatic except that you need to configure the button actions.
• You can hide a record editor in the view (or, more precisely, place a record editor within a container component that is always hidden). Just as when you are using a visible record editor, it can be synchronized with the record grid’s selection.  Effectively this creates a data model in the view’s memory that can be used to invisibly manipulate data.
• An Action button (in this case, placed in the record grid’s button bar) can have multiple actions combined to do useful things in a view. Here, we would like users to be able to instantly update data in the database and record grid. One technique that we will use could be called “push and refresh”.  It consists of the following sequenced actions:
  • Set property—Updates the hidden record editor’s data model as desired, such as setting the Status field value.
  • Save—Asks the hidden record editor to push it’s changed values to the back-end Record Service.
  • Refresh—Ask the visible record grid to refresh, in order to show the updated value instantly and give feedback to the user.

These hints may already be enough information for you to compose the view and compare it with the "finished" screenshot above.  If you become stuck, you could follow the following general steps for the trickier parts.

Start by creating a new view (Container layout) called Orders and give it both permission roles: Order Submitter and Restaurant Manager. Add the Rich text component for the header.

Build out the nested containers structure as shown in the diagram - this is similar to what was done with the Restaurant Details container for the Restaurants View.

Displaying orders

Add the record grid for Order and set Enable row selection to Single row as usual.

The Column configurations are interesting here. As we did in the New Order View, you can bring in columns from Restaurant and Dish because each Order is associated to exactly one of these.  As before, this is a great example of changing the Column header to be meaningful (otherwise, Dish and Restaurant fields that are both called Name will both show up as Name).

Displaying associated employees

For the record grid component for Person, placed in the Container component on the right side, it’s important to specify the Mode as Association and not Record. Once you identify the Record Definition to Show as CTM:People (remember that you will find this using search because it is in the Foundation library), you will then be asked for two additional pieces of configuration:

• The Association to use: select Orders on Behalf of Employee

• The Associated record ID: you will want the ID of the selected row from the Order Record Grid as we did previously to bind a record editor to a grid selection; find this using the Edit Expression dialog.

  Warning

  Important

  If the ID column is not there, go back and add it and make it not Visible.

• Columns: probably all you really need here is something like Full Name and perhaps the Phone Number Home. After all, the most that might happen here is identifying someone here giving them a call. You could also navigate to some UI that shows more information about them, such as their manager, and so on. However it's worth noting here that record grids can only show associated data "two levels deep" (that is, they cannot show associations of your associations).

Instant updates for the order

At this point, the view is functional in terms of displaying Order records, but doesn't allow any modification of them. Now this view is going to get much more interesting - it is going to provide a way to update the Status with the click of a button.

As described earlier, a hidden record editor for Order is needed for the “push and refresh” of status information. After dragging it in to your hidden container, make sure it is in the Edit Mode and Record ID property is pointing to the same selected ID from the order grid. 

Creating the button components to instantly act on a selected Order is a very useful technique, and turns you into a true view designer “power user”. Let’s see the detailed steps to implementing this for one case: setting the Status to In Progress with a click of a button (the other updates are almost identical to implement).  Before we start, let’s review the requirements for this Button. Recall that it needs to

• Instantly update the Status value on the back-end (this will be a combination of Set Property  and Save actions).
• Allow the user to see the updated value of the Status in the record grid (this is a simple Refresh action).

Let’s go through this step-by-step.  

1. Drag an Action button into the built-in button bar at the top of the grid  (If you drag it anywhere else, it will be visible at all times, even when there is no record grid selection.
   
2. Set up the Action button properties the way you like. Although normally a button's Label should be some "action word" (verb), like Update to In Progress, but in this case it might be clear to users enough simply show up as In Progress. The following screenshot also shows the Disabled Condition but you should leave this configuration alone for the moment, until the update behavior is working correctly. - for now just leave that blank.
   
3. Add a Set property action the In Progress button..
   1. This is for changing the in-memory "model" of the Order record to set its Status to In Progress.
   2. The tricky part of this is setting the right Property path expression.  You will need to “find” the right Status element that will be updated, and in a complex view this might take some exploring. You are only specifying the path to the value here, not the new value.
   3. For the Property value itself, choose the new selection value In Progress from the Options under the Status field as shown:
      
4. To actually persist the change, the next action will be a Save on Record editor (Order).  Do not use Close after save here because we aren't in a dialog.
5. Finally, add the Refresh action for Record grid (Order) - this way the updated Status value will be reflected immediately in the record grid.

 

At this point you are ready to try it out, by launching (or refreshing) the preview browser tab.  Select an order that is not in the state of In Progress and use the In Progress button to update it.

A final enhancement to this technique: think about under what conditions the user will be clicking on In Progress. Remember that the purpose of the Action button is to advance the Order record through its life-cycle.  In this case, the life-cycle essentially progresses from Submitted to Closed (or Cancelled); this is one reason that the Status values have numeric equivalents which go from 0 to 40.

Consider the times when should a user see the Action button as enabled. After all, a user should not expect to be marking an Order as In Progress if it has already reached or surpassed that phase of its life-cycle. Letting a user do that could be very confusing. We would like to only enable it conditionally, which is very easy to do in the view configuration without the need to write code.  Here is the solution.

In this case, you will notice that most components have a Disabled property, which is set to Never by default. What we would actually like to is to specify that the In Progress action button should be disabled whenever the selected Order has a Status value of, or numerically higher than, In Progress.  By using the inequality of >=, the logic is less fragile by handling intermediate states because it handles the state "jumping past" the normal sequence. Let’s configure this.

Once you have tested the In Progress Button behavior, use it as a kind of recipe to implement the similar behavior for Delivered and Cancel Buttons.  You can re-use the same hidden record editor for each one, but each action button will need its own actions list and its own Disabled conditional expression.

Once all the buttons have been implemented, to test this more fully, try selecting orders, one at a time, some of which are still in Submitted state, and some in later states.  If we have implemented this correctly, the later states should have the In Progress button as disabled.  The following test cases show each button tested against all the life-cycle states.

These screenshots show exactly the same kind of logic to create "smart" Action Buttons for Delivered (hidden when Status >= "Delivered") and Cancel (hidden when Status >= "Cancelled").  You can re-use the hidden record editor, but just set Status to different values.

No selection:

Submitted state:

In Progress state:

Delivered state:

Cancelled state:

Did it work?

If the Action buttons are not enabled at the right times, or don't seem to have any effect, here are some things to check:

• The Save action is effectively disabled when not all required fields in the Order record have a value. Since we did add some required fields along the way, make sure you have provided missing values, or just remove these older record Instances using the Edit data feature.
• Are you using the correct Property path for the Set property actions? These can be confusing because the individual field components show up as well, such as Status, but we always need to identify the Record Instance itself.
• As mentioned before, the Disabled conditional is not evaluating when to be enabled, but rather when it is the opposite (disabled).  Make sure your logical expression isn't the reverse of what you intended.
• As before, you will find that if there is a Description field in Order that has no default, the Save action will fail.
• Make sure the Refresh actions are pointing to the record grid, not a record editor.

Update the shell

As before, be sure to update the shell of the application to have access to this view.  It should now look something like this:

Challenge

• Set up the filtering of the record grid for the Order records to exclude orders that are Completed (Closed) by default.
• Display a Cancel icon in the Status column from the Order Record grid, and change the Status color to Danger (red) when the Order Status is Cancelled (value 30).
• Display the Special Instructions information for the currently selected order (not just as a column in the record grid). If you want an extra challenge, display the information in a non-default font.
• Build a simple view to display the details of a Restaurant. Launch this view as a centered modal dialog, by clicking on a restaurant's name in the record grid for Order.

What we learned

• Record grid components can include columns from a singly-associated record.
• Record grid components can be constrained to show multiple associated records as rows.
• An easy way to hide components is to put them into a Container that is Hidden -  At all times.
• Container component Name is optional, but a great way of making it easier to find the one you want later on, especially in a complex view.
• Components can have conditional properties, such as Disabled and Hidden.
• An Action button can be configured to do many things, such as an sequence that effectively updates a record in-place.

We have come a long way toward building a complete and useful application, and learned a huge amount of BMC Helix Innovation Studio skills along the way. The data model and UI are completely functional.

Now that we can actually associate data, and easily manipulate the Status of an Order, we should turn our attention into building out the Order Lifecycle Process to implement the required user stories.