User Interface

User Interface
Thursday, October 6, 2016PrintSubscribe
Dealing with Duplicates in Lookups

Fields configured with Lookup, Auto Complete, and Drop Down List item styles allow the user to type in a value and display a list of results. The text displayed in the results is configured via the Data Text Field property. Users can quickly enter a search term and find the field value they are looking for using lookups.

However, it is possible that the text displayed in the results can be non-unique. For example, there may be multiple customers with the same name, but from different locations. How can the user determine which value to select?

If multiple fields are borrowed from the lookup controller, the user interface will display these borrowed values in order to help the user determine the correct option. The example below shows duplicate customers displayed in a lookup of type “DropDownList”.

Duplicate customers will show the city and country of the customer in the drop down list.

Let’s borrow the City and Country fields from the Customers table into Orders form in the sample Northwind project.

Start the app generator, click on the project name, and press “Model”. Select “Orders” model from the list.

Editing the Orders data model.

Check the box next to “City” and “Country” columns in the Customers table.

Including City and Country fields in the Orders model.

Press “Save” to save the model. Then, press “Finish”, and confirm the popup to refresh the project. Then, press “Generate” to regenerate the app.

Navigate to the Orders page, and create a new record. Notice that the two new fields are displayed as read-only in the form. Enter a duplicate customer name, and the City and Country will be displayed next to the duplicate values.

Duplicate customers will show the city and country of the customer in the lookup results.

Selecting one of the customers will populate the Company Name in the lookup input, and copy the City and Country in the following borrowed fields.

Selecting a customer in New Orders form will copy the City and Country values.

This feature is automatically enabled when duplicate values are detected. The fields defined in the Copy property of the lookup field will be used. If duplicates are a common occurrence on a particular lookup, it is recommended to use a different display value, or create a calculated field in the lookup controller that can be specified as the Data Text Field. The full lookup grid can also be viewed by activating the arrow icon next to the field.

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.

Thursday, September 22, 2016PrintSubscribe
Adding a Google Maps API Key

An API key must be added to the project to use any features that depend on the Google Maps API, such as Maps presentation style, Geocode feature, or CalculateDistance() business rule method. The Google Maps API Key can be acquired here. Make sure to log into your Google account, and press the “GET A KEY” button to get started.

The button to acquire a Google Maps API key.

Once a key has been acquired, start the app generator. Click on the project name, and press Settings. Then, select Features page of the Project Wizard.

Navigating to the Features page of the Project Wizard.

Switch to the Touch UI section. If you have an API key, under “key=” plus the key in the “Google Maps API Identifier” box. If you have a client ID, enter “client=” plus the client ID in the box.

Entering the Maps API Identifier.

Press Next, and proceed to generate the application. The key will be embedded in “web.config” file of the generated application.

The API key can be accessed from any custom code or code business rules via the “ApplicationServices.MapsApiIdentifier” property. It can also be accessed from JavaScript business rules via the “__settings.mapApiIdentifier” property.

It is highly recommended to restrict access to your key to specific websites, IP address, or apps from the Google Developer Console.

Continue to Show Action Buttons