Constructor

.Mappedin
(
  • options
)
static

Parameters:

  • options Object

    Initialization options.

    • [clientId] String optional

      The client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one.

    • [clientSecret] String optional

      The secret/password that goes along with your ID.

    • [accessToken] String optional

      OAuth access token.

    • perspective String

      The name of the perspective you are using for 2D and 3D. Probably "Website". This controls what 3D files or 2D tiles get downloaded, and different persepctives may have different map features enabled/disabled, or have different images.

    • [language] String optional

      Language name (e.g. en-US).

    • things Object

      The things object is where you specify what fields you want to download for each object in the Mappedin API. Only specify what you will actually use, to minmimze transfer time. This SDK will ensure it has the 2D or 3D files it needs, and id is always included, but it won't download anything extra (like the names of locations) unless you specify it here.

      • venue [String]
        The Venue information you want. 'slug' and 'name' are typical, but you may also want others. Speak to Mappedin to see what is available.
      • locations [String]
        The fields you will be using for any Locations. You probably want at least 'name' and 'type'. You will also probably want 'description' and 'logo', but there can be any number of Location properties and it depends on your Venue and usecase. Talk to Mappedin for more details.
      • categories [String]
        The fields you will use for each Category. Typically 'name' at a minimum, but other common fields are 'description', 'picture', 'sortOrder' or 'parents' (for hierarchical categories) as well.
      • maps [String]
        The fields on each Map you are interested in. You'll probably want one or both of 'name' or 'shortName', and 'elevation' to sort.
      • [polygons] [String] optional
        The Polygon fields you want. The default is probably sufficient.
      • [nodes] [String] optional
        The Node fields you want. The default is probably sufficient.
    • venue String

      Venue ID.

Contains the functions you need to start the MapView. Typically you will just use Mappedin.initialize, which does all this for you, but for special cases your flow should look like this:

  1. One of Mappedin.test3D (typical), .forceTest, .force3D, or .force2D to put the MapView into either 2D or 3D mode.
  2. Mappedin.init to download all of the data you need from the Mappedin API.
  3. new Mappedin.MapView, which will create the MapView and display the default MappedinMap.

Each of those functions has a callback which you should use to trigger the next step. Once you get the final callback from the MapView constructor, you can hide any loading screen UI and do whatever you want.

Show:
force2D
(
  • callback
)

Forces Mapview into 2D mode.

Parameters:

  • callback Function

    The function to call when the Mapview is finished loading.

force3D
(
  • callback
)

Forces Mapview into 3D mode.

Parameters:

  • callback Function

    The function to call when 3D mode is ready.

forceTest
(
  • container
  • callback
  • loadMapViewByMode
)

Forces the Mapview to perform it's 3D test. It attempts to save the result the test is not run again on subsequent loads. This lets you override that behaviour. The callback will be executed when the test is complete and either the 2D or 3D Mapview is loaded.

Parameters:

  • container Div

    The div to run the test in. Works best if it's the same as where the MapView will go, as the number of pixels being rendered is a factor.

  • callback Function

    The function to call when the test is complete and either 2D or 3D mode is ready. The callback will be fired with a result key, a boolean that will be true if you are in 3D mode, and the result of the benchmark.

  • loadMapViewByMode Function

    Function to call with test results, typically used to switch map modes.

getCollectionItemById
(
  • name
  • id
)
Object

Gets an object (Node, Polygon, etc.) if it exists within the Venue by looking up its Mappedin ID or External ID.

Parameters:

  • name CollectionType

    collectionType to look up the ID from that collection.

  • id String

    Either Mappedin ID or External ID.

Returns:

getVenue
(
  • options
)
Mappedin

A one stop function to download all of the information you need for a given MappedinVenue.

Parameters:

  • options Object

    Initialization options.

    • [clientId] String optional

      OAuth client ID.

    • [clientSecret] String optional

      OAuth client secret.

    • [accessToken] String optional

      OAuth access token.

    • [perspective] String optional

      Perspective name.

    • [language] String optional

      Language name (e.g. en-US).

    • things Object

      The things object is where you specify what fields you want to download for each object in the Mappedin API. Only specify what you will actually use, to minmimze transfer time. This SDK will ensure it has the 2D or 3D files it needs, and id is always included, but it won't download anything extra (like the names of locations) unless you specify it here.

      • venue [String]
        The Venue information you want. 'slug' and 'name' are typical, but you may also want others. Speak to Mappedin to see what is available.
      • locations [String]
        The fields you will be using for any Locations. You probably want at least 'name' and 'type'. You will also probably want 'description' and 'logo', but there can be any number of Location properties and it depends on your Venue and usecase. Talk to Mappedin for more details.
      • categories [String]
        The fields you will use for each Category. Typically 'name' at a minimum, but other common fields are 'description', 'picture', 'sortOrder' or 'parents' (for hierarchical categories) as well.
      • maps [String]
        The fields on each Map you are interested in. You'll probably want one or both of 'name' or 'shortName', and 'elevation' to sort.
      • [polygons] [String] optional
        The Polygon fields you want. The default is probably sufficient.
      • [nodes] [String] optional
        The Node fields you want. The default is probably sufficient.
    • venue String

      Venue ID.

Returns:

getVenue
(
  • options
  • mode
  • callback
)

Once you are in 2D or 3D mode, call this function with the options you need for the Mappedin API, and a callback that will give you a MappedinVenue populated with all your data.

The things object parameter is where you specify what fields you want to download for each object in the Mappedin API. This SDK will ensure it has the 2D or 3D files it needs, but it won't download anything extra (like the names of locations) unless you specify it here. This is a typical minimum, though you may have more location properties you are interested in. Talk to Mappedin for more information.

things: {
      venue: ['slug', 'name'],
      locations: ['name', 'type', 'description', 'icon', 'logo'],
      categories: ['name'],
      maps: ['name', 'elevation', 'shortName']
  }
  

If you would like to force the test to run again, use the forceTest method instead. Or, if you want to force the user into a specific mode, use force2D or force3D respectively. Note while 2D should work for basically anyone, if the user's device/browser does not support WebGL and you call force3D, you will get an exception when you create a MapView object.

Parameters:

  • options Object

    Any options you need to specify to talk to the Mappedin API.

    • clientId String

      The client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one.

    • clientSecret String

      The secret/password that goes along with your ID.

    • perspective String

      The name of the perspective you are using for 2D and 3D. Probably "Website". This controls what 3D files or 2D tiles get downloaded, and different persepctives may have different map features enabled/disabled, or have different images.

      • [perspective2D] String optional
        Use if you have a different perspective to use in 2D mode.
      • [perspective3D] String optional
        Use if you have a different perspective to use in 3D mode.
    • venue String

      The "slug" that identifies the specific Venue you are interested in. Mappedin can tell you what it is. Developer accounts often start with "api-demo1".

    • things Object

      The things object is where you specify what fields you want to download for each object in the Mappedin API. Only specify what you will actually use, to minmimze transfer time. This SDK will ensure it has the 2D or 3D files it needs, and id is always included, but it won't download anything extra (like the names of locations) unless you specify it here.

      • venue [String]
        The Venue information you want. 'slug' and 'name' are typical, but you may also want others. Speak to Mappedin to see what is available.
      • locations [String]
        The fields you will be using for any Locations. You probably want at least 'name' and 'type'. You will also probably want 'description' and 'logo', but there can be any number of Location properties and it depends on your Venue and usecase. Talk to Mappedin for more details.
      • categories [String]
        The fields you will use for each Category. Typically 'name' at a minimum, but other common fields are 'description', 'picture', 'sortOrder' or 'parents' (for hierarchical categories) as well.
      • maps [String]
        The fields on each Map you are interested in. You'll probably want one or both of 'name' or 'shortName', and 'elevation' to sort.
      • [polygons] [String] optional
        The Polygon fields you want. The default is probably sufficient.
      • [nodes] [String] optional
        The Node fields you want. The default is probably sufficient.
  • mode String

    one of Mappedin.modes.

  • callback Function

    This function is called when the Venue data is loaded, or there is a problem.

    • error String

      If there is an error, you will get it here. Typically this will only be useful for developers when building/testing. It's not usually something a user can deal with.

    • result Mappedin

      A Mappedin data object with all the data you asked for. It will have a Venue property with a Venue object, and Locations, Categories, Nodes, Maps, and Polygons arrays.

getVenue
(
  • options
  • mode
  • callback
)

Once you are in 2D or 3D mode, call this function with the options you need for the Mappedin API, and a callback that will give you a Venue object populated with all your data.

The things object parameter is where you specify what fields you want to download for each object in the Mappedin API. This SDK will ensure it has the 2D or 3D files it needs, but it won't download anything extra (like the names of locations) unless you specify it here. This is a typical minimum, though you may have more location properties you are interested in. Talk to Mappedin for more information.

things: {
      venue: ['slug', 'name'],
      locations: ['name', 'type', 'description', 'icon', 'logo'],
      categories: ['name'],
      maps: ['name', 'elevation', 'shortName']
  }
  

If you would like to force the test to run again, use the forceTest method instead. Or, if you want to force the user into a specific mode, use force2D or force3D respectively. Note while 2D should work for basically anyone, if the user's device/browser does not support WebGL and you call force3D, you will get an exception when you create a MapView object.

Parameters:

  • options Object

    Any options you need to specify to talk to the Mappedin API

    • clientId String

      The client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one

    • clientSecret String

      The secret/password that goes along with your ID

    • perspective String

      The name of the perspective you are using for 2D and 3D. Probably "Website". This controls what 3D files or 2D tiles get downloaded, and different persepctives may have different map features enabled/disabled, or have different images.

      • [perspective2D] String optional
        Use if you have a different perspective to use in 2D mode
      • [perspective3D] String optional
        Use if you have a different perspective to use in 3D mode
    • venue String

      The "slug" that identifies the specific Venue you are interested in. Mappedin can tell you what it is. Developer accounts often start with "api-demo1"

    • things Object

      The things object is where you specify what fields you want to download for each object in the Mappedin API. Only specify what you will actually use, to minmimze transfer time. This SDK will ensure it has the 2D or 3D files it needs, and id is always included, but it won't download anything extra (like the names of locations) unless you specify it here.

      • venue [String]
        The Venue information you want. 'slug' and 'name' are typical, but you may also want others. Speak to Mappedin to see what is available.
      • locations [String]
        The fields you will be using for any Locations. You probably want at least 'name' and 'type'. You will also probably want 'description' and 'logo', but there can be any number of Location properties and it depends on your Venue and usecase. Talk to Mappedin for more details.
      • categories [String]
        The fields you will use for each Category. Typically 'name' at a minimum, but other common fields are 'description', 'picture', 'sortOrder' or 'parents' (for hierarchical categories) as well.
      • maps [String]
        The fields on each Map you are interested in. You'll probably want one or both of 'name' or 'shortName', and 'elevation' to sort.
      • [polygons] [String] optional
        The Polygon fields you want. The default is probably sufficient.
      • [nodes] [String] optional
        The Node fields you want. The default is probably sufficient.
  • mode String

    One of Mappedin.modes.

  • callback Function

    This function is called when the Venue data is loaded, or there is a problem.

    • error String

      If there is an error, you will get it here. Typically this will only be useful for developers when building/testing. It's not usually something a user can deal with.

    • result Mappedin

      A Mappedin data object with all the data you asked for. It will have a venue property with a Venue object, and locations, categories, nodes, maps, and polygons arrays

initialize
(
  • options
  • container
)

This function will take a single options object combining all options for Mappedin.init and the MapView constructor, and the div the MapView should live in. It returns a Promise that will resolve with the MapView once the 3D test has been performed, the right MapView was loaded, the data has been retrieved from the Mappedin API, and the MapView has been created. It could also fail (mostly if the options you set for the Mappedin API are incorrect).

This is a convenience function that lets you avoid chaining a bunch of callbacks, calling test3D/force2D/force3D then Mappedin.init then the MapView constructor.

Parameters:

  • options Object

    Takes an object combining all options from Mappedin.init, the MapView constructor, and the Search constructor. If you explictly want to set the 3D mode rather than run the test, it also accepts a mode property that can be any of Mappedin.mode

    • venue Object

      Any options from Mappedin.getVenue

    • mapview Object

      Any options from the Mappedin.MapView constructor

    • search Object

      Any options from the Mappedin.Seach constructor.

    • firstMapSelector Function

      If you would like to pick the first map loaded, set this function. It gives you a Venue object, and expects a Mappedin Map or Map Id to be returned. Return venue.defaultMap for the default behaviour. If you return an invalid map, an error will be logged to the console and an arbitrary map will be loaded.

  • container Div

    The HTML element the Mapview will live in.

initialize
(
  • options
  • container
)

This function will take a single options object combining all options for Mappedin.init and the MapView constructor, and the div the MapView should live in. It returns a Promise that will resolve with the MapView once the 3D test has been performed, the right MapView was loaded, the data has been retrieved from the Mappedin API, and the MapView has been created. It could also fail (mostly if the options you set for the Mappedin API are incorrect).

This is a convenience function that lets you avoid chaining a bunch of callbacks, calling test3D/force2D/force3D then Mappedin.init then the MapView constructor.

Parameters:

  • options Object

    Takes an object combining all options from Mappedin.init, the MapView constructor, and the Search constructor. If you explictly want to set the 3D mode rather than run the test, it also accepts a mode property that can be any of Mappedin.modes.

    • venue Object

      Any options from Mappedin.getVenue.

    • mapview Object

      Any options from the MapView constructor.

    • search Object

      Any options from the Search constructor.

    • firstMapSelector Function

      If you would like to pick the first Map loaded, set this function. It gives you a MappedinVenue object, and expects a MappedinMap or Map Id to be returned. Return venue.defaultMap for the default behaviour. If you return an invalid Map, an error will be logged to the console and an arbitrary Map will be loaded.

  • container Div

    The HTML element the Mapview will live in.

test3D
(
  • container
  • callback
  • loadMapViewByMode
)

This is the typical function to call before instatiating a MapView. It will either perform a test to determine if the current device is capable of running in 3D mode, and store the results, or if prior results are available, just use those. Then, it will setMapView to be the constructor for the proper mode. This lets the developer write their website without having to know or care whether the user is experiencing it in 2D or 3D. The callback you pass into the function will give you the results, however, if you care, and you can also determine it from the type property on the MapView you create.

If you would like to force the test to run again, use the forceTest method instead. Or, if you want to force the user into a specific mode, use force2D or force3D respectively. Note while 2D should work for basically anyone, if the user's device/browser does not support WebGL and you call force3D, you will get an exception when you create a MapView object.

Parameters:

  • container Div

    The div to run the test in. Works best if it's the same as where the MapView will go, as the number of pixels being rendered is a factor.

  • callback Function

    The function to call when the test is complete and either 2D or 3D mode is ready. The callback will be fired with a result key, a boolean that will be true if you are in 3D mode, and the result of the benchmark.

  • loadMapViewByMode Function

    Function to call with test results, typically used to switch map modes.

categories

[MappedinCategory]

Collection of all Categories within the Venue.

collectionType

CATEGORY, EVENT, LOCATION, MAPGROUP, MAP, NODE, POLYGON, VENUE, VORTEX const static

The possible types of collections of objects you can get from the Venue. To be used to look up items using getCollectionItemById.

events

[MappedinEvent]

Collection of all Events within the Venue.

locations

[MappedinLocation]

Collection of all Locations within the Venue.

mapGroups

[MappedinMapGroup]

Collection of all MapGroups within the Venue.

maps

[MappedinMap]

Collection of all Maps within the Venue.

modes

TEST, 3D, 2D, FORCE_TEST const static

The possible modes MapView can be in. Typically you will use TEST, which will run a 3D compatibility test the user loads the page and then load load either the 2D or 3D version of MapView. On subsequent loads, it will use the saved result to avoid running a new test. FORCE_TEST will make sure a new test is run and the results are saved, whereas 3D and 2D will force the MapView directly into 2D or 3D mode without checking for compatibility. 2D should always work but some browsers/devices do not have the WebGL support needed for 3D, so be careful.

nodes

[MappedinNode]

Collection of all Nodes within the Venue.

polygons

[MappedinPolygon]

Collection of all Polygons within the Venue.

vortexes

[MappedinVortex]

Collection of all Vortexes within the Venue.