• Home
• Felgo
• JsonListModel

JsonListModel

A proxy view model for JSON data sources. More...

• List of all members, including inherited members

Properties

• count : int
• fields : array
• keyField : string
• source : array

Methods

• void append(var value)
• var get(int index)
• int indexOf(string field, var value)
• void insert(int index, var item)
• void move(int from, int to, int n)
• void remove(int index, int count)
• void set(int index, var changes)
• void setProperty(int index, string property, var value)
• void syncModelToSource()

Detailed Description

JsonListModel allows to transform your JSON data into a QML ListModel for usage with e.g. an AppListView.

With Felgo, you develop apps using QML and JavaScript. This makes it easy to work with JSON data and REST APIs, as you can see with the examples of the Access a REST Service topic. But JSON objects are a variant data type. This means that there's no defined data structure that default UI components can expect. When you use this variant type as your data source for e.g. an AppListView, the list view is not able to fully utilize all its features.

For example, if individual data properties or list entries in your JSON data are modified, the list view can not track these changes. Thus, each modification of the data requires to recreate and redraw the list from scratch. Of course this is not ideal in terms of performance and user experience.

In addition, advanced features like list sections or transition animations are not available. The JsonListModel solves all these issues. It integrates QSyncable, a ListModel implementation by Ben Lau. You can also find the full project on GitHub.

The JsonListModel holds a local copy of the specified JSON data. Whenever the source JSON data changes, it is compared to the local copy of the model. After diffing the two sets of data, the JsonListModel applies all detected changes individually. It thus synchronizes the local copy with the JSON data step-by-step.

The JsonListModel type implements the full QML ListModel API and fires individual events for all changes in the data. The list view can thus only update relevant entries or apply transition animations. This is super useful, as you can e.g. fetch new data and simply replace the old JSON. The JsonListModel will detect all changes, and the ListView updates its items accordingly - without a full redraw.

The JsonListModel is backed by a performant QSyncable model in Qt C++ and exposed to QML for easy usage. With the JsonListModel you can:

• Fetch JSON data from REST APIs with QML and JavaScript.
• Pass the data to your C++ list model, which synchronizes the JSON data and prepares it for usage in your view.
• Show the model data with a list view in QML, which only renders list items that have changed.

With the JsonListModel you do not require to implement a custom model in C++ anymore. The JsonListModel itself is your C++ model, which is fully usable from QML and can work with JSON list items of any format.

Apart from list views, the model also supports the GridView and Repeater types to display model data.

Example Usage

Basic Demo Project

For a simple example project that uses JsonListModel to show data from a REST API, you can see the MVC Architecture Demo App.

Todo List Demo

The advanced ToDo List App supports fetching of todos, creation and storing of drafts, offline caching, paging, sorting and filtering. It uses list tranisition animations and shows how to integrate PullToRefreshHandler, VisibilityRefreshHandler or SortFilterProxyModel.

AppListView with Transition Animation

The following example shows how to use JsonListModel together with AppListView. When adding a new item to the JSON, the JsonListModel detects the change. The AppListView can thus use a transition animation when adding the entry. It is not required to fully redraw the list and exising items in the view are not affected.

 import Felgo
 import QtQuick

 App {
   AppPage {
     id: page

     // property with json data
     property var jsonData: [
       {
         "id": 1,
         "title": "Entry 1"
       },
       {
         "id": 2,
         "title": "Entry 2"
       },
       {
         "id": 3,
         "title": "Entry 3"
       }
     ]

     // list model for json data
     JsonListModel {
       id: jsonModel
       source: page.jsonData
       keyField: "id"
     }

     // list view
     AppListView {
       anchors.fill: parent
       model: jsonModel
       delegate: SimpleRow {
         text: model.title
       }

       // transition animation for adding items
       add: Transition {
         NumberAnimation {
           property: "opacity";
           from: 0;
           to: 1;
           duration: 1000
           easing.type: Easing.OutQuad;
         }
       }
     }

     // Button to add a new entry
     AppButton {
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.bottom: parent.bottom

       text: "Add Entry"
       onClicked: {
         var newItem = {
           "id": jsonModel.count + 1,
           "title": "Entry "+(jsonModel.count + 1)
         }
         page.jsonData.push(newItem)

         // manually emit signal that jsonData property changed
         // JsonListModel thus synchronizes the list with the new jsonData
         page.jsonDataChanged()
       }
     }
   } // Page
 }

To learn about ListView features in general, you can find more examples here: Use ScrollViews and ListViews in Your App.

Sorting, Filtering and List Sections

As the JsonListModel is a regular QML ListModel, it is compatible with SortFilterProxyModel and also supports list sections:

 import Felgo
 import QtQuick

 App {
   AppPage {
     id: page

     // property with json data
     property var jsonData: [
       {
         "id": 1,
         "title": "Apple",
         "type": "Fruit"
       },
       {
         "id": 2,
         "title": "Ham",
         "type": "Meat"
       },
       {
         "id": 3,
         "title": "Bacon",
         "type": "Meat"
       },
       {
         "id": 4,
         "title": "Banana",
         "type": "Fruit"
       }
     ]

     // list model for json data
     JsonListModel {
       id: jsonModel
       source: page.jsonData
       keyField: "id"
       fields: ["id", "title", "type"]
     }

     // SortFilterProxyModel for sorting or filtering lists
     SortFilterProxyModel {
       id: sortedModel
       // Note: when using JsonListModel, the sorters or filter might not be applied correctly when directly assigning sourceModel
       // use the Component.onCompleted handler instead to initialize SortFilterProxyModel
       Component.onCompleted: sourceModel = jsonModel
       sorters: LocaleAwareSorter { id: typeSorter; roleName: "type"; ascendingOrder: true }
     }

     // list view
     AppListView {
       anchors.fill: parent
       model: sortedModel
       delegate: SimpleRow {
         text: model.title
       }
       section.property: "type"
       section.delegate: SimpleSection { }
     }

     // Button change the sorting order
     AppButton {
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.bottom: parent.bottom

       text: "Change Order"
       onClicked: typeSorter.ascendingOrder = !typeSorter.ascendingOrder
     }
   } // Page
 }

To correctly have relevant model roles available for SortFilterProxyModel, make sure to specify all required JsonListModel::fields.

Property Documentation

 JsonListModel {
     keyField: "id"
     fields: [
         "id",
         "value"
     ]
 }

 JsonListModel {
     keyField: "id"

     source: [
         { "id": "a", "value": 1 },
         { "id": "b", "value": 2 }
     ]

     fields: [
         "id",
         "value"
     ]
 }

Method Documentation