DataSource

Since: BlackBerry 10.0.0

#include <bb/data/DataSource>

To link against this class, add the following line to your .pro file: LIBS += -lbbdata

Provides access to data from an external data source.

The DataSource class lets you access data from a local data source, such as a JSON file, XML file or SQL database. It can also be used to access remote JSON or XML data using an HTTP data source URL. You can use this class in C++ code as well as QML, but it is specifically intended to make it easier to load data in QML.

Internally, this class makes use of classes such as JsonDataAccess, SqlDataAccess, XmlDataAccess and QNetworkAccessManager to perform the work.

The properties source, query, type and remote will allow the location and the type of data to be specified and whether the source is remote or local.

For example, to load data from an SQL table into a list using a DataSource in QML, follow these steps:
  1. Start with an application containing QML code that defines a ListView within a Page, as well as a GroupDataModel that's associated with the ListView.

  2. In the QML source file:
    1. Add an import statement: "import bb.data 1.0"

    2. Add a DataSource below the definition of your data model as an attached object.

    3. Add code in DataSource.onDataLoaded to connect the DataSource to the data model.

    4. Trigger loading by calling DataSource.load() from Page.onCreationCompleted().

    5. Specify the fields to display in the list items by adding binding code in the ListView.

Here is an example of the QML code required:

import bb.cascades 1.0
import bb.data 1.0

Page {
  content: ListView {
    id: myListView
    dataModel: dataModel
    listItemComponents: [
      ListItemComponent {
        type: "item"
        StandardListItem {
           title: ListItemData.firstname + " " + ListItemData.lastname
           imageSource: "asset:///" + ListItemData.image
           description: ListItemData.title
        }
      }
    ]
  //...
  }
  attachedObjects: [
    GroupDataModel {
      id: dataModel
    },
    DataSource {
      id: dataSource
      source: "sql/contacts1k.db"
      query: "select * from contact order by firstname, lastname"
      onDataLoaded: {
        dataModel.insertList(data);
      }
    }
  ]
  onCreationCompleted: { dataSource.load(); }
}


Overview

Public Functions Index

DataSource (QObject *parent=0)
virtual ~DataSource ()
Q_SLOT voidabort ()
Q_SLOT voidload ()
QStringquery () const
boolremote () const
Q_SLOT voidsetQuery (const QString &query)
Q_SLOT voidsetRemote (bool remote)
Q_SLOT voidsetSource (const QUrl &source)
Q_SLOT voidsetType (bb::data::DataSourceType::Type type)
QUrlsource () const
bb::data::DataSourceType::Typetype () const

Static Public Functions Index

Signals Index

voiddataLoaded (const QVariant &data)
voiderror (bb::data::DataAccessErrorType::Type errorType, const QString &errorMessage)
voidqueryChanged (QString query)
voidremoteChanged (bool remote)
voidsourceChanged (QUrl source)
voidtypeChanged (bb::data::DataSourceType::Type newType)

Properties

QString query

The query property contains an SQL query statement or an XML path.

An SQL select could be something like: "select * from contacts"

An XML path will identify a path to the subset of XML data which is of interest. For example, performing a load operation using a path such as "/contacts/contact" will return the repeating list of <contact> elements in XML such as this:
<contacts version="1.0">
    <contact>
        <id>1</id>
        <title>Sr. Editor</title>
        <firstname>Mike</firstname>
        <lastname>Chepesky</lastname>
    </contact>
    <contact>
        <id>2</id>
        <title>Talent Scout</title>
        <firstname>Westlee</firstname>
        <lastname>Barichak</lastname>
    </contact>
    ...
</contacts>
Since:

BlackBerry 10.0.0

bool remote

If true the data is at a remote source otherwise it is local.

The value of this property can usually be inferred from the source. If the source url scheme is "http" then remote is assumed. If remote the data is loaded using network access.

Otherwise, the value for remote will be false unless it is set using this property.

Since:

BlackBerry 10.0.0

QUrl source

The path to the external data source.

In QML, this path is relative to the QML document in which this DataSource is declared. When setting this property from C++, this path is instead relative to the application working directory.

Since:

BlackBerry 10.0.0

bb::data::DataSourceType::Type type

The type of data source.

The value of this property is usually inferred from the query property or the format of the data content associated with source.

Note that for remote data the type cannot be determined from the data content until the data is loaded.

The type is Xml if the query property contains a query path such as "/contacts/contact" or the query path is empty but the source data is in XML format.

The type is Sql if the query property contains an SQL select statement.

The type is Json if the source data is in JSON format.

Otherwise, the type will be "Unknown" unless it is set using this property.

Since:

BlackBerry 10.0.0

Public Functions

DataSource (

Constructs a DataSource object with the specified parent.

If the parent is not 0, ownership of this object will be transferred to the parent.

Parameters
parent

The parent owner or 0. Optional and will default to 0 if not specified.

Since:

BlackBerry 10.0.0

virtual~DataSource ()

Destructor.

Since:

BlackBerry 10.0.0

Q_SLOT void abort ()

Abort the current load operation if a network download is in progress.

This will not abort synchronous load operations such as loading from a local file. If a load operation is aborted an error signal will be omitted.

Q_SLOT void load ()

Loads the data from the data source.

Since:

BlackBerry 10.0.0

QString query ()

Gets the current value of the query property.

Return:

The query to use with this data source.

Since:

BlackBerry 10.0.0

bool remote ()

Gets the current value of the remote property.

Return:

True if the data source is remote and false if it is local.

Since:

BlackBerry 10.0.0

Q_SLOT void setQuery (

Sets a new query to use with this data source.

Parameters
query

The new query to use.

Since:

BlackBerry 10.0.0

Q_SLOT void setRemote (
  • boolremote)

Sets a new value for the remote property.

Normally the remote value is inferred from the source url and does not need to be explicitly set by the user of this class. See the remote property above for the rules.

Parameters
remote

True if the data source is remote and false if it is local.

Since:

BlackBerry 10.0.0

Q_SLOT void setSource (

Sets a new path to the external data source.

Parameters
source

The new path of the external data source.

Since:

BlackBerry 10.0.0

Q_SLOT void setType (

Sets a new type to use with this SQL data source.

Typically, the type is inferred from other information and does not need to be explicitly set when you use this class. See the type property above for the rules.

Parameters
type

The data source type.

Since:

BlackBerry 10.0.0

QUrl source ()

Gets the current value of the source property.

Return:

The current path to the external data source.

Since:

BlackBerry 10.0.0

bb::data::DataSourceType::Type type ()

Gets the current value of the type property.

Return:

The type of data for the data source based on the DataSourceType::Type enumeration.

Since:

BlackBerry 10.0.0

Static Public Functions

void registerQmlTypes ()

Deprecated.

Registers DataSource and related classes for use in QML.

Deprecated

No longer needed as a QML plugin is used to do the registration instead.

Since:

BlackBerry 10.0.0

Signals

void dataLoaded (

Emitted when new data is loaded.

Depending on the type of data and how it's loaded, the data passed by this signal can be either a QVariantList or a QVariantMap.

For SQL data, this signal always passes a QVariantList containing a QVariantMap for each item.

For JSON data, this signal passes either a QVariantList or a QVariantMap depending on the top-most JSON type used in the input data (QVariantList if it's an array, and QVariantMap if it's an object).

For XML data, this signal passes either a QVariantList or a QVariantMap depending on how the data is loaded, and the amount of data:
  • If you don't specify a queryPath, the data will be a QVariantMap representing the entire document.

  • If you do specify a queryPath, and the path refers to a non-repeating XML element, the data will be a QVariantMap containing the single item.

  • If you do specify a queryPath, and the path refers to a repeating XML element, the data will be a QVariantList (if the actual data contains more than one repetition) or a QVariantMap (if the actual data contains only one repetitiion).

Parameters
data

The new data that was loaded.

Since:

BlackBerry 10.0.0

void error (

Emitted when data failed to load and generated an error.

Parameters
errorType

The type of error that was generated.

errorMessage

The detailed error message.

Since:

BlackBerry 10.0.0

void queryChanged (

Emitted when the query property changes.

Parameters
query

The new query to use.

void remoteChanged (
  • boolremote)

Emitted when the remote property changes.

Parameters
remote

The new value for remote property.

Since:

BlackBerry 10.0.0

void sourceChanged (

Emitted when the source property changes.

Parameters
source

The new path of the external data source.

Since:

BlackBerry 10.0.0

void typeChanged (

Emitted when the type property changes.

Note:

Due to a workaround for a Qt Core issue with accessing enumerations from QML, the argument of this signal doesn't follow naming convention for signals, in which the signal arguments are typically named to match the associated property's name. To avoid runtime errors, use the object's property to access current property value instead of the signal argument (use type instead of newType).

Parameters
newType

The new type to use.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus