Search code examples
azure-mapsazuremapscontrol

Can I add anything to Shape.Properties?

In the Azure Map API, the Shape object has add/get/setProperties. Can I use that to add a property I use when handling events on the shape?

And if so, any limits on what names I can use for the key? Is there a set of pre-defined keys that the atlas library is using?

And if I can't use this, what can I use to set an identifier on each shape (in my case they are "pins" in a shape layer).

Solution

  • Yes, you can add properties to the shape when an event occurs. Note that only DataSource's have Shape objects, and clusters will only be Feature types and aside from cluster aggregates, you can't add data to them.

    Not that GeoJSON features have an id property that you can use to set a unique identifier. When passed into a DataSource, it will try and honor that and the wrapped Shape object will have the same ID (Shape objects had a getId method). When create a Shape object, you can also set a unique ID at that time. If you don't a unique ID will be assigned to it automatically.

    In terms of limits:

    • Generally, don't use a name that starts with an underscore. That is typically used for private properties in JavaScript/JSON, and the map does add at least one of these to each Shape object ("_azureMapsShapeId" which is an internal ID for managing the shapes life cycle. If there is an ID on the original feature passed in, it usually will be the same. If no ID is on the original data, a GUID is used as the ID. All shapes need a unique ID). Odds are you won't run into any issue if you do use an underscore, but ideally you want to keep your property names shorter since they add to the overall size of the data.
    • If you want to update/add a lot of properties on a shape, use the getProperties method to get all the properties, update that object (add properties if needed), then use the setProperties method. This will trigger a single update in the map.
    • If you want to update properties in a lot of shapes in a DataSource (e.g. in a loop), the most efficient way to do this it to call the DataSource's toJson method which will return a GeoJSON FeatureCollection, loop over this and update as needed, then use the DataSource's SetShapes method to overwrite all the data in the data source with the updated data. Again this will trigger a single update in the map.