Introduction to App Builder - Lesson 6: Binding

This is the sixth lesson of the Introduction to App Builder tutorial series.

In this lesson, we'll learn about a fundamental concept in App Builder: binding. We'll learn about it as we construct a key page in our Northwinds application.

Pages with multiple panels: The Orders page

All the pages we've built so far have only had one panel. We'll see how we can build pages with multiple panels and how to make them work together using binding.

To start, we'll create a page called Orders.

1. Using the same steps we've followed in previous lessons, create the new Orders page. It should have a full-page panel for now, we'll add more later.

2. Once App Builder creates the page, add a panel of type Grid, using Order (Source) as the panel source. You can let App Builder auto-build the panel, we'll edit the controls in it later. If you visit the page's preview, you'll see that it simply lists all the Orders present in the database.

Now let's add a second panel to the Orders page. Our goal is to have an initial panel listing all orders, but the details of each one being shown in other panels on the same page. That way, when the end user clicks on an order, the other panels automatically change to show details about the selected order.

1. Navigate to the Orders page and click View Page to preview it.

2. Access the live designer.

3. When the live designer opens, click the + Panel button. The Create a Panel dialog opens.

4. Select Grid as the Panel Type and click Next.

5. Select OrderDetail (Source) as the Panel Source and click Next.

6. You can allow App Builder to auto build the panel, we'll edit the controls later. Click Next and Finish.

Because the Order table has a foreign key that connects with the OrderDetail table and the two panels pull data from rules that are based on those two tables, App Builder automatically binds them. This means that now, when you visit the Orders page preview, clicking on an order's row in the Orders panel will make the Order Details panel be automatically populated with details of the order you've selected.

Add a binding manually

When two panels on the same page pull data from rules that have connecting foreign keys, App Builder will automatically bind them. However, if you need to bind two panels manually, this is how you can do that:

1. Navigate to the page with the panels you want to bind.

2. Click the panel you want to automatically populate with details of the user's selections in another panel.

3. In the Panel tab, find the Parent Panel & Binding field.

   1. Use the menu to select the parent panel.

   2. Click the button with the binding symbol. The Binding Columns dialog opens.

   3. Click + Binding and use the menus to select:

      1. Type: The type of binding.

      2. Child Column: Select which column from the child panel's base rule should be the child.

      3. Parent Column: Select which column from the parent panel's base rule should be the parent.

   4. Click the checkmark icon to confirm and exit the window.

Click View Page to preview the Orders page now that it has two panels. To test, try selecting different rows in the parent panel and see how the information in the child panel changes accordingly:

Edit display values

Note that the Order Details panel only shows the unit prices of each item. However, several items were bought in large quantities. In addition, several of them were bought with discounts. Let's modify the panel so it calculates and shows price totals.

1. In App Workbench > Rules, access the OrderDetail (Source) rule and click to edit it. In the Columns tab, click + Column.

2. In order to multiply the unit price by the quantity and subtract the discount, the expression we need is:

   OD.UnitPrice*OD.Quantity*(1-OD.Discount)

3. In the Alias field, enter Line Total. Click Save.

4. In the updated table of columns, use the Logical column to cast the new Line Total field as Currency. Take this opportunity to also cast the Unit Price column as Currency and the Discount column as Percent.

5. Click Results to see the values being displayed. Now go back to the Orders page edit screen and add the new Line Total control to the OrderDetails panel, giving it the name Total. After doing that, revisit the Orders page preview. The OrderDetails panel now shows totals at the end of each row:

   

Now that we have a total for each individual item, let's also add another control to show the total price of an entire order:

1. Go to the Orders page preview and access the live designer.

2. Select the Total control in the Order Details panel to make the live designer show edit options for it.

3. In the Control Properties tab, find the Aggregate Function field, and click Sum.

4. Click Save.

Now the Order Details panel shows the total price for an entire order at the bottom of the Total column:

Make a control read only

We don't want to allow end users to edit all controls on a page. For instance, in the Orders page we're building, we can't allow users to edit the price of an item. Follow these steps:

1. Navigate to the Orders page preview and access the live designer.

2. Click the Unit Price control in the Order Details panel to make the live designer show edit options for it.

3. In the Position & Width tab, find the Edit Options field, and click Read only.

4. Click Save.

When you are returned to the page preview, notice that clicking the edit icon in any of the rows of the Order Details panel no longer lets you edit the Unit Price column.

Orders page improvements

Despite the improvements we've already made, the Orders page still isn't very user friendly. The Orders panel has more controls than what can be read comfortably on the screen, and some important information that end users would like to know cannot be found on the page. Let's keep working on this page.

Shipping Information panel

The Orders panel has too many controls. Take a look at it in the Orders page preview. There are so many controls that they don't fit the screen and it's not possible to comfortably read everything.

To make our application more user-friendly, we'll add more panels to the page to better distribute the information.

1. Navigate to the Orders page edit screen and click + Add Panel.

2. Once it appears, click + Choose Panel Type.

3. This time, the panel type should be Form. The panel source should be Order (Source), same as the main Orders panel. This time, however, opt to Choose Manually the new panel's controls. When the Choose Columns screen appears, select all the columns except OrderNumber and OrderDate.

4. Click Next and Publish.

5. When App Builder refreshes the page, change the new panel's name to Shipping Information and click Save.

App Builder will automatically bind this new panel to the Orders panel using the OrderID column. Now that we have a new panel to display shipping details, the main Orders panel doesn't need to have all those controls anymore. Visit the Orders panel edit screen and reduce the number of controls there, leaving only OrderNumber and OrderDate, the two that aren't also present in the Shipping Information panel.

However, the new Shipping Information panel still has a lot of controls, so we'll organize them a bit better:

1. In the Orders page edit screen, select the Shipping Information panel and click Controls.

2. Looking at all the controls that are available, we can separate them into two groups, so we'll do that. Click + Control.

3. Skip the Column field, because we don't need any new controls, we'll just organize the existing ones. In the Control Type field, select Accordion. In the Name field, enter Shipping Info.

4. Click Next and Finish.

5. Repeat Steps 2 to 4 and create another group called Dates & Cost.

When App Builder returns you to the list of controls, you'll see that the two groups are now listed. Go over all the controls and decide which one of them should go under each group by changing their Parent to be one of the two. By the time you're done and you return to the Orders page preview, the Shipping Information panel should be looking a lot more organized:

Customer Information panel

Let's add another panel to the Orders page, because currently it doesn't show us any information about who placed the orders. It shows us what was bought, but not who bought it.

1. Navigate to the Orders page edit screen and click + Add Panel.

2. Once it appears, click + Choose Panel Type.

3. The panel type should be Form again. The panel source should be Customer (Source), since we want information about who is placing the order. You can let App Builder auto select all controls, because we'll organize them ourselves in the next steps.

4. Click Next and Publish. App Builder will automatically bind this new panel to the main Orders panel using CustomerID as the binding criteria.

5. When App Builder refreshes the page, change the new panel's name to Customer Information and click Save.

6. Now, let's organize the controls in the new panel. Go to its edit screen and click + Control.

7. This time, however, let's pick a different type of organizer. In the Control Type field, select Tab. Give this first tab the name Customer.

8. Repeat Steps 6 and 7 to create another tab with the name Contact.

9. When the new tabs are ready, go over the controls and distribute them into the two tabs. Which controls do you think would fit best under each one? When you're done, revisit the Orders page preview and the Customer Information panel will have the two tabs you created:

   

Use panel groups to organize your page

Even though we were able to use bound panels to divide up the information in our Orders page, we now have a new problem because the four panels are fighting for space in the screen and it's not very legible right now. We'll fix that problem using panel groups, with which we can organize panels on our pages to improve how they look.

1. In the Orders page edit screen, click the Groups button under the Page Panel Layout panel.

2. Click + Group.

3. In the Parent field, select Orders (Page), the page we're building. Give the group the name Top row.

4. In the Layout field, select Side by side.

5. Click the icon to save.

Next, exit out of the group creation dialog and select the Orders panel. We want it on the top row, so in the Panel tab, find the Position property and select Top row in the Parent field. Click Save. We also want the Shipping Information and Customer Information panels in the top row, so repeat the process for them. Use the numbers in the Order field to determine which panel comes first.

Now, create a second group, but this time give it the name Bottom row. It will contain the Order Details panel, which we want to make occupy the whole bottom of the screen. Therefore, make sure that the number in the Order field is bigger than the corresponding field in the first group. Once you create the new group, make sure to assign it as the Parent of the Order Details panel.

Finally, in the Order page edit screen, change the Layout to Stacked. App Builder will then stack the two groups following the numerical order of the two groups. When you refresh the page, the Page Panel Layout should look like this:

And the preview of the Orders page should be looking like this:

What other improvements can you make to the Orders page? For instance, in the screenshot above, we added an Employee control to the Orders panel, so users can see which employee a customer talked to when placing their order. How would you add that control to your Orders panel? Here's a few other ideas for improvements:

• Are all the prices being displayed correctly, as currencies?

• Are all the discounts being shown as percentages?

• How can you add a Category control to the Order Details panel like in the screenshot above?

• Should you allow end users to delete the entries in the Shipping Information and Customer Information panels? How can you prevent them from doing so?

Review and wrap-up

In this lesson, we used the concept of binding to make our pages more responsive and complete. In the next lessons, we'll continue to improve our understanding of development concepts in App Builder. Proceed to Lesson 7: More about rules.