Lists and Grids for Displaying Data in Sailfish OS

This article was peer reviewed by Marc Towler. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!

---

Lists and Grid are one the fundamental building blocks of any mobile application.

In this article I’m going to introduce the design of the SilicaListView and SilicaGridView, the Silica implementation of these common components. We will see some examples on how to display types of data, handle clicks and more, keeping the code as simple as possible.

The MVD design

Sailfish OS UIs are based on QML, a declarative language provided by the QT Framework. To give the developer or designer control over different aspects of an application, QT uses the Model-View-Delegate design pattern to modularize the visualization of data.

The model holds the data and its structure, and the View is a container that displays the data. In our case the view will be a list or a grid. Finally the delegate dictates how the single piece of data will appear in the view.

The SilicaListView

Let’s start with a simple example:

import QtQuick 2.0
import Sailfish.Silica 1.0

Page {
    id: page

    SilicaListView {
        width: parent.width;
        height: parent.height
        model: ListModel {
        ListElement { name: "Paul"; telephone: "342342341" }
        ListElement { name: "Laura"; telephone: "343241" }
        ListElement { name: "Luca"; telephone: "6454341" }
        ListElement { name: "Daniel"; telephone: "23431231" }
        ListElement { name: "Seb"; telephone: "666342342341" }
        ListElement { name: "Carl"; telephone: "55342342341" }
        }

        delegate: Item {
            width: parent.width
            height: Theme.itemSizeMedium
            Label {
                text: name
                font.pixelSize: Theme.fontSizeMedium
                anchors {
                            left: parent.left
                            right: parent.right
                            margins: Theme.paddingLarge

                        }
            }
        }
    }

}

Apart from the page components (look at this article for an introduction to Silica Components), we declared a SilicaListView with an hard coded model. The list will appear like this:

Each ListElement is an object with two properties – a name and a phone number.

The delegate is just an Item (the basic QML component) with its ‘width’ property set to fill the ListView width and the ‘height’ set using the Theme object, the actual size is calculated at runtime, adapting it to the display in use.

The delegate contains a Label displaying the contact name. To show the phone number I can add another Label to the delegate:

Item {
            width: parent.width
            height: Theme.itemSizeMedium
            anchors {
                        left: parent.left
                        right: parent.right
                        margins: Theme.paddingLarge

                    }

            Label {
                id: cName
                text: name
                font.pixelSize: Theme.fontSizeMedium
                anchors {
                            left: parent.left
                            right: parent.right
                        }
            }

            Label {
                text: "Tel: " + telephone
                font.pixelSize: Theme.fontSizeSmall
                anchors {
                            left: parent.left + Theme.paddingSmall
                            right: parent.right
                            top: cName.bottom
                        }
            }

Model and Delegate can be defined inline but as models get bigger, it’s better to move it in another QML file.

For example, you can create a ContactsModel.qml file with this content:

import QtQuick 2.0

ListModel {
        ListElement { name: "Paul"; telephone: "342342341"; team: "IT" }
        ListElement { name: "Laura"; telephone: "343241"; team: "IT"}
        ListElement { name: "Luca"; telephone: "6454341"; team: "IT" }
        ListElement { name: "Daniel"; telephone: "23431231"; team: "Sales" }
        ListElement { name: "Seb"; telephone: "666342342341"; team: "Sales" }
        ListElement { name: "Carl"; telephone: "55342342341"; team: "Sales" }
        }

And use it as a list model:

    model: ContactsModel {}

I added the team property to use in the next example.

A List sometimes needs to be divided into sections. Do this using the section property to define the model key used as grouping element and the delegate to use as a section header.

Define the section property in the SilicaListView:

    section {
        property: "team"
        criteria: ViewSection.FullString
        delegate: SectionHeader {
                text: section
            }
        }

Now it’s time to handle the click events and react to them.

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    var name = list.model.get(index).name
                    console.log(name);
                }

We defined a MouseArea element filling our delegate. This way we can catch and handle the click event and get the clicked element using the list model get and index property.

Every list can have a header and footer attached to the respective list property. These are useful as you shouldn’t include a SilicaListView or GridView in another Scrollable element. If you need content before or after the list/grid then use these properties.

   SilicaListView {
        id:list
        width: parent.width;
        height: parent.height
        model: ContactModel {}
        header: MyHeader {}
        footer: Button {
            width: parent.width
            anchors.margins: Theme.paddingSmall
            text: "Load more..."
              onClicked: console.log("clicked!")
          }

        section {
            property: "team"
            criteria: ViewSection.FullString
            delegate: SectionHeader {
                    text: section
                }
            }

        delegate: Item {
            width: parent.width
            height: Theme.itemSizeMedium
            anchors {
                        left: parent.left
                        right: parent.right
                        margins: Theme.paddingLarge

                    }

            Label {
                id: cName
                text: name
                font.pixelSize: Theme.fontSizeMedium
                anchors {
                            left: parent.left
                            right: parent.right
                        }
            }

            Label {
                text: "Tel: " + telephone
                font.pixelSize: Theme.fontSizeSmall
                anchors {
                            left: parent.left
                            right: parent.right
                            top: cName.bottom
                        }
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    var name = list.model.get(index).name
                    console.log(name);
                }
            }
        }
    }

We can choose to declare objects inline or in a separate file. As an example I created a file called MyHeader.qml with this content and declared the footer inline:

import QtQuick 2.0
import Sailfish.Silica 1.0

PageHeader {
        title: "Numbers"
}

Models

To simplify a developer’s life QML define a set of ready to use models, such as SqliteModel, XmlListModel and SparqlModel. You can defined your own models using the C++ QT API.

As an example, we can display the latest Sitepoint news using the site’s RSS feed. Let’s define our model using the predefined XmlListModel:

XmlListModel {
     id: feedModel
     source: "https://www.sitepoint.com/feed/"
     query: "/rss/channel/item"
     XmlRole { name: "title"; query: "title/string()" }
     XmlRole { name: "link"; query: "link/string()" }
     XmlRole { name: "description"; query: "description/string()" }
     XmlRole { name: "pubDate"; query: "pubDate/string()" }
}

Here we define the source of the feed and the query property that set the scope for the model. Only <item> children will be used, and the three XmlRoles act as a property inside the ListElement.

Now we can make our list view using this model, the complete example looks like this:

import QtQuick 2.0
import Sailfish.Silica 1.0
import QtQuick.XmlListModel 2.0
Page {
    id: page


    SilicaListView {
        id:list
        width: parent.width;
        height: parent.height
        model: XmlListModel {
            id: feedModel
            source: "https://www.sitepoint.com/feed/"
            query: "/rss/channel/item"
            XmlRole { name: "title"; query: "title/string()" }
            XmlRole { name: "link"; query: "link/string()" }
            XmlRole { name: "description"; query: "description/string()" }
            XmlRole { name: "pubDate"; query: "pubDate/string()" }
       }

        header: MyHeader {}
        footer: Button {
            width: parent.width
            anchors.margins: Theme.paddingSmall
            text: "Load more..."
              onClicked: console.log("clicked!")
          }

        delegate: Item {
            width: parent.width
            height: Theme.itemSizeMedium
            anchors {
                        left: parent.left
                        right: parent.right
                        margins: Theme.paddingLarge

                    }

            Label {
                id: cName
                text: title
                font.pixelSize: Theme.fontSizeSmall
                anchors {
                            left: parent.left
                            right: parent.right
                        }
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    var name = list.model.get(index).name
                    console.log(title);
                }
            }
        }
    }

}

We need to address situations where we have no items to display, for example when the feed is still loading.

We can use the ViewPlaceholder element to handle this, binding its visibility to the count property of the list view:

ViewPlaceholder {
enabled: list.count == 0
text: "Loading..."
hintText: "Be patient my friend"
}

Models in Js

If you need to generate a just in time model, you can use javascript. We obtain and display a list of numbers from 1 to 100 like this:

import QtQuick 2.0
import Sailfish.Silica 1.0


Page {
    id: page

    SilicaListView {
        id:list
        width: parent.width;
        height: parent.height
        model: ListModel {
           id: myJSModel

        }
        header: MyHeader {}
        footer: Button {
            width: parent.width
            anchors.margins: Theme.paddingSmall
            text: "Load more..."
              onClicked: console.log("clicked!")
          }
        delegate: Item {

            width: parent.width
            height: Theme.itemSizeMedium
            Label {
                text: value
                font.pixelSize: Theme.fontSizeMedium
                anchors {
                            left: parent.left
                            right: parent.right
                            margins: Theme.paddingLarge

                        }
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    var value = list.model.get(index).value
                    console.log(value);
                }
            }
        }

        Component.onCompleted: {
            for(var i=0;i<=100;i++) {
                var myElement = { "value" : i }
                myJSModel.append(element)
            }
        }
    }

}

The myElement could be an arbitrary javascript object and we can add as many properties as needed and use them in our delegate.

We defined the JavaScript model in the Component.onCompleted event. By doing this our code is called when the associated components are ready and displayed.

Gridviews

The GridView acts in a similar way to the list view, sharing most of the properties.

import QtQuick 2.0
import Sailfish.Silica 1.0


Page {
    id: page

    SilicaGridView {
        id:list
        width: parent.width;
        height: parent.height

        cellWidth: width / 2
        cellHeight: width / 2

        model: ListModel {
           id: myJSModel

        }
        header: MyHeader {}
        delegate: Item {
            width: list.cellWidth
            height: list.cellHeight



            Label {
                text: value
                font.pixelSize: Theme.fontSizeMedium
                anchors {
                            left: parent.left
                            right: parent.right
                            margins: Theme.paddingLarge

                        }
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    var value = list.model.get(index).value
                    console.log(value);
                }
            }
        }

        Component.onCompleted: {
            for(var i=0;i<=100;i++) {
                var element = { "value" : i }
                myJSModel.append(element)
            }
        }
    }

}

We have to define two more properties that the list view, cellWidth and cellHeight that are self explanatory.

Conclusion

Lists and grids are popular but not always easy to implement.

Sailfish, thanks to QML, has one of the cleanest and most convenient APIs regarding these two crucial components, allowing a developer to achieve a usable UI without much effort.

I’d love to hear your thoughts and comments and if you’ve tried any Sailfish development yet.

Frequently Asked Questions (FAQs) about Lists and Grids for Displaying Data in Sailfish OS