Tutorials

Part 3: Creating & Emailing a PDF

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

In Parts 1 & 2 of this tutorial, we built a very basic “Hello World” app and then personalised it with dynamic data we captured from the end-user.

This tutorial follows on from that, turning that personalised on-screen message into a PDF document that will be emailed to the end-user. If you haven’t already completed the first two parts of this tutorial, now would be a good time to do that.

If you have, fire-up Nutshell, open your “Hello World” app in the builder and let’s get started.

Creating an Email

Instead of going back to the start screen, we want our app to send an email, so let’s change the “Go Back” button to “Send Email”. Start by selecting it, and in the Properties panel, change the Label to “Send Email” and Reference to “Send Email Button”.

Change the Go Back button to Send Email

While you’re in there, un-check the Back to previous screen option and save your changes. When a user taps this button, we don’t want it to take them back to the start screen again.

Now all we need to do is create and send an email. Change the toolbar to Essentials, and drag an Email component to the canvas. The Email component is a background process (which means the user never sees it on-screen) so it always sits directly on the canvas.

Position your Email component to the right-hand side of your workflow

You’ll notice the little red warning triangle on the Email’s icon. This is telling you that this component will certainly break if you tried to run your app right now, because it needs some basic configuration first. We’ll do that in a moment.

For now, let’s link our “Hello” screen to the Email component, so that the Email is triggered when the Send Email button is tapped.

Draw a link from the “Hello” screen to your new Email component

We’ll need to tell Nutshell only to follow this link when the Send Email button is tapped. To do that, select the link and look at the Properties panel. In the Behaviour section, tell Nutshell to only follow this link if “Send Email Button” is selected, and save your changes.

This link will only be followed when the user taps Send Email

Now let’s configure the Email itself and get rid of that red warning triangle. Select it on the canvas and look at the Properties panel. I want to send this email to myself, so that I can make sure it’s working properly, so I’ll use the following settings. You can use whatever you like.

• Label: “Send Email”
• To: nutshellalex@gmail.com
• From: noreply@nutshellapps.co.uk
• Subject: “Hello”
• Emails that fail to send should be: “Queued for later”

That last setting just means that if my end-user has a poor network connection and the email can’t be sent right then, Nutshell will put it in a queue and re-try at a later time, when the connection is stronger.

Our email component fully-configured (well, almost)

The only thing left to do now is to create some content for our email. With the Email still selected on-canvas, you’ll find an Edit Email Content button towards the top of the Properties panel. Click it to open the email editor.

Type into the Nutshell email content editor

Start by typing in a short message. In this instance, we’ve put “Name would like to say hello!”. We’re going to substitute the word “Name” with the name of our end-user. But first, let’s make it look a little more attractive.

Select the text, and using the toolbar across the top, change the font to 18pt Roboto, and choose a nice purple colour so that it matches our app user-interface a little better. You should end up with something like this:

That’s a little more engaging

Now let’s insert the end-user’s name dynamically into our email. We can do this in exactly the same way we did on-screen. Just select the word “Name” and hit the little lightning-bolt icon in the toolbar.

The lightning-bolt icon always indicates that you can insert data dynamically

You’ll be asked where the data you’d like to insert is going to come from. In this case, it’ll come from the Name field on our start screen, which is an Input.

Our data source will be an input (form field)

Select Input and hit Confirm.

Next, you’ll be asked which form field you’d like to pull data from. In this case, we’ll be pulling the end-user’s name, which will be captured in the Name field on the start screen.

Select the Name field on your start screen as the data-source

Click on the Name field in your start screen to select it. You’ll be taken back to the Email content editor, where a placeholder will appear in your text.

A placeholder now sits within our email content

When the email is sent, this placeholder will be replaced with whatever the end-user typed into the Name field. Let’s see if it works.

Save your changes and hit Preview.

Click the Send Email button

When you click the Send Email button, you should see a little progress bar flash across the bottom of the screen. This means the email has been sent. Check your mailbox.

Our email appears as we styled it, with the name correctly inserted

So, we know it works. But after the email is sent, our app just stays on the “Hello” screen. Without a Go Back button, how do we get back to the start screen afterwards?

That’s easy. Any component in Nutshell that talks to a third-party system (in this case, a mail server) gives you the option of following different paths in your workflow depending on whether it was successful or not.

So, in this case, we can send our app down different paths, depending on whether the email was sent or not. Let’s do that now.

Select your email component, and draw a Link from it, leading back to the start screen.

Draw a Link back from your email component to the start screen

It’s going to get pretty confusing with all these links crossing over one another. We can tidy them up a bit. Select your new link on the canvas and look at the Properties panel.

Expand the Style section to find three different styles of Link – straight, curved and angled. Select the Curved style and save your changes.

The Style settings allow you to create links that curve around other components

Your link will take on a curved appearance on the canvas, but it probably doesn’t curve the right way. Click any point along its length and drag it on the canvas to adjust the curve. Move it so that it curves around the other components, like this:

Click and drag the link to adjust the curve

That’s much neater.

Now, with the link still selected, look at the Properties panel again. You’ll see another section titled Link Outcome.

This section is unique to links emerging from components that perform some sort of operation – e.g. sending an email, connecting to a database, or making an external API call – and allows you to create links that will only be followed if that operation succeeds or fails.

For now, we’re just going to set up a Success outcome. We want this link to be followed after the email has been sent successfully. We can deal with failures another time.

Check the Success option and save your changes.

When the Link Outcome is set to Success, this link will only be followed if the operation worked

You’ll notice the link line turns green (failure outcomes turn red) so that you can see at a glance what it means.

Preview your app again, and this time, once the email has been sent, you’ll be returned to the start screen.

Hopefully everything is working now, and you’re receiving a nicely designed personalised email containing dynamic data-captured from your end user. Pretty sophisticated for a few minutes’ work, and we haven’t had to write a single line of code.

But what if we want to send our personalised message in a PDF document? That would be cool, right? Another tutorial perhaps?

It’s deceptively easy, so let’s do it right now.

Generating a PDF

Change the toolbar to Essentials and drag a PDF component onto the canvas. Position somewhere near your Email component, as we’re going to be attaching the PDF to our email.

Drag the PDF component onto the canvas next to our Email component

Again, the little warning triangle tells us that we need to do some basic configuration. Select the PDF on the canvas and look at the Properties panel.

Basic PDF properties

Let’s give it a Label of “Hello PDF” so we can see at-a-glance what it’s there for. We’ll also need to give it a filename. The .pdf extension will be added automatically, so just the word “hello” will do in this instance.

We’ll leave the paper size at the defaults for now (A4 portrait) and the margins too. At the bottom of the properties panel, you’ll see an option to Include Copyright Notice. This is such a great app, we don’t want anyone else to copy it, so let’s turn that on.

Add a custom copyright notice

We could add a page number too, but since this is a one-page document, we don’t really need it. Hit Save Changes.

Now, let’s create some content for our PDF. After creating our email, this should be a breeze, as it works in exactly the same way. At the top of the Properties panel, click the Edit PDF Content button to launch the content editor.

The PDF content editor is exactly the same as the Email content editor

You’ll be happy to find that the PDF content editor is exactly the same as the Email content editor we used earlier. Let’s type in our personalised message, and style it so that it matches our email.

Now use the lightning-bolt tool to insert our end-user’s name dynamically into our PDF, in the same way we did earlier with the email.

Our end-user’s name will be injected into the PDF when it is created

So, we’ve finished creating our PDF document. All we need to do now is attach it to our email. You do this by drawing a link on the canvas from the PDF component to the Email component.

Draw a link from the PDF component to the Email component

You’ll notice that the link is a dotted line this time. This indicates that it is an attachment. In other words, when the email is sent, the PDF will be sent as an attachment.

That’s it.

Preview your finished to make sure it’s all working properly.

Data captured from your end-user is pulled into the following screen

The email should arrive as it did before, only this time a file called hello.pdf should be attached. The end-user’s name should have been inserted dynamically into the PDF too.

Email with personalised PDF document attached

So, in this series of tutorials, we’ve created a simple app that captures user-input, uses that data to personalise the user-experience and sends that data in a PDF by email. And all in a few minutes, without writing a single line of code.

Just imagine what kind of data you could process by adding only a few extra form fields.

In the meantime, hit Publish and give it a whirl on your Smartphone.