Nationalities Lookup Form

Because the Nationalities table is simple, and of finite size i.e. there are 195 countries in the world, then this is a good choice for the first ReST API to integrate for CRUD operations.

We know from the ReST API what the end points and associated security keys we need to get started. We will always start by reading the data, then displaying it, before moving on to editing, creating and finally deleting data.

Custom Variables for Security Keys

Interestingly, the first thing to do is NOT to start creating data sources. This is because the data sources will require security credentials, and the best place to store these is in server-side custom variables which will not be remoted to the client when executing requests securely on the server.

Custom Variables Configurator

Open App Studio, then open the custom variables configurator.

Select Server in the drop down combo, then click the Add button to create a variable:

The New Server Custom Variable popup modal form will open:

Name

Give this variable a name easily recognisable i.e. in this case we will call it restdbio-football-API-Key as this is descriptive and unambiguous. We know it relates to a restdb.io ReST API and the sample models football and the security key is an API key.

Value

The value assigned to the variable is the key generated in the restdb.io database API tab shown on this page.

Save

Save the variable to create it and it will be displayed in the grid:

Custom Variables for Key Fields

Data source requests will return a data table of rows with fields. Each row will typically have an identifier for example in this sample the Nationality ID. This will be a long random string of characters or numbers generated by the back-end database when records are created.

In order to handle the selection of rows, we need to create a custom variable which will be dynamically set when the end-user selects a specific record in a form or a grid or a field. We will assign this variable to the key field in the data source request.

Because we know that the restdb.io Rest API request will return nationalities, we will create a custom variable called "Nationality-ID" which we will assign to the field later.

Add Nationality-ID

Select the Client in the drop down this time before using the Add button to create the custom variable "Nationality-ID:

We do not need any more custom variables to display and select nationalities in the lookup form, however we will when we need to design a data entry form in order to map fields to the ReST API body.

Read List

The next thing is to create the data source request to integrate the list of nationalities pulled from the ReST API.

Data Source Configurator

Open App Studio, then open the data source configurator.

Create a data source, and a sub-folder hierarchy like this:

This unambiguously defines that we have a restdb.io data source inside which we have the Football industry depicted as a folder. We then define a sub folder for Nationality which will be where all the CRUD request methods for nationalities will be created.

Security

Before creating and testing requests, we need to set the security at the correct level in this folder hierarchy. Specifying this at the restdb.io data source is not correct because we may have other databases with different security keys. Because each restdb.io database has its own security key, then the place to specify security is the Football folder.

Click on the Football folder and click inside the Authorisation tab:

Set the Authorisation to be "API Keys", and Add To to "Header". This is because restdb.io expects an API key as a header.

Now click the Add API Key button. This will create a blank row beneath:

We know from this restdb.io documentation that the API Key is a header called x-apikey so we type this into the Key text box.

We have already created a centralised custom variable which lives securely on the server, so we will use that as the value. This is done by clicking inside the Value text box then clicking the Insert Variable button:

This will popup the Insert a Custom Variable popup form where we will select the restdbio-football-API-Key variable we created earlier:

Then we click the Select button:

The custom variable is inserted into the Value. We should type something into Description to add clarity if necessary.

Nationality Folder

Now that we have set the API security at the database level, we need to ensure that all requests inherit the same security. This is done by selecting the Nationality folder beneath, clicking into the Authorisation tab and setting the Authorisation drop down combo to "Inherit from parent":

Every data source request we create in this folder will now inherit the security keys specified at the database level.

Create a Data Source Request

We can now create a data source request to read a list of nationalities from the ReST API.

Add Request

Click the add button menu item Request:

This will open up the Add New Request popup form:

Give this a name that describes exactly what it does. Something like "Read a list of Nationalities" is descriptive and unambiguous in the context of the location of the request in the tree hierarchy. Click the Save button to add and select this new request.

Edit Request Properties

The new request properties will look like this:

This will provide a default sample URL endpoint, a unique ID, the name you typed, a default description, and a HTTP Verb (method) defaulting to GET.

Paste in the correct URL from the list of restdb.io ReST API views previously tested in your browser, or using Postman

https://www-football-891b.restdb.io/Nationalities

Send Request

You should now test the request by clicking the Send Request button:

You will be prompted to confirm the URL being requested. Later, when developing filters, you will be able to edit this URL, but for now simply click the Confirm Request URL button:

Results

After the ReST API request has been sent, the Results tab will be selected and the JSON tab will show the first columns:

Scroll down until you see the Data Table:

We can see that the actual data from the ReST API is being returned, including the nation flags as URL images. This is because our restdb.io view is able to map its media files onto a two-dimensional table for easy consumption by client-side applications.

Fields

If we scroll back up to the top and click the left Fields tab, we should see a list of the fields accompanying the data:

Clicking on the top right Fields tab will show these Available Fields in a vertical list to the left:

Fields can be re-ordered using the left drag icon, or removed using the right delete button.

Selecting any field will show its corresponding properties to the right. Selecting the Nationality field and scrolling down should reveal the sample values:

These are useful to confirm that fields are returning the expected data.

Image URL

When returning images, you should configure the type of field so that it displays correctly in form components such as grids.

Select the FlagUrl field and set it's Type to "Image URL":

Key Field for Drill Down

Another important field to configure is the unique identifier or "Key" field. This is usually a long random unique string or number. We need to set the ID field to be the Key as well as assign it to the custom variable we created earlier:

This facilitates a process known as 'drill-down' where the end-user selected a hyperlinked column in a row and drills down into it by opening up the data entry form.

Note that we can now simply close the the data source configurator form as all changes are automatically persisted so we can move onto creating the lookup form.

Nationalities Lookup Form

Now that we have the custom variables and data source request to facilitate listing nationalities, we need to create a lookup form upon which to display a grid showing all nationalities.

Create Form

Open App Studio then select the Forms configurator.

Add

Use the Add button to create a new form called "Nationalities" or "Nationality Lookup". In the form properties, make sure that this form is of type "Lookup". You do not need to assign a data source to the form as we will do this in the form designer when we add a Grid component.

Design

Open form designer from the form properties popup, and drag a grid component into the first panel on the Main Top Region tab so that it looks like this:

Click on the Grid to open the component properties for the grid. Select the Data Sources tab:

Use the Add button to select the data source request you created above.

After selection, the Read data source request should appear like this:

Grid Configuration

Select the Grid tab to configure the grid to display the data.

Population

In the Population left tab, set the Population Trigger to Form Loaded. This tells the grid to load the data as soon as the form is displayed.

Columns

In the Columns left tab, the fields previously retrieved from the ReST API are displayed in the order you designed. You can re-order these by using the up/down arrows or delete a column.

Note that in the world of data, the term field is used, yet in grids, the word column is used. This is why the grid uses the column nomenclature instead of field.

Note that the ID key column is showing the custom variable you assigned to it previously.

For the FlagUrl column, this should remember that it was configured as a Image URL Type. Set the Image Size to be 24 x 24 so that it looks the correct size when displayed in the grid:

Also set the Caption, Visibility and Width of the FlagUrl column:

Hide the Flag and ID columns as these need not be shown to the end-user.

Drill Down

We will not configure the drill down tab until after we have created the data entry form in the next section.

Apply

Apply the grid properties, then Save the form design to persist the form for later use.

Navigation Bar

We can now add this lookup form to the navigation bar from where it can be opened by the end-user.

Open App Studio then select the Navigation Bar configurator.

Football Industry

Create a group called "Football Industry" using the Add Group button.

Nationalities

When the Football Industry group is selected, add a form using the Add Form button. This will popup a modal dialogue where you can select your newly created Nationalities form. Clicking Save will show the new Nationalities form menu:

Select Visible, and change the Icon to a globe. Then press the Apply & Close button.

Test

You can now test your configuration by opening the Football Industry group in the navigation bar and selecting the Nationalities item.

You should now see the lookup form with the data from the ReST API displayed in a grid.

Test that column filtering and sorting works as expected.

We are now ready to move to the next step to create a data entry form configured for creating, reading, updating and deleting nationality records.