Application Development : Defining the Application Structure – Single Page Applications – Page Actions

Single Page Applications

A single Page application is entirely built around a unique Page at the root of the scene graph. You have been essentially designing single Page applications until now. The biggest advantage of the single Page application structure is not only its simplicity, but also the capacity to provide the user a single screen where all content and Actions are presented in an extremely focused way during the entire application lifetime. You might think that building your application around a single Page might lack the flexibility required for more complex interactions. You will, however, see that you can provide a very enticing user experience based on the single Page design using the controls presented in the following sections (you will also be able to extend very naturally the concepts introduced for single Page applications to multiple Page or navigation-based apps).

Actions

I have informally mentioned Actions when I discussed the Action bar. This section will show you how to implement them in practice in your own applications. There are several places where you can define Actions:

• You can add Actions to a Page by setting the Page’s Actions property. You can also specify whether the Actions are displayed on the Action bar or in the Action overflow menu (by default, page Actions are located in the overflow menu and only the most used Actions should appear on the Action bar).
• You can add context Actions to a UIControl, which will be displayed in a context menu when the user touches and holds the control in your app.
• Finally, you can add Actions to a TitleBar.

1 ActionItem

An ActionItem object represents the actual Action. You can specify the following properties when declaring an ActionItem:

• ActionItem::title: A text string that will be displayed with the Action (for example, on the Action bar or in a menu).
• ActionItem::imageSource: A URL specifying the image set on the Action.

When the user triggers the Action, the ActionItem::triggered() signal is emitted. You can therefore use the onTriggered: handler in QML in order to react to user Actions.

2 Page Actions

Listing 1 illustrates how Actions are added to a Page control.

Listing 1.  Actions

import bb.cascades 1.0
Page {
        actions: [
        ActionItem {
            id: action1
            title: "action1"
            onTriggered: {
                actionLabel.text = action1.title
            }
        },
        ActionItem {
            id: action2
            title: "action2"
            onTriggered: {
                actionLabel.text = action2.title
            }
 
       }
       ]
    Container {
        Label {
            id: actionLabel
            text: "Hello Actions"
            textStyle.base: SystemDefaults.TextStyles.BigText
            horizontalAlignment: HorizontalAlignment.Center
        }
    }
}

Figure 2 shows the action bar when all Actions are located in the overflow menu.

Figure 2. Actions overflow menu

And Figure 3 displays the expanded overflow menu.

Figure 3. Expanded overflow menu

If you want to display actions directly on the Action bar, you need to set the ActionItem’s ActionBar.placement property to ActionBarPlacement.OnBar (see Listing 2 and Figure 4).

Listing 2. Actions on Action Bar

import bb.cascades 1.0
 
Page {
        actions: [
        ActionItem {
            id: action1
            title: "action1"
            ActionBar.placement: ActionBarPlacement.OnBar
            onTriggered: {
                actionLabel.text = action1.title
            }
        },
        ActionItem {
            id: action2
            title: "action2"
            ActionBar.placement: ActionBarPlacement.OnBar
            onTriggered: {
                actionLabel.text = action2.title
            }
        }
        ]
    Container {
        Label {
            id: actionLabel
            text: "Hello Actions"
            textStyle.base: SystemDefaults.TextStyles.BigText
            horizontalAlignment: HorizontalAlignment.Center
            contextActions:[

        }
    }
}

Figure 4. Actions on Action bar

3 Context Actions

You can also associate actions to a UIControl by setting the UIControl::contextActions property (see Listing 3).

Listing 3.  Context Actions

import bb.cascades 1.0
 
Page {
    Container {
        Label {
            id: actionLabel
            text: "Hello Actions"
            textStyle.base: SystemDefaults.TextStyles.BigText
            horizontalAlignment: HorizontalAlignment.Center
            contextActions: [
                ActionSet {
                    Title:
                    ActionItem {
                        id: action1
                        title: "action1"
                        ActionBar.placement: ActionBarPlacement.OnBar
                        onTriggered: {
                            actionLabel.text = action1.title
                        }
                    }
                    ActionItem {
                        id: action2
                        title: "action2"
                        ActionBar.placement: ActionBarPlacement.OnBar
                        onTriggered: {
                            actionLabel.text = action2.title
                        }
 
                    }
                }
            ]
        }
    }
}

You need to touch and hold the Label in order to display the context Actions. Notice how the Actions are grouped in an Action set. (You can specify multiple Action sets, but at the moment, Cascades will take only the first one into account. This might change in future releases.)