QuickStart Background

The QuickStart Library and sample application was built to satisfy a few key requirements of non-GIS developers who find themselves approaching mapping and location in their app for the first time.

Target Developers

Esri does a good job of embracing existing Esri developers. The Runtimes, APIs, and the platform as a whole have common patterns and consistent naming, and no-one can deny that the runtimes and APIs breathe GIS. But for a non-GIS developer the learning curve can be quite steep.

These are developers who want to download the SDK, put a map control in their project, and display a map. If they can't see that in a matter of minutes, they're put off learning the more complex and powerful aspects of the platform. But if they do get to add Esri's maps to their app then suddenly they can explore and innovate with the real power that the platform and runtimes expose.

QuickStart Aims

Key points the QuickStart Library aims to tackle are:

• Hide service URLs
• Hide spatial references
• Use Lat/Lon
• Use Zoom levels (1-20)
• Switchable Basemaps
• Map Annotations (Put a pin on a map)

And we try to reduce to a single line coding pattern where possible.

The QuickStart Library guides the developer to the more advanced concepts of the platform by letting them address some common use-cases without learning a lot up-front. Effectively, it tries to reshape the learning curve.

It's also important to note that the QuickStart Library doesn't subclass AGS classes or change any platform patterns. Throughout, new developers are exposed to core AGS classes, objects and patterns.

Hide Service URLs

Service URLs are well-enough defined for beginning use-cases that they needn't be exposed to developers. Basemap, Geocoder and Routing URLs don't really change, so can be hidden.

The QuickStart Library provides functions like:

  [self.mapView setBasemap:EQSBasemapTypeTopographic];

  [self.mapView.geoServices findPlaces:searchString withinEnvelope:self.mapView.visibleAreaEnvelope];

  [self.mapView.geoServices findAddressFromPoint:mapPoint];

  [self.mapView.geoServices findDirectionsFrom:startPoint to:endPoint];

Hide Spatial References and use Lat/Lon

For web and mobile applications not heavy on GIS, developers want to talk lat/lon (WGS84) with "Web Maps" (Web Mercator Aux Sphere).

There's a lot that can be done with a map before the need to get to Spatial References.

The QuickStart Library aims to allow interaction with the map without exposing spatial references. Of course, they're still there, but the developer doesn't have to understand them or even reference them until later, allowing code like:

  [self.mapView centerAtLat:40.7302 Long:-73.9958 animated:NO];

  AGSPoint *nyc = [AGSPoint pointFromLat:40.7302 lon:-73.9958];

Note, the nyc point above is Web Mercator, like the map, but has readable latitude and longitude properties on it.

Zoom Levels

Typical "Web Maps" have a zoom level - a number between 1 and 20. The QuickStart Library complements core AGSMapView navigation by providing methods like

  [self.mapView zoomToLevel:7 animated:NO];

  [self.mapView zoomToLevel:13 withLat:40.7302 lon:-73.9958 animated:NO];

Switchable Basemaps

We saw earlier how we hide the URL(s) behind basemaps. We provide an enumeration of basemap types and handle the transitions between them behind the scenes.

typedef enum {
    EQSBasemapTypeStreet = 1,
    EQSBasemapTypeSatellite = 2,
    EQSBasemapTypeHybrid = 3,
    EQSBasemapTypeCanvas = 4,
    EQSBasemapTypeNationalGeographic = 5,
    EQSBasemapTypeTopographic = 6,
    EQSBasemapTypeOpenStreetMap = 7,
    
    EQSBasemapTypeFirst = EQSBasemapTypeStreet,
    EQSBasemapTypeLast = EQSBasemapTypeOpenStreetMap
} EQSBasemapType;

The developer sets or changes the basemap with

  [self.mapView setBasemap:EQSBasemapTypeTopographic];

And the QuickStart library hides the notion of WebMaps, Basemap Layers on WebMaps and so forth from the developer.

Map Annotations (Graphics)

To add graphics to a map, the developer usually has to create a graphics layer and add graphics to that layer. This process can be wrapped and abstracted to the AGSMapView, so that graphics become annotations on a map (rather than annotations on a layer on a map). It's a subtle difference, but covers a lot of straightforward use-cases. Very often the user just wants to bring up a map and "put a pin on it".

  AGSGraphic *g = [self.mapView addPoint:geoLocation withSymbol:self.mapView.defaultSymbols.geolocation];

The QuickStart Library takes care of creating graphics layers, of creating the graphic, of setting its symbol, and of adding it to the graphics layer. The whole process abstracts to "A graphic on the map" and the developer doesn't have to worry about setting up and managing graphics layers.

Single Line Coding Patterns

Throughout the QuickStart Library, the effort is to bring things to a single line pattern if possible. Get directions. Add a pin to the map. Zoom to a place. Set the basemap. Find Paris.