Mappedin Class
Constructor
-
options
Parameters:
-
options
ObjectInitialization options.
-
[clientId]
String optionalThe client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one.
-
[clientSecret]
String optionalThe secret/password that goes along with your ID.
-
[accessToken]
String optionalOAuth access token.
-
perspective
StringThe 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 optionalLanguage name (e.g. en-US).
-
things
ObjectThe 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] optionalThe Polygon fields you want. The default is probably sufficient. -
[nodes]
[String] optionalThe Node fields you want. The default is probably sufficient.
-
-
venue
StringVenue 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:
- One of Mappedin.test3D (typical), .forceTest, .force3D, or .force2D to put the MapView into either 2D or 3D mode.
- Mappedin.init to download all of the data you need from the Mappedin API.
- 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.
Methods
Properties
- categories
- collectionType static
- events
- locations
- mapGroups
- maps
- modes static
- nodes
- polygons
- vortexes
-
callback
Forces Mapview into 2D mode.
Parameters:
-
callback
FunctionThe function to call when the Mapview is finished loading.
-
callback
Forces Mapview into 3D mode.
Parameters:
-
callback
FunctionThe function to call when 3D mode is ready.
-
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
DivThe 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
FunctionThe 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
FunctionFunction to call with test results, typically used to switch map modes.
-
name
-
id
Gets an object (Node, Polygon, etc.) if it exists within the Venue by looking up its Mappedin ID or External ID.
Parameters:
-
name
CollectionTypecollectionType to look up the ID from that collection.
-
id
StringEither Mappedin ID or External ID.
Returns:
-
options
A one stop function to download all of the information you need for a given MappedinVenue.
Parameters:
-
options
ObjectInitialization options.
-
[clientId]
String optionalOAuth client ID.
-
[clientSecret]
String optionalOAuth client secret.
-
[accessToken]
String optionalOAuth access token.
-
[perspective]
String optionalPerspective name.
-
[language]
String optionalLanguage name (e.g. en-US).
-
things
ObjectThe 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] optionalThe Polygon fields you want. The default is probably sufficient. -
[nodes]
[String] optionalThe Node fields you want. The default is probably sufficient.
-
-
venue
StringVenue ID.
-
Returns:
-
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
ObjectAny options you need to specify to talk to the Mappedin API.
-
clientId
StringThe client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one.
-
clientSecret
StringThe secret/password that goes along with your ID.
-
perspective
StringThe 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.
-
venue
StringThe "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
ObjectThe 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] optionalThe Polygon fields you want. The default is probably sufficient. -
[nodes]
[String] optionalThe Node fields you want. The default is probably sufficient.
-
-
-
mode
Stringone of Mappedin.modes.
-
callback
FunctionThis function is called when the Venue data is loaded, or there is a problem.
-
error
StringIf 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
MappedinA 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.
-
-
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
ObjectAny options you need to specify to talk to the Mappedin API
-
clientId
StringThe client key/ID provided to you by Mappedin to access our API. Contact your Mappedin representative if you do not have one
-
clientSecret
StringThe secret/password that goes along with your ID
-
perspective
StringThe 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.
-
venue
StringThe "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
ObjectThe 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] optionalThe Polygon fields you want. The default is probably sufficient. -
[nodes]
[String] optionalThe Node fields you want. The default is probably sufficient.
-
-
-
mode
StringOne of Mappedin.modes.
-
callback
FunctionThis function is called when the Venue data is loaded, or there is a problem.
-
error
StringIf 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
MappedinA 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
-
-
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
ObjectTakes 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
ObjectAny options from Mappedin.getVenue
-
mapview
ObjectAny options from the Mappedin.MapView constructor
-
search
ObjectAny options from the Mappedin.Seach constructor.
-
firstMapSelector
FunctionIf 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
DivThe HTML element the Mapview will live in.
-
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
ObjectTakes 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
ObjectAny options from Mappedin.getVenue.
-
mapview
ObjectAny options from the MapView constructor.
-
search
ObjectAny options from the Search constructor.
-
firstMapSelector
FunctionIf 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
DivThe HTML element the Mapview will live in.
-
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
DivThe 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
FunctionThe 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
FunctionFunction to call with test results, typically used to switch map modes.
collectionType
CATEGORY, EVENT, LOCATION, MAPGROUP, MAP, NODE, POLYGON, VENUE, VORTEX const staticThe possible types of collections of objects you can get from the Venue. To be used to look up items using getCollectionItemById.
modes
TEST, 3D, 2D, FORCE_TEST const staticThe 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.