Tutorials

Part 3: Editing & Deleting 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 and second parts of this tutorial, we created the first few screens of a simple Address Book app, with the ability create contacts, see them all listed in a table and even search for them by Name or Email address.

Before we begin, 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 two parts 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 two parts of this tutorial, as this one picks-up where part two left-off.

When we finished the last tutorial, we’d created a contacts list, with a keyword search facility that allowed end-users to find contacts by Name or Email address.

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

In this tutorial, we’re going to set-up another screen for viewing and editing the details of a contact when our end-user taps their name in the Contacts List. Sounds complicated, but it’s actually very simple.

This is where we really test your knowledge of Nutshell. If you’ve completed all of the tutorials so far, this should be a breeze…

Create a new screen labelled “View/Edit Contact” and position it on the canvas immediately below the Contacts List screen. You probably know how to do this by now. If not, it might be worth repeating some of the earlier tutorials.

Next, add a title to the screen using the Text component, and title it “View/Edit Contact”. In the future, you could easily create separate screens for viewing and editing, but for now, to keep things simple, our screen is going to be multi-purpose.

Now recreate the same form we built for the Add Contact screen – the same fields, labels and settings, with an “Update” button at the bottom. You should end up with something like this:

Our new View/Edit Contact screen looks a lot like our Add Contact screen

Now that we’ve set-up our “edit contact” form, we need to pull-in the details of whichever contact our end-user selected on the Contacts List, and use them to pre-populate the appropriate form fields. For this, we need another Data component.

Switch the toolbar to Data, and drag a new Data component onto the canvas somewhere between the Contact List and the View/Edit Contact screens. Now draw a link from the Contacts List screen and the Data component, then another from the Data component to the View/Edit Data screen. Like this:

Link from Contacts List screen to View/Edit Contact screen via our new Data component

The idea is that when our end-user taps on a contact in our list, the workflow will move automatically to our new Data component, extract the relevant record from the database, and then continue to our View/Edit Contact form, where each of the fields will be displayed in the appropriate form field.

To achieve this, we need to configure our Data component to select the record that the end-user tapped. This is easier than it sounds.

Select the new Data component on the canvas and look at the Properties panel. Start by selecting “Address Book” as our Data Source, and “Find & Retrieve Records” as our Action, since we need to find and retrieve the specific contact we’ll be editing.

Set the Data Source and Action of your new Data component

Next, we need to determine what we want this Data component to retrieve. To do this, click the Open Mapping Tool button under What to retrieve. We want to pull out a single record based on specific criteria.

We only want to select records that match specific criteria (i.e. the table row our end-user taps)

You’ll then be asked where this criterion will be coming from.

When we created the search query earlier, the criteria came from a form field (the search field on our Contacts List screen). This time, however, it’s coming from an Item selected from a Data Table.

The record will be selected within a Data Table by our end-user

When we choose this option, the ID of the record our end-user taps is passed automatically to the Data component, to let it know which item in particular the end-user tapped on. That means we don’t have to figure out the ID ourselves.

Finally, we just need to tell Nutshell which table this information will be coming from. Again, because you linked your screens up to your Data component before mapping it, Nutshell has a good idea of which table you might want to reference, and will try to pre-populate this for you.

Choose the List of Contacts table on the Contacts List screen

Now that we’ve determined which record to pull out of the Address Book database, we now need to specify where Nutshell should put that data. Click the Open Mapping Tool button under Where to put it.

The last time we did this, we wanted to populate a Data Table. This time, we just want to pre-populate fields in a form. Select the Use them to populate form fields option and hit Confirm.

We’re going to use the data record we bring back to populate form fields

The last step is to map which database fields should be inserted into which form fields.

For each of the fields in our View/Edit Contact form, select which database field should be used to pre-populate it. Don’t forget to remove any extraneous rules you don’t need, and then hit Confirm.

Map your database fields to the appropriate fields in your View/Edit Contact form

That’s it. The Properties panel will update to reflect your mapping.

Preview your app and check that it works. Tap on a contact in the list, and you should see the appropriate contact open in our new View/Edit Contact form.

When our end-user taps on a name, the full details for that contact open up in our form

Before we add the ability to save any changes we make to the contact, we should probably add a “Back” button, so that our end-user can return to the main contacts list if they like. Change the toolbar to Forms and drag a new Button onto the screen.

We’ve used the “Secondary” styling and turned on the Back to previous screen option, so that it’ll go back the main contacts List when our end-user taps it.

Add a Back button at the top of the screen

Updating Data Records

When our end-user makes changes to the contact, we want those changes to be saved back to the database when they tap the Update button. As you’d expect, we’ll be using another Data component to achieve this.

Change the toolbar to Data and drag another Data component to the canvas. Put it somewhere to the left of our View/Edit Contact form, like this:

Add another Data component to the canvas

Next, we need to link to it from our form.

Link to your new Data component from the View/Edit Contact form

Because we’ve got a couple of buttons on our form (and we’re going to be adding more soon), we need to make sure this link is only followed if the “Update” button is selected.

This link should only be followed if our end-user taps the Update button

Finally, once the update is finished, we want to return our end-user to the Contacts List. Draw another link, this time from the Data component back to the Contacts List screen.

Remember though; if we link directly back to the screen itself, the contacts displayed in the list will be out of date, so we need to link back to the “Fetch All Contacts” data component instead.

This will re-run the database query and pull out the very latest contacts data, including any changes our end-user just made.

Link your new Data component back to Fetch All Contacts

So, when our end-user taps the Update button, our new Data component will run, and then return the end-user to the fully-refreshed Contacts List screen.

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

Set the Data Source to “Address Book”, and for the Action, choose to “Update existing record(s)”. You might want to also re-label the component “Save Changes” so that it’s clear what it does from the canvas.

Set the Data component to Update existing records in the Address Book database

Two new options appear in the Properties panel, as usual. The first option is to define which record(s) to update. This should be familiar, as it’s the exact same process we just used to decide which data record to pull out the database earlier.

Click the Open mapping tool button under What to update. You’ll be asked where the criteria for choosing a record will be coming from. In this case, it’ll be coming from the List of Contacts table.

Nutshell will remember that our end-user tapped on a record in the Contacts List table, and we can reference that again here.

We’ll be updating the record that our end-user taps in the Contacts List data table

You’ll then be asked which table the record will be selected in. If there isn’t a rule already set-up, create one, and choose the Data Table on our Contacts List screen. Whichever record our end-user taps on in that table will be updated.

Choose the List of Contacts table

The next step is to tell Nutshell which form fields should be used to overwrite which database fields when the update is made.

To do this, click the Open Mapping Tool button under Update fields.

Because we linked our screen to our Data component before configuring it, and we named our form fields the same way as our database fields, Nutshell can guess which information to insert into which field.

Nutshell’s smart auto-mapping saves a lot of time

Double-check that Nutshell got it right, and then click Confirm to finish.

Preview your app and try editing one of your contacts. Be sure to try editing each field one-by-one, and make sure they’re being saved in the database. Also, check that when you are returned to the Contacts List, the name you changed has updated too.

A quick test confirms that our mapping works perfectly first time

Our Address Book app is coming along very quickly. We can create contacts, view them in a list, search for them by name or email address and update their details later. The only thing we can’t do yet is delete a contact.

Let’s add that now.

Deleting a Record

When our end-user opens a contact, as well as updating the record with any changes they make, we also want to give them the option to delete it. Let’s start by adding a Delete button, which will sit right next to the Update button.

Add a Delete button next to the Update button

This time, we’re going to use the third “Destructive” styling option for our Button.

It’s usually a good idea to style buttons that trigger destructive actions – like deleting an item permanently from a database – differently from other buttons on the screen, so that end-users can see that there’s something risky about tapping them.

In this case, our Delete button turns red, which is a sure sign of danger. Hopefully it will make our end-users think twice before tapping it.

Now all we need is to hook it up to – you guessed it – another Data component.

Drag one to your canvas and place it somewhere sensible. We’ve placed ours just above the “Save Changes” data component, so that it can be linked-up without getting muddled.

Add your new Data component and link to it from your View/Edit Contact screen

Draw a link to it from your View/Edit Contact screen, and then configure the link so that it is only followed when your Delete button is tapped. We certainly don’t want this link being triggered by accident!

Just as we did earlier with the Update data component, we want the end-user to return to our Contacts List after a contact is deleted. We also want to make sure that when they arrive there, the Contacts List table is refreshed, so that the item they just deleted is no longer there.

To do this, we draw another link from our new Data component back to the Fetch All Contacts data component, like this:

Draw a link back from your new Data component to Fetch All Contacts

Now, once a contact has been deleted, the end-user will be returned to the Contacts List, where the deleted contact will be gone. We just need to configure the Data component and we’re done. Select it on the canvas and look at the Properties panel.

Choose “Address Book” for the Data Source, and for the Action, choose to “Delete existing record(s)”. Another option will appear below, allowing you to specify what should be deleted.

This Data component will Delete existing record(s) from the Address Book database

Click the Open Mapping Tool button under What to delete. The steps are identical to those we used earlier to specify which records should be Updated:

1. First tell Nutshell that the record to be deleted will be selected from a Data Table
2. Then tell Nutshell which data table in particular (our Contacts List, of course)

That’s it. Because all we’re doing is deleting a record, there’s no further mapping to do.

Preview your app, open a contact from the list and try deleting it.

Open a contact, hit Delete and make sure it’s gone when you return to the list

So, we’ve created an entire database-driven mobile app in minutes, without writing a single line of code. We can create, search, retrieve, edit and delete data records using simple mapping tools. What’s next?

You could add some extra fields to the Address Book database for physical address and perhaps even a photograph. You could turn on validation to make sure the data you collect in your app is good data.

You could even add a “Call” button to the contact, which will trigger a phone call when the end-user taps it. This is a Smartphone app, after all.

In fact, let’s do that now. It’ll only take five minutes.

Triggering a Phone Call

The first thing we need is a button. You probably don’t need to be told how to do that by now. We’ve put ours right next to the Telephone field, since it’s the contact’s Telephone number we’re going to be dialing.

Add a Call button somewhere near the Telephone No. field

Now, switch the toolbar to Device, which contains a bunch of components that allow you to integrate your app with the end-user’s device. In this toolbar, you’ll find a Phone component.

Drag it onto the canvas, somewhere to the right of your View/Edit Contact screen, and draw a link to join the two.

Add your Phone component, and link to it from the View/Edit Contact screen

Now, select the link and set it to only be followed if the Call button is selected.

Only follow this link if your end-user taps on the Call button

Now, we just need to tell the Phone component what number to call. Select it on the canvas and look at the Properties panel. You’ll see a Phone Number property, which we could hand-type a number into, but we don’t want to do that.

The Phone Number property can be automatically populated from a data-source

Instead, we want to automatically pull-in the contact’s number from the Telephone No. field in our View/Edit Contact screen. To do this, we click on the little lightning bolt icon next to the Phone Number property.

You’ll be asked where you’d like to pull the data from. In this case, we want to pull it from a form field on a screen.

We want to pull our Telephone No. from a form field on a screen

You’ll then be asked to select, on the canvas, which form field in particular you’d like to pull data from.

By the time our end-user taps the Call button, the Telephone No. field in our View/Edit Contact screen will be pre-populated from the database. So, let’s choose that.

Click on the Telephone No. field to select it as the data-source

The Properties panel will update to reflect this field-mapping.

The Properties panel is updated to reflect where the data will be coming from

Because your computer doesn’t have a phone built-in, the Call button won’t work in Preview, so publish your Address Book app to yourself and test it on your phone.

That’s the end of our tutorial.

In less than an hour, we’ve created a fully-functional database-driven mobile app, which can be extended in any number of different ways.

In future tutorials, we’ll cover how to use Nutshell’s Connectors to hook an app like this to a third-party CRM product, such as Salesforce. But for now, we’ll leave you to play!