Tutorials

Part 2: Searching & Displaying Data

Prefer to watch rather than read? There’s a video version of this tutorial in our Videos section – you can find it hereGo to the video.

In the first part of this tutorial, we started building the first screen of a simple Address Book app, and a database table to store our contacts, before wiring them together into a fully working prototype.

Log into your Nutshell instance, and in the main navigation across the top, click on the Apps manager to see a list of all your apps.

If you’ve completed the first part of this tutorial, you’ll have a folder already setup called “Tutorials”. If this is the case, open-up the Address Book app in the Nutshell builder.

If you haven’t, now would be a good time to go back and complete the first part of this tutorial, as this one picks-up where that one left-off.

When we finished the last tutorial, we’d created a simple data capture form and a database table. We’d then used the Data component to create a new record from the data captured in the form. This was the start of a simple Address Book app.

How our Address Book app looked at the end of the last tutorial

In this tutorial, we’re going to create a new screen that will display a list of contacts in our Address Book, and provide a simple search tool, allowing our end-user to find a contact either by Name or Email address.

Why not Preview your app now, and create a few contacts, so that there’s something to display in the list. The next step will be to add the screen that will contain the list of contacts.

Change the toolbar to Essentials and drag a new Screen component onto the canvas. For now, place it directly below the Add Contact screen, like this:

Position your new screen immediately below the Add Contact screen

Label your new screen “Contacts List” and add a title of “Address Book” to the top, using the Text component. It should look something like this:

This will be the main screen of our Address Book, so the title should reflect this

Now all we need is a table in which to display our list of contacts. Change the toolbar to Visuals and you’ll see a component called Data Table. This component allows us to take a bunch of data from a given data-source and display in a table. Drag it to your screen.

Drag a Data Table component on to your new screen

It’s blank to begin with, as we haven’t set-up any columns yet. We’ll do that in a moment.

For now, set its Reference to “List of Contacts” – this will become important later when we map which database fields should be inserted into which columns. Speaking of which, let’s set our columns up now.

Further down the Properties panel you’ll see a box into which you can add your columns. It may be empty to begin with, but you can use the little + button to add columns quickly. You could add as many columns as you like, but we want to keep this simple, so to begin with, our table is only going to show the contact’s name.

Use the little + button under the box to add a new column and set both its Column Name and its Reference to “Name”. Save your changes, and you’ll see the table update on-screen with some dummy placeholder data to show you what it’ll look like once it’s populated.

Add the Name column in the Properties panel

Now, we need to decide how we want the table to behave under different circumstances. Expand the Behaviour Settings section further down the Properties panel.

The first thing we need to set is what should happen when the user taps on a row. There are three choices:

• Auto-submit
  The row behaves like a button; when tapped, it moves the workflow forward. This is especially useful if you want the table to behave like a menu.
• Select item
  The row behaves like a toggle; when tapped, the item is selected. Another button would then determine what to do with the selected item. This is especially useful for selecting and performing actions (such as Deleting) on multiple rows.
• Do nothing
  As you’d expect, does nothing when the row is tapped. Useful for when data is for display-only.

In this instance, when a name of a contact is tapped, we want to move to another page where we can view or edit that contact. We’ll leave it at the default, which is Auto-submit.

The Behaviour Settings allow you to decide how your table should behave in different circumstances

The next behavioral setting concerns the table’s size on-screen. At the moment, we can see that it comfortably displays 5 rows before running out of space. But what happens when we have more than 5 contacts in our list? We have two choices:

• Flexible, grows with content
  As the name implies, this option allows the table to grow to fit whatever content is pushed into it. If there are 200 rows, then the table grows big enough to fit all 200 rows. Anything below the table will be moved further down the screen automatically, so that there’s no ugly overlap.
• Fixed-size, scrollable panel
  If this option is enabled, the table itself will grow, but only the box you’ve marked out on the screen will actually be visible. If the table gets any bigger than this, it will be scrollable.

We don’t have much else on this screen, so we’ll keep it at the default for now: Flexible, grows with content. Now let’s get some data in there.

Find & Retrieving Data

The next step is to pull all of the contacts out of our Address Book database and feed them into our table on-screen. To do that, we’ll need the Data component again.

Change the toolbar to Data and drag another Data component onto the canvas. Drop it to the left-hand side of our new “Contacts List” screen, and draw a link leading from the Data component to the screen. Right-click on the Data component if you can’t see any handles.

Right-click if you can’t see any handles, and choose Straight Link

Once you’ve linked your new Data component to the “Contacts List” screen, we can begin configuring our Data component. Select it on the canvas and look at the Properties panel.

The first thing we need to do is set the Data Source to our Address Book database table. Then we need to choose which action we’d like to perform – in this instance, we want to Find & Retrieve Records.

Basic configuration of our new Data component

You’ll notice two new mapping buttons appear at the bottom of the Properties panel, allowing you to set What to retrieve and Where to put it. Let’s start with the first one.

Options to specify what to retrieve and where to put it appear

Click the Open Mapping Tool button under What to retrieve, and you’ll be asked whether you want to bring back all records, or just specific records that match some kind of search criteria.

The mapping tool, specifying what kind of data to retrieve

In this case, we just want to pull out everything from our database, so select the All Records option and hit confirm.

Now we just need to determine where to put that data. Click the Open Mapping Tool under Where to put it, and you’ll be asked what you intend to do with the data we pull out of the database.

We’d like to use the resulting data-set to populate our new data table

There are a few options, including pre-populating fields in a form (we’ll use this later when we create an “edit contact” form) and populating a data table on a screen (which is what we’re trying to do now).

Check the populate a Data Table within a Screen option and hit confirm. You’ll be taken to the next step, where you’ll be asked to map which database fields should be inserted into which column, for each record that comes back.

Map which database fields should be inserted into which column of which table

Because we linked our Data component to the Contacts List screen, Nutshell has already anticipated which table we want to populate, and has created a new mapping rule for every column in our table (there is only one).

You just need to choose which of our database fields you’d like to be inserted into the Name column. Select the Name field from the Database Fields dropdown, and you should be able to read the whole thing as a plain-English statement:

“For each record returned from Address Book, put Database Field: Name into Table/Column: Contacts List/Name”

Easy.

For the sake of clarity, let’s re-label our Data component “Fetch All Contacts” so that we can see what it does at-a-glance.

Re-label the Data component to make it easily recognisable later

Let’s Preview our new screen and see what the table looks like.

Oops! When we Preview our app, it just re-opens our Add Contact form again. We can remedy that.

Select your new “Fetch All Contacts” Data component again, and at the bottom of the Basic Settings section, you’ll see a checkbox for Set as Start Item. Turn this on and save your changes.

Usually, only screens can be set as the start item (the first thing to load when the app runs), but sometimes these screens need to include data pulled in from the database. In these instances, a Data component configured to Find & Retrieve Records can be set as the start item instead. No other Data action can be used as a start item.

Now Preview again, and you should see your new data table fully populated.

Our new table, populated from our Address Book database

On the left-hand side of the Preview panel, you’ll see our Address Book listing any contacts you’ve added. On the right-hand side, you’ll see the debug console, giving you a glimpse of what’s going on behind-the-scenes.

If the debug console says data is being pulled out of the Address Book, but it isn’t appearing in your app, check your mapping to make sure the right fields are being sent to the correct column.

That’s great, but now we can’t get back to our Add Contact form. Let’s add a button to our Contacts List screen so that our end-users can add a new contact whenever they like.

Change the toolbar to Forms, and drag a new Button component onto your screen.

Drag a new Button component onto the screen

Give it a Reference of “Add Button” and re-label it “Add”. Now re-size it, and tuck it up in the top right-hand corner of the screen, like this:

Tuck the new Add button up in the top-right hand corner

Now draw a link from your Contacts List screen to your Add Contact form, making sure that the link is only followed if your new Add Button is selected.

Draw a link from your Contacts List to the Add Contact form

Finally, with your link selected, make sure Clear next screen is turned on in the Properties panel (right at the bottom of the Basic Settings section). This will ensure that the form is wiped clear again each time the link is followed.

If you don’t turn this option on, Nutshell will remember what was last entered into the form, which in some cases can be extremely helpful… but not in this case.

Preview your app and tap your new Add button to make sure you go back to the Add Contact form. There are two things missing now: a way to get back if you change your mind, and a way to return the end-user to the Contacts List screen after they’ve added a new contact to the database.

Let’s tackle these in order.

Adding a Back Button

Zoom into the Add Contact form, change the toolbar to Forms and drag a new Button component onto it. Give it a Reference of “Cancel Button” and a Label of “Cancel”, then resize and re-position it so that it sits alongside the “Add” button. You should end up with something like this:

Cancel button aligned next to the Add button

The Cancel and Add buttons are the same colour. A good usability practice is to have one primary action on a screen (i.e. the action an end-user is most likely to want to take), and other secondary actions. There should be some distinction between these two actions.

Nutshell gives us a quick and easy way to differentiate these, with the Button Style property. With the Cancel button selected, chose “Secondary” from the Button Style dropdown.

The Cancel button will change colour to the secondary button style

The button changes colour, to something less striking. This indicates that the button is secondary to the Add button, which now stands out more strongly.

While you’re in the Properties panel, turn on the Back to previous screen option and save your changes. Whenever an end-user taps this button, they’ll return to the previous screen automatically – we don’t need to worry about setting up a special link to handle that.

Preview your app to make sure it’s all working.

Now that we’ve done that, the only thing left to do is make sure the end-user is returned to the Contacts List after they’ve added a new contact.

Our two screens, linked together

Zoom out on the canvas, so that you can see the whole app workflow clearly. We haven’t specified what should happen after the “Add New Contact” action is completed – our app just hangs indefinitely. We need to link it back to our Contacts List afterwards.

Trouble is, if we just link back to the screen, it’ll pull up the same list of contacts that were displayed there before we added a new contact. In otherwise, it won’t include the new contact the end-user just added, which doesn’t make sense; our end-user will want to see their new contact in the list to confirm that it worked.

To get around this, we need to link back to the “Fetch All Contacts” action instead, which will reload a fresh list of all contacts, including the new one our end-user just added.

For the sake of neatness, let’s move the “Add New Contact” over to the left-hand side, and draw a link from it, to the “Fetch All Contacts” action. Like this:

After Add New Contact is complete, it will return the end-user to Fetch All Contacts

Make sure that the Link Outcome is set to “Success” in the Link Properties and save your changes. The link will turn green, indicating that if the contact is added to the database successfully, the end-user will be returned to the Fetch All Contacts action, which will in turn pass them back to the Contacts List screen.

Phew!

Preview your app, create a new contact and you should be returned to the Contacts List screen with your new entry there at the bottom of the table.

Hit Add, create a new contact, and it should appear at the bottom of the list

Here’s some homework for you: each time we add a new contact, it appears at the bottom of the list, however most address books display contacts in alphabetical order. See if you can work out how to automatically sort the table by Name in alphabetical order.

So, now our end-user can create new contacts, and see them in a list. That’s a great start. But what happens when the list gets really long, and they need to search form someone by name or email address?

Let’s add that functionality now.

Adding a Search Function

The first step is to add a search field at the top of the screen above the table, like this:

Add a search field above the table

Give it a Reference of “Search Field” and a Placeholder/Label of “Search…” and leave it as Plain text. Also, because we don’t want to force our end-user to search – it is entirely optional – be sure to turn off the Required Field and Validate Field options too.

Next we need a search button. Add one alongside the search field, like this:

We chose to make our Add button a secondary button to create visually hierarchy

Give your search button a Reference of “Search Button” and a Label of “Go”, then align it to the right of your search field.

When our end-user taps this button, we need to query the database again, find anything that matches their search term – either in the Name or Email fields – and then return them to this list, with a new set of search results in the table.

Let’s start by adding a new Data component to handle the database query.

Switch the toolbar to Data and drag a new Data component onto the canvas, somewhere to the right of your Contacts List screen. Then draw a link from your Contacts List screen to the new Data component, like this:

Link your Contacts List screen to the new Data component

There’s more than one link coming from the Contacts List screen, so make sure you tell Nutshell to only follow this one if the “Search Button” is selected, so that none of the other buttons trigger it by mistake.

Once the Data component has done its thing (we’ll configure that in a moment), we want to return to the Contacts List screen again, where we’ll see the results.

We can do this by drawing a link from the Data to component back to the Contacts List again. To keep things tidy, we can use “square” link style to avoid links drawn over the top of one another, like this:

The Go button triggers a link to the new Data component, which returns us to the Contacts List

Now all we need to do is configure our search query. Select the Data component on the canvas, and look at the Properties panel.

First, select our “Address Book” database as the Data Source, and set the Action to “Find & Retrieve Records”.

Set your new Data component to find and retrieve records from your Address Book database

Click the Open Mapping Tool button under What to retrieve, and this time choose to only return records that match specific criteria, which we’ll define in just a moment.

This time, we only want to bring back records that match a specific search term

Before we can set the criteria, Nutshell needs to know where the criteria will be coming from. In this instead, it will be a search term, coming from a form field on our Contacts List screen, so let’s choose Form Fields & Variables.

Our search field is a form field, so we need to choose Form Fields & Variables

The next stage asks us to define our search criteria as a set of rules. At first glance, there seems to be a lot going on here, but it’s deceptively simple.

Nutshell will only select records that match the rules that you set. You can have any number of rules. In this instance, we want to select records where either the Name or Email field in the database contain whatever text the end-user typed into our Search Field.

So, we create those rules so that they read back in plain-English:

Rules should read pretty well in plain-English

Remove any extraneous rules that Nutshell saw fit to include, and the last step is to decide whether both of these conditions must be met (i.e. the Name and Email field should match) or if any one of them will do (i.e. either the Name or Email field should match).

In this case, we’d like to match on any of the rules – in case people have used nicknames for their email addresses – so we choose to include records that meet at least one of these conditions.

Now, we just need to map the results back to our table like we did earlier. Click the Open Mapping Tool button under Where to put it.

We want to use the records returned to re-populate our Contacts List table

Nutshell asks what we’d like to do with the resulting data records. In this case, we want to re-populate our table. Choose Use them to populate a Data Table within a Screen and hit Confirm.

Choose which field to insert into your Name column

The last step is to choose which field from the database you’d like to insert into the Name column of our table. Once that’s set, you’re finished.

Your Address Book app so far – looking tidy, and not a line of code in sight

Preview your app and give it a whirl.

Try searching for a name or email address and see if it works

So, there we have it; a fully-functional database of contacts that we can add new records to and search on one or more criteria. All without writing a single line of code or learning SQL. Not bad for 20 minute’s work!

In the next tutorial, we’ll add a new form with which our end-user will be able to view and edit an existing contact in the database, and perhaps even make a phone call.

In the meantime, hit Publish, choose Only Me and try it out on your Smartphone.