Keeping it pithy: Toasts in Cascades Featured

What is a toast? Well according to BlackBerry...

"A SystemToast displays a small message that expires and disappears after a predefined amount of time. This message provides users with information and allows them to continue with the application after the toast expires."

You've seen toasts when you clear your browser history or delete an attachment from a BBM and in many other places throughout BlackBerry 10. When dealing with toasts and any other user prompts, developers need to be cognizant of the user experience and of the fact that users typically do not want to be interrupted (at least not too frequently).

So when is it appropriate or not to use a toast? To answer this we need to acknowledge that there are two types of toast. The basic toast is minimally intrusive and contains text only. Also available is a slightly more intrusive toast with a button that is typically reserved to undo a delete action. In both cases, a toast is appropriate for a short (one sentence) message that can be read in a matter of a few seconds. If using a toast with a button, it is particularly important for the message to be brief, so the user can both read the message and take action on the message if needed before the toast finishes.

When to use:

  • Clearing a text field (undo button needed)
  • Deleting an item from a list (undo button needed)
  • Alerting users to an event such as “Download/Upload finished”, “New Achievement Unlocked”, etc. (NO undo button)

When NOT to use:

  • Anytime you want to present users with information longer than one simple sentence
  • Anytime a user is required to respond to the alert (use a dialog in this case)

Keep in mind that toasts allow the user to continue using the app and can be completely ignored by the user. So if your alert requires a user to respond in some way, use a dialog.

The Basic Code

When appropriately used, toasts are incredibly useful, so let’s dive into the code. SystemToasts, like dialogs, are attached objects that can be called upon and shown when a signal fires.

 

First things first, on lines 1 and 2 of your qml document, you must import both the cascades library and the system library...

import bb.cascades 1.0
import bb.system 1.0

 

To attach a toast…

attachedObjects: [
        SystemToast {
            id: simpleToast
            body: "Short and sweet. Congrats!"
        }
    ]

To call a toast simply use the .show() function tied to whichever signal you want to use.

Example 1:

Button {
    onClicked: {
        simpleToast.show();
    }
}

Result:

toasttut1

Example 2:

 

            Button {
                text: "Delete the Sweet"
                attachedObjects: [
                    SystemToast {
                        id: intrusiveToast
                        body: "Short, but sweet deleted!"
                        button.label: "Undo"
                        button.enabled: true
                    }   
                ]
                onClicked: {
                    intrusiveToast.show()
                }
            }

 

Result:

 toasttut3

Diving a Little Deeper

That's the basics of how to show a toast. Now let's take a look at more of a real world example and dive a bit deeper. In the previous example a toast was shown on a button click and an undo button was present on the toast, but the button did not actually have any fucntion tied to it. In the next example we will show the toast when a different signal fires and hook up the undo button.

The Code

Comments are in BOLD

import bb.cascades 1.0
import bb.system 1.0
Page {
    Container {
        layout: DockLayout {
        }
        verticalAlignment: VerticalAlignment.Fill
        horizontalAlignment: HorizontalAlignment.Fill
        Container {
            verticalAlignment: VerticalAlignment.Center
            horizontalAlignment: HorizontalAlignment.Center
            //Text field for user to enter some text
            TextField {
                id: inputField
                //create a property to temporarily hold the
                //text string from our field when the user clears the field
                property string storedText
                hintText: "Enter some text"
                
                onTextChanging: {
                    if (text != "") {
                        clearButton.enabled = true
                    } else {
                        clearButton.enabled = false
                    }
                }
            } //end TextField
            //Button to clear the field and trigger our toast
            Button {
                id: clearButton
                text: "Clear Field"
                horizontalAlignment: HorizontalAlignment.Center
                enabled: false
                onClicked: {
                    //First we assign the field text to the property
                    //string from the TextField to temporarily store the string
                    inputField.storedText = inputField.text
                    //After we temporarily store the text
                    //from the field, we clear the field text
                    inputField.setText("")
                    //and here we show the toast
                    intrusiveToast.show()
                }
            } //end Button
        }
        attachedObjects: [
            SystemToast {
                id: intrusiveToast
                //Let the user know the field has been cleared
                body: "Field contents cleared"
                //here we enable the undo button and label it
                button.label: "Undo"
                button.enabled: true
                //Regardless of whether the user taps
                //the undo button, the toast will finish
                //Once the toast finishes, if the user tapped
                //"undo" then we restore the field text using
                //the property in which we stored the string
                onFinished: {
                    if (intrusiveToast.result == SystemUiResult.ButtonSelection) {
                        inputField.setText(inputField.storedText)
                    }
                }
            } //end Systemtoast
        ]
    }
}

In the above example, we have a TextField and a Button shown, and we have an intrusive SystemToast attached.  So when the user enters some text into the field and then taps the button, a couple of things happen in a particular order.

1The very first thing we need to do is use a string property to store the original text from the text field before it is cleared by the button click

2Now that the text is temporarily stored, we can clear the field by setting the text to be empty

3With the previous two functions done, now we can trigger the toast.

 

field clear toast


 

field clear toast2

While the toast is being shown, the user can tap 'Undo' to restore the field text. If we hadn't stored the origianl text before clearing the field, the undo action could not function, and the user may hate you ;)

So, with that I bid you adieu for now. Be sure to download the pre-signed bar of the in depth example above and the full source ZIP attached to this post. And as always, happy coding!

Useful Links:

https://developer.blackberry.com/native/documentation/cascades/ui/dialogs_toasts/

https://developer.blackberry.com/native/documentation/cascades/ui/dialogs_toasts/toasts.html

Leave your comments

Post comment as a guest

0
  • No comments found
Subscribe to the official OSBB BBM Channel!

osbbchannelQR

C00013E89

Back to top