Blog: Posts from September, 2016

Posts from September, 2016
Friday, September 30, 2016PrintSubscribe
Displaying Field Values in Category Descriptions

Data fields displayed in forms of applications created with Code On Time are organized in categories. By default, all data fields are rendered top down in a single category. It is possible to use categories to enable the rendering of data fields in multiple columns, tabs, a wizard, or a combination thereof.

Each category is rendered with a bar at the top displaying the header text. When the user presses on the bar, the category will collapse or reveal itself. The categories’ Description property is displayed underneath the collapsible bar. Data fields belonging to the category are rendered in row containers, with the label on the left side, and the input control on the right side.

The Employees page with a multi category layout in two tabs. Field values are displayed in the category description.

Let’s configure the Employees page of the Northwind sample project into multiple categories, and customize the descriptions for each category. We will display the field values in the category descriptions in order to provide context to the user.

Start the Project Designer. In the Project Explorer, switch to the Controllers tab. Double-click on “Employees / Views / editForm1 / c1 – Employees” category node.

Editing c1 category of editForm1 view of Employees controller.

Make the following changes.

Property Value
Header Text Person
Description View the personal information.
Tab Employee

Press OK to save. Next, create a new category by right-clicking “Employees / Views / editForm1” and press New Category.

Creating a new category in 'editForm1' view of Employees controller.

Configure as follows and press OK to save the category.

Property Value
Header Text Hire Info
Description The hiring info is displayed below.
New Column Yes
Tab Employee

Create another category with the following properties. Notice the use of field names wrapped in curly brackets. The text will be updated at runtime with the field values.

Property Value
Header Text Address Info
Description The address of {FirstName} {LastName} is displayed below.
Tab Address

Finally, use drag & drop to reposition the data fields in the correct categories, as shown in the picture below.

The data fields have been repositioned in the correct categories.

On the toolbar, press Browse to generate the application. When the application comes up in your browser, navigate to the Employees page and select a record. Notice that the data fields have been rendered in two tabs, with the first tab displaying two columns. Each category displays the specified category description.

Two tabs are rendered in editForm1 of Employees page, with two columns in the first tab.

Switching to the second tab will display the “Address Info” category. Notice that the fields in curly brackets have been replaced with the field values.

The second tab displays field values in the category description.

Note that the same functionality is available in Desktop user interface.

The Desktop user interface also displays field values in the category description.

In custom form templates, category descriptions can be added by inserting a row container, with a description control inside. Field values can be displayed by using a “field” control marked as read-only.

<div data-container="collapsible" data-header-text="Address Info">
    <div data-container="row">
        <div data-control="description">
            Where does 
            <span data-control="field" data-field="FirstName" data-read-only="true"></span>
            <span data-control="field" data-field="LastName" data-read-only="true"></span>
            live ?
Monday, September 26, 2016PrintSubscribe
Conditional Visibility in View Templates

Conditional visibility on data fields and categories allows hiding or showing page elements based on field values. View templates give the ability to define custom presentations. When a custom template is defined for the view, the client library is not able to determine which page elements should be displayed or hidden based on the conditional visibility expressions. As such, the creator of view templates must mark up the template in order to bind these expressions with the correct elements.

When the template has been correctly defined, data fields, categories, and even custom page elements will be able to displayed or hidden depending on field values. For example, a large label is displayed in the sample below when the order has been shipped past the required date.

Warning displayed in New Order form conditionally.

Let’s use the create form for Orders in the Northwind sample database.

Arranging Data Fields into Categories

First, let’s rearrange the data fields into multiple categories, in order to control visibility of each category, instead of each individual data field. The user will only be able to enter shipping information if a shipped date is assigned.

Start the Project Designer. In the Project Explorer, switch to the Controllers tab. Right-click on “Orders / createForm1” view node, and press New Category.

Creating a new category for "createForm1" view of Orders controller.

Define the following settings:

Property Value
Header Text Ship Info
Visible When
$row.ShippedDate != null

Press OK to save the category. Next, drag data fields ShipVia, Freight, ShipName, ShipAddress, ShipCity, ShipRegion, ShipPostalCode, and ShipCountry into the new category.

Dragging shipping fields onto the second category in Orders.     Data fields have been separated into two categories in "createForm1" view of Orders controller.

Adding Data Field Visibility

Users should not be able to set the shipped date until the order date has been set. Let’s add a data field conditional visibility expression to ShippedDate data field.

Double-click on “Orders / Views / createForm1 / c1 – New Orders / ShippedDate” data field node.

Selecting ShippedDate data field in Orders controller.

Make the following change:

Property Value
Visible When
$row.OrderDate != null

Press OK to save the data field.

Adding the View Template

Let’s add a custom view template for editForm1 of Orders controller.

On the toolbar, press Develop to open the project in Visual Studio. In the Solution Explorer, right-click on the “WebSite” node and press “Add / New Folder”.

Adding a new folder to the project

Give this new folder the name “Views”. Next, right-click on the folder and press “Add / HTML Page”.

Adding a new HTML page to the Views folder.

Give this page the name “Orders.createForm1.html”. Replace the contents of the file with the following:

<div data-container="collapsible" data-header-text="New Order">
    <div data-container="row">
        <div data-control="description">Enter new order information below.</div>
    <div data-container="row">
        <div data-control="label" data-field="CustomerID">CustomerID</div>
        <div data-control="field" data-field="CustomerID">CustomerID</div>
    <div data-container="row">
        <div data-control="label" data-field="EmployeeID">EmployeeID</div>
        <div data-control="field" data-field="EmployeeID">EmployeeID</div>
    <div data-container="row">
        <div data-control="label" data-field="OrderDate">OrderDate</div>
        <div data-control="field" data-field="OrderDate">OrderDate</div>
    <div data-container="row">
        <div data-control="label" data-field="RequiredDate">RequiredDate</div>
        <div data-control="field" data-field="RequiredDate">RequiredDate</div>
    <div data-container="row" data-visibility="f:ShippedDate">
        <div data-control="label" data-field="ShippedDate">ShippedDate</div>
        <div data-control="field" data-field="ShippedDate">ShippedDate</div>
    <div data-container="row" data-visible-when="$row.RequiredDate < $row.ShippedDate">
        <h3 style="color:red">WARNING: THIS ORDER HAS BEEN SHIPPED LATE</h3>
<div data-container="collapsible" data-header-text="Ship Info" data-visibility="c:c2">
    <div data-container="row">
        <div data-control="description">Enter shipping information below.</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipVia">ShipVia</div>
        <div data-control="field" data-field="ShipVia">ShipVia</div>
    <div data-container="row">
        <div data-control="label" data-field="Freight">Freight</div>
        <div data-control="field" data-field="Freight">Freight</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipName">ShipName</div>
        <div data-control="field" data-field="ShipName">ShipName</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipAddress">ShipAddress</div>
        <div data-control="field" data-field="ShipAddress">ShipAddress</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipCity">ShipCity</div>
        <div data-control="field" data-field="ShipCity">ShipCity</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipRegion">ShipRegion</div>
        <div data-control="field" data-field="ShipRegion">ShipRegion</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipPostalCode">ShipPostalCode</div>
        <div data-control="field" data-field="ShipPostalCode">ShipPostalCode</div>
    <div data-container="row">
        <div data-control="label" data-field="ShipCountry">ShipCountry</div>
        <div data-control="field" data-field="ShipCountry">ShipCountry</div>

Notice that there are three highlighted pieces in the sample above.

The yellow highlight shows how to apply data field-level visibility to an element by using the attribute “data-visibility”, and setting the value to “f:” followed by the name of the field. This will inherit the visibility from the field “ShippedDate”.

The green highlight shows how to apply category-level visibility to an element. Use the attribute “data-visibility”, and set the value to “c:” followed by the category ID. The example will inherit visibility from the category “c2”.

The orange highlight shows how to use custom JavaScript expressions to set visibility. Use the attribute “data-visible-when”, and set the value to your JavaScript visibility expression.

Switch back to the browser, navigate to the Orders page, and create a new order. Notice that the OrderDate data field, custom header, and shipping category are hidden.

When Order Date is not set, ShippedDate and ship info are hidden.

Enter a value for Order Date. Notice that the Shipped Date data field will appear.

The ShippedDate data field appears when OrderDate is set.

Enter a value for Shipped Date. The Ship Info category will appear.

Ship Info category appears when Shipped Date is set.

If the Shipped Date is after the Required Date, the warning text will appear.

A warning appears when the Shipped Date is after the Required Date.

Friday, September 23, 2016PrintSubscribe
Calculating Driving Distance Between Points

In businesses that require a lot of driving and tracking packages, it is invaluable to estimate a driving distance between two different addresses or sets of latitude/longitude. Starting in release, C# and Visual Basic business rules now have access to the CalculateDistance() method. This method will query the Google Distance Matrix API to estimate driving distance.

The results from the CalculateDistance() business rule method displayed in a messsage.

It is required to obtain and add a Maps API Identifier to your project in order to use this feature.

Please make sure to follow Google Maps APIs Terms Of Service. Of note is section 10.5.d, which restricts long-term storage of Content.

Let’s add a custom action to the Employees page that, when pressed, will display how far the employee lives from the main office using a code business rule.

First, we need to add an action that will be accessible to the user in order to trigger the code.

Start the Project Designer. In the Project Explorer, switch to the Controllers tab. Right-click on “Employees / Actions / ag1 (Grid)” node, and press New Action.

Adding an action to grid scope of Employees controller.

Enter the following settings:

Property Value
Command Name Custom
Command Argument DistanceFromHQ
Header Text Distance From HQ
When Key Selected Yes

Press OK to save. Next, let’s create a business rule that will be triggered when the user presses the action. Right-click on “Employees / Business Rules”, and press New Business Rule.

Adding a business rule to Employees controller.

Enter the following properties:

Property Value
Type C# / Visual Basic
Command Name Custom
Command Argument DistanceFromHQ
Phase Execute

Press OK to save the business rule. On the toolbar, press Browse to generate the application and create the rule file.

When generation is complete, press “Edit Rule” on the action bar to open the file in Visual Studio.

Editing the rule in Visual Studio.

Replace the contents with the following:


using System.Data;
using MyCompany.Data;
using MyCompany.Models;

namespace MyCompany.Rules
    public partial class EmployeesBusinessRules : MyCompany.Data.BusinessRules
        /// <summary>
        /// This method will execute in any view for an action
        /// with a command name that matches "Custom" 
        /// and argument that matches "DistanceFromHQ".
        /// </summary>
        public void r100Implementation(EmployeesModel instance)
            // combine address pieces with ","
            string sourceAddress = string.Join(",", instance.Address, instance.City,
                instance.Region, instance.PostalCode, instance.Country);
            string destinationAddress = "1 Microsoft Way,Redmond,Washington";

            // get distance and calculate miles
            decimal meters = CalculateDistance(sourceAddress, destinationAddress);
            decimal miles = meters * 0.00062137m;

            // show result
            if (meters == 0)
                Result.ShowAlert("No path found.");
                Result.ShowAlert("Distance from HQ is " + meters 
                    + " meters, or " + miles + " miles");

Visual Basic:

Imports MyCompany.Data
Imports MyCompany.Models

Namespace MyCompany.Rules
    Partial Public Class EmployeesBusinessRules
        Inherits MyCompany.Data.BusinessRules

        ''' <summary>
        ''' This method will execute in any view for an action
        ''' with a command name that matches "Custom" 
        ''' and argument that matches "DistanceFromHQ".
        ''' </summary>
        Public Sub r100Implementation(ByVal instance As EmployeesModel)
            ' combine address pieces with ","
            Dim sourceAddress = String.Join(",", instance.Address, instance.City,
                    instance.Region, instance.PostalCode, instance.Country)
            Dim destinationAddress = "1 Microsoft Way,Redmond,Washington"

            ' get distance and calculate miles
            Dim meters = CalculateDistance(sourceAddress, destinationAddress)
            Dim miles = meters * 0.00062137D

            ' show result
            If (meters = 0) Then
                Result.ShowAlert("No path found.")
                Result.ShowAlert("Distance from HQ is " & meters &
                                 " meters, or " & miles & " miles")
            End If
        End Sub
    End Class
End Namespace

Switch back to the web browser, and press the three dot menu button next to any row to reveal the grid action menu.

Activating the grid scope menu for a row in Touch UI.

Press “Distance From HQ” action, and a message box will display the distance.

The results from the CalculateDistance() business rule method displayed in a messsage.

Note that it is also possible to pass a latitude and longitude by separating the values with a comma, such as in the following example:

CalculateDistance(instance.Latitude + "," + instance.Longitude, destinationAddress)
Continue to Geocoding