Nationality Form: Read

This is the process we will follow.

READ

• Add a 'read' data source for reading a single nationality record

• Link the key nationality record identifier to this ReST API end-point if necessary

• Create a data entry form

• Assign this 'read' data source to the data entry form

• Design this form and drag fields from this data source

• Add this form to the navigation bar

• Configure drill down to the lookup form grid component

• Test that we can lookup nationalities and drill down into a data entry form showing the nationality master record

• Set the History Menu record summary

• Test that we can lookup nationalities and drill down into the nationality form, and that the history menu shows the nation

• Add a master/detail grid to show all footballers who represent this nation

• Test that we can view all footballers who belong to this nation

Add a READ Data Source

Open App Studio, open the Data Sources configurator, select the Nationality folder you created previously, then use the add button menu to create a new request:

The Add New Request modal popup form shows asking you to name the request:

Type a meaningful name such as "Read a Nationality" and click Save.

The request will be added to your tree view beneath the Nationality folder:

Edit Properties

Edit the properties in the Details tab as following by referencing this list of ReST API end-points.

URL

https://restdb.trisys.co.uk/ReadNationality

Now it is known from the documentation that this ReST API end-point has a nationality identifier property ?ID=.

We therefore type this parameter list into the URL so that it reads:

https://restdb.trisys.co.uk/ReadNationality?ID=

Whilst the caret is still blinking after the last character typed, click on the Insert Variable button:

This will open the following modal popup for where you should select the Nationality-ID custom variable you created previously in the Variable drop down list . Click the Select button.

The URL should now show the custom variable appended to the end:

HTTP Verb

The default GET verb/method is usually correct for reading a single record from a ReST API and is correct for this specific back-end end-point.

Authorisation

Previously we set up security credentials at the Football folder level, so we can leave this to be set to "Inherit from parent".

We do not need to change anything else.

Send Request

Click this button on the Details tab to send the request to the ReST API.

You will be prompted to confirm the URL:

The value of the custom variable Nationality-ID should show after ?ID= but if it does not, then copy this value in: 67f7cb8278badf650004fb6b as this is the ID for English.

This URL should now be:

https://restdb.trisys.co.uk/ReadNationality?ID=67f7cb8278badf650004fb6b

Press the Confirm Request URL button.

The request should run quickly and select the Results tab and show the JSON top left tab displaying the full JSON returned from the ReST API:

{
    "Columns": [
        {
            "field": "ID",
            "title": "Id",
            "type": "string",
            "format": null,
            "width": 70,
            "hidden": false,
            "template": null
        },
        {
            "field": "Nationality",
            "title": "Nationality",
            "type": "string",
            "format": null,
            "width": 200,
            "hidden": false,
            "template": null
        },
        {
            "field": "Country",
            "title": "Country",
            "type": "string",
            "format": null,
            "width": 200,
            "hidden": false,
            "template": null
        },
        {
            "field": "Flag",
            "title": "Flag",
            "type": "string",
            "format": null,
            "width": 200,
            "hidden": false,
            "template": null
        },
        {
            "field": "FlagUrl",
            "title": "Flagurl",
            "type": "string",
            "format": null,
            "width": 70,
            "hidden": false,
            "template": "<img src='#: FlagUrl #' style='width: 64px; height: 64px;' />"
        }
    ],
    "DataTable": {
        "List": [
            {
                "ID": "67f7cb8278badf650004fb6b",
                "Nationality": "English",
                "Country": "England",
                "Flag": "67fa336b78badf6500054bea",
                "FlagUrl": "https://football-891b.restdb.io/media/67fa336b78badf6500054bea"
            }
        ],
        "DynamicColumns": null,
        "TotalRecordCount": 0,
        "TotalPageCount": 0,
        "FirstRowNumber": 0,
        "LastRowNumber": 0,
        "PageNumber": 1,
        "RecordsPerPage": 1,
        "SortColumnName": null,
        "SortAscending": true,
        "AICriteria": null,
        "Success": false,
        "ErrorMessage": null
    },
    "URL": "https://restdb.trisys.co.uk/ReadNationality?ID=67f7cb8278badf650004fb6b",
    "Verb": "GET",
    "Success": true,
    "ErrorMessage": null
}

Look at the DataTable -> List to see that it contains 1 nationality record.

Our data source request has now been created and configured, so we can now close this configurator.

Create a Data Entry Form

Open App Studio, then open the Forms configurator.

Add

Click the Add button to open the modal popup form:

Name

Type the name "Nationality". You do not need the word "Form" to follow it, despite your initial instinct.

Purpose

Type "Nationality CRUD form."

Type

This must be set to "Data Entry".

Icon

Use the far right button to choose a suitable icon for the form. Use the text "glob" in the filter to find mother Earth.

Caption

Set the caption to "Nationality". Note that we will configure the history menu to show the nationality, not this caption.

Description

The description will be automatically generated which is fine for now.

Data Sources

Click the Data Sources tab as this is where we will add the READ data source we created earlier:

There are 4 CRUD data source lines. Click this database icon for the Read data source:

This modal popup form appears to allow you to select the previously created data source request. Navigate through the folder hierarchy until you locate this data source request:

Click the Select button to choose this data source.

The popup will close and the selected Read data source request is now added to the list of data sources for this data entry form:

If you ever need to remove a data source request from the list, you can use this button:

It is recommended that you now click the Apply button on this form, in order to persist the form properties before designing your form. Your new form should now appear in the list of forms, and the Read data source request you added should be shown in the properties list:

Form Design

Click one of the Edit buttons, either the grid row or properties panel. The form modal popup will display. Click the Design button:

The form designer will open:

Tabs

The tabs toolbar is the selected tool by default. Each data entry form is designed as a master/detail meaning that the master record is shown at the top, and any further details about linked entities is shown below in a series of tabs like this:

The Main Top Region refers to the master record on the top of the form.

We will design the nationality fields in this region.

Preview

The concept of form rows, columns and panels was introduced here, so we will now take a look at what the default data entry form looks like without any fields by clicking the Preview button to show this drop down menu:

We can see the Nationality form and the master panel at the top of the form, and the First Tab (detail) beneath:

Click the Edit Mode button to return to the form designer editor.

Edit Panel

Click the down arrow in the Row 1, Column 1 panel and choose the Edit Panel option:

This opens this modal popup:

For this simple form, we will hide the title and border by unchecking these properties:

Click the Apply button.

Fields

Click on the fields panel in the toolbar to show the available fields. These fields are those connected to the Read data source request we added earlier:

Drag these fields into the form design panel, and preview how it looks:

Configure Layout

We want to show the nation flag on the form, so we will configure the layout to create another column to the right of these fields to span the 3 rows we created. Click this button:

This will open this modal popup to modify the form tab layout:

Use the up arrow on the Columns field to increase the number of columns to 2, then set the first column width to 7 and the second to 5:

Then click the Apply button to apply the layout to the form design. Your form should look like this:

Nation Flag

Click the drop down menu on the right panel to edit it, and make the following changes in the modal popup:

We set the title of the panel to "National Flag", set the icon to be a flag. Click the Apply button.

Now we will drag the Flag field into this panel and hide its label:

Save Form

Now save the form design using this button:

We have now completed the design of our data entry form to read a record.

We will now add this to the navigation bar.

Navigation Bar

When we add this form to the navigation bar, we will be able to test it.

Open App Studio and select the Navigation Bar configurator and select the Football Industry folder you created previously.

Add Form

Click the Add Form button to open this modal popup where you should select the Nationality form you created earlier:

Click the Save button which will close the popup and show the new form in the nav bar menu:

Properties

Check or set these properties:

Visible

Because this is a data entry form, we only want it to be visible in the nav bar when the form is open and showing a record, so this should be unchecked.

Entity Form

This is a data entry form which models entities, so this should be checked.

Apply & Close

Click the Apply & Close button to persist the navigation bar and refresh the nav bar.

Configure Drill Down

The navigation bar should not show any change from the last time you saw it because the Nationality form will only appear on it when the form is opened.

In order to test this data entry form, we need to enable drill down from the nationalities lookup form we created previously.

Configure Grid Component

Open App Studio and select the Forms configurator.

Open Nationalities Form Designer

Open the nationalities form in form designer by choosing Edit then Design.

Click on the Grid component to open this modal popup form:

Select the Grid tab and click the Drill Down left menu option. Click the Add button which will open this modal popup:

Choose Nationality as the Column Name.

Make sure that the Hyperlink is checked.

Ensure that Key Column Name is the ID i.e. the identifier of the nationality record.

Select the Nationality form in the Form field. This is the data entry form we created earlier.

Click the Save button which will close the popup and show the drill down hyperlink details:

You should add another hyperlink to the Country column so that both of these columns can now be used to drill down into the data entry form:

Click the Apply button, and then Save the form design.

Test Data Entry Form

Open the Football Industry group on the navigation bar.

Nationalities

Click the Nationalities nav bar menu to open the lookup form:

If you hover your mouse over any of the nationalities or countries, you should see that it becomes highlighted. This proves that the drill down configuration has been applied.

Click any nationality or country.

Nationality Form

The nationality form should open and show the selected nation details including their flag:

Notice also how the navigation bar now shows the Nationality form as being open?

History Menu

When the history menu appears, we want the name of the nationality to appear, not the name of the form for example:

Configuring Record Summary

Open App Studio and select the Forms configurator. Edit the properties of the Nationality form and click the History Menu tab:

Click this button to open this modal popup:

Choose the Nationality field and click the Save button to persist this setting and close the popup.

Record Summary

The record summary should now show {Nationality} indicating that the Nationality field will be displayed in the History Menu:

Apply

Click the Apply button to persist this.

Test Record Summary

Open another nationality from the nationality lookup form, and then click on the History drop down menu. You should see the last nationality you opened at the top of the list?

National Team Players

We will now design the nationality form and add a grid component to the first tab.

Open App Studio and select the Forms configurator.

Open Nationality Form Designer

Open the Nationality form in form designer by choosing Edit then Design.

Edit Tabs

Select the Tabs panel in the Tools panel:

Edit Tab

Click this button:

This will open up this modal popup to edit the tab properties:

Set the Caption to say "National Team Players".

Set the Icon to a ball using the filter "ball".

Check Selected, Visible and Enabled.

Click the Apply button to save the properties and close the popup.

The selected tab should now reflect the changes:

Add a Grid Component

Open the Components panel and drag a Grid into the panel:

After dragging and dropping, the grid should be visible:

We cannot configure the grid yet because we have not yet created a data source to show a list of footballers.

Instead, we need to Save the form design to persist our design.

Add a Footballers Data Source Request

In order to display a list of footballers on our Nationality form, we need to create a data source request connected to the appropriate ReST API.

Thinking ahead about what we'd like to do with this list of footballers, we'd certainly want to drill down into a footballer form when we get that far, so we ought to create a custom variable to be able to bind it to the unique key identifier.

We will do that first.

Create Custom Variable: Footballer-ID

Open the App Studio, then the Custom Variables configurator, and add the client-side custom variable called Footballer-ID.

We will use this when creating the footballers data source request.

Players Folder

Open App Studio, open the Data Sources configurator, select the Football folder you created previously, then use the add button menu to create a new folder called "Players":

Footballers Request

Use the Add button menu to create a new request called "Footballers":

Paste in this URL which is defined in the ReST API we are integrating:

https://football-891b.restdb.io/views/ReadFootballers

The Authorisation should always default to "Inherit from parent".

Send Request

To get the list of fields, use this button to send the request and get the list of fields and data. We can see that there is a field we can use to identify the nationality by its unique identifier:

Parameters

Because we want this data source request to be re-used throughout the application, we are going to use optional parameters linked to custom variables. Only if a custom variable value is not empty will it be appended to the URL at run-time.

We previously created the Nationality-ID custom variable and we know that this ReST API can return footballers belonging to a particular nation. Sending the request identified that the NationalityID URL parameter should be the correct URL parameter name.

Click the Add Parameter button to add this parameter:

Select the Field NationalityID, then assign that to the Custom Variable Nationality-ID then click the Save button.

The parameter is added to the list:

Fields

In the list of fields populates when sending the request, locate the ID field, then set this as the Key and assign this custom variable Footballer-ID:

Because we know by inspecting the data returned, we will also make the fields with https data into images for example:

Do the same for these fields:

• PhotoUrl

• TeamBadgeUrl

That's all we need to do at this stage.

Wire up the Footballers Grid

We can now point the grid on the nationality form at this new data source request.

Open App Studio and select the Forms configurator. Open the Nationality form, edit it, and Design it to open the forms designer.

Add Read Data Source

Click on the grid on the National Team Players tab:

This opens the Component Properties: Grid modal popup. Click on the Data Sources tab.

Use the Add button to choose this data source request.

The popup form should now show that a Read data source request is associated with the grid:

Grid Columns

Click on the Grid tab.

Population Trigger

Select "Record Loaded" in the drop down combo:

Columns

Click on the left tab Columns, and order the columns, hiding some, as you would like to see them.

Because this grid is on a nationality form, we do not need to see the nationality column in this grid. Here are the properties for each column you should set:

Drill Down

Leave this for now as until we create the footballer form, we have nothing to drill into!

Apply

Apply the changes to these properties.

Save

Save the form design to persist the configuration.

Test

You can now test your configuration by opening the Football Industry group in the navigation bar and selecting the Nationalities item. Drill down into any nationality to open the form.

The nationality form now shows the National Team Players in the grid.

We will revisit this form to configure drill-down once we have completed all CRUD configuration and created the footballer forms.