Place QML Type

The Place type represents a location that is a position of interest. More...

• List of all members, including inherited members

Properties

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• place : QPlace
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

Methods

• copyFrom(Place original)
• string errorString()
• void getDetails()
• initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Detailed Description

The Place type represents a physical location with additional metadata describing that location. Contrasted with Location, Address, and coordinate type which are used to describe where a location is. The basic properties of a Place are its name and location.

Place objects are typically obtained from a search model and will generally only have their basic properties set. The detailsFetched property can be used to test if further property values need to be fetched from the Plugin. This can be done by invoking the getDetails() method. Progress of the fetching operation can be monitored with the status property, which will be set to Place.Fetching when the details are being fetched.

The Place type has many properties holding information about the location. Details on how to contact the place are available from the contactDetails property. Convenience properties for obtaining the primary phone, fax, email and website are also available.

Each place is assigned zero or more categories. Categories are typically used when searching for a particular kind of place, such as a restaurant or hotel. Some places have a ratings object, which gives an indication of the quality of the place.

Place metadata is provided by a supplier who may require that an attribution message be displayed to the user when the place details are viewed.

Places have an associated icon which can be used to represent a place on a map or to decorate a delegate in a view.

Places may have additional rich content associated with them. The currently supported rich content include editorial descriptions, reviews and images. These are exposed as a set of models for retrieving the content. Editorial descriptions of the place are available from the editorialModel property. Reviews of the place are available from the reviewModel property. A gallery of pictures of the place can be accessed using the imageModel property.

Places may have additional attributes which are not covered in the formal API. The extendedAttributes property provides access to these. The type of extended attributes available is specific to each Plugin.

A Place is almost always tied to a plugin. The plugin property must be set before it is possible to call save(), remove() or getDetails(). The reviewModel, imageModel and editorialModel are only valid then the plugin property is set.

Saving a Place

If the Plugin supports it, the Place type can be used to save a place. First create a new Place and set its properties:

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

Then invoke the save() method:

    myPlace.save();

The status property will change to Place.Saving and then to Place.Ready if the save was successful or to Place.Error if an error occurs.

If the placeId property is set, the backend will update an existing place otherwise it will create a new place. On success the placeId property will be updated with the identifier of the newly saved place.

Caveats

The Places API is currently designed for only saving core details. Saving rich content like images and reviews or details like supplier and rating is not a supported use case. Typically a manager will generally ignore these fields upon save and may produce a warning message if they are populated.

The Places API only supports saving of the following core details:

• name
• place id
• location
• contact details
• icon
• categories (tag-like names to describe a place)
• visibility scope

It is possible that providers may only support a subset of these. See the plugin documentation for more details.

Saving of properties such as the rating, extended attributes, images, reviews, editorials and supplier is explicitly not supported by the Places API.

Saving Between Plugins

When saving places between plugins, there are a few things to be aware of. Some fields of a place such as the id, categories and icons are plugin specific entities. For example the categories in one manager may not be recognised in another. Therefore trying to save a place directly from one plugin to another is not possible.

It is generally recommended that saving across plugins be handled as saving favorites as explained in the Favorites section. However there is another approach which is to create a new place, set its (destination) plugin and then use the copyFrom() method to copy the details of the original place. Using copyFrom() only copies data that is supported by the destination plugin, plugin specific data such as the place identifier is not copied over. Once the copy is done, the place is in a suitable state to be saved.

The following snippet provides an example of saving a place to a different plugin using the copyFrom method:

place = Qt.createQmlObject('import QtLocation 5.3; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Removing a Place

To remove a place, ensure that a Place object with a valid placeId property exists and call its remove() method. The status property will change to Place.Removing and then to Place.Ready if the save was successful or to Place.Error if an error occurs.

Favorites

The Places API supports the concept of favorites. Favorites are generally implemented by using two plugins, the first plugin is typically a read-only source of places (origin plugin) and a second read/write plugin (destination plugin) is used to store places from the origin as favorites.

Each Place has a favorite property which is intended to contain the corresponding place from the destination plugin (the place itself is sourced from the origin plugin). Because both the original place and favorite instances are available, the developer can choose which properties to show to the user. For example the favorite may have a modified name which should be displayed rather than the original name.

Text { text: place.favorite ? place.favorite.name : place.name }

The following demonstrates how to save a new favorite instance. A call is made to create/initialize the favorite instance and then the instance is saved.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

The following demonstrates favorite removal:

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

The PlaceSearchModel has a favoritesPlugin property. If the property is set, any places found during a search are checked against the favoritesPlugin to see if there is a corresponding favorite place. If so, the favorite property of the Place is set, otherwise the favorite property is remains null.

See also PlaceSearchModel.

Property Documentation

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

Method Documentation