Information Technology

API

Warning: This API has not be extensively tested at this time.

The API (Application Programming Interface) allows programmers to access the aMapAppObject from their own code rather than depending on the user interface.  At the moment the API for the application is fairly limited, but we expect to be adding to it as we become aware of needs and desires.

This page is intended for programmers.  Non-programmers will find it neither interesting or useful and should skip it.

When the page designer creates the aMapApp3 application, they assign the application object to a variable,

myMapApp = new aMapAppObject(…);

We will use myMapApp in the examples below, but you can use any name you wish. The API consists of calls to methods in the aMapAppObject.  At the moment, with one major exception, no properties of the object are intended for direct manipulation.  To use any of the object methods the programmer could write myMapApp.name_of_API_function(). 

Accessing the map

The major exception to the rule of not accessing properties in the Google map itself.  The map exists as a property named, imaginatively, “map”. By using myMapApp.map you can access any of the properties and methods that are available to the Google map API.  This API is defined by Google at http://code.google.com/apis/maps/documentation/reference.html.

For example, let’s assume that you want your script to change the zoom factor for the map to level 9.  Your script would include the line,

myMapApp.map.setZoom(9);

Change the constant to a variable and you have a powerful way to adjust the map.

General API calls

In making any of these calls, remember to prefix them with the name of your mapAppObject variable.

CALL

PARAMETERS/FUNCTIONS

resizeMap(width,height)

Width: numeric value of new width of div tag containing the map.

Height: numeric value of new height of div tag containing the map.

This function allows a script to change the size of the map.  The location is tied to the upper left corner and will not change.

changeLanguage(language)

Language: string containing the name of the new language, “Japanese”.

 

 

newLocaton(configObject)

configObject: Object containing the basic configuration information for a new location. 

Example: Config={name:"Hyde Park",

                 type:2,

                 description:'Roosevelt Library',

                 latitude:41.770770,

                 longitude:-73933162,

                 user:"rmnixon",

                 notes:'nothing yet',

                filename:lib-1259615610695.jpg

  }

Properties of the object include

name (location name), description(location description) ,

longitude, latitude (coordinates of location), type (location type), user (user to be listed as location creator) and filename (location image if there is one).

The location image must be located in the folder MapApp/images/username/.  It is the programmer responsibility to make sure that the file is there and the name is unique and fits the standard format of OriginalFileName-unixtime.fileExtension i.e.

chipmunk-1259615610695.jpg

newLocationDialog(configObject)

configObject: same object as function above.  Only the latitude and longitude are required however.

This allows a script to bring up the standard new location dialog.  This is especially useful if it is expected that the user has the coordinates.  An interface could collect the coordinate and then pop up the standard window to collect the rest of the information.  This eliminates the problem of uploading location windows.

modifyLocation(locationID, configArray)

Username and password must be set.  The configArray is the same format as for newLocation.

displayByGroups(groups)'groups' is either a the string "All" or an array of group ID's.  All location markers currently on the display will be removed and replaced with the the locations that are part of the any of the groups listed in the array.  If the parameter is "All" then all locations will be displayed.
createNewGroup(configObject)

configObject: object containing the information needed to create a new object.  It must have the following properties

name: Name of group
description: Description of Group
policy: Type of group, either 0 (open) or 1 (keyed)
key: String for keyed group
user: User id for the group owner

All of these properties must have values although description and key may be blank strings.

Tip: mapApp.configObject.user will give you the ID of the current user.  In most cases this should be used for the user property.

Returns either the new group id or 0 if a group with the name already exists or -1 if the current user isn't authorized to create groups.

 

 

assignUserToGroup(groupID, interface,user)causes the user to join the group with the groupID.  interface is a boolean value where true means that the group control window is being displayed and therefore needs to be updated. If the call is attempting to join a keyed group, the current user will be presented with a request for the admission key string.
addLocatonGroupAPI(groupID, locationID)Adds a location to a group.
removeLocationGroupAPI(groupID, locationID)Removes a location from a group.
loadLoginStatus(loginInfo,index)

Let's you change the authentication information for the current user.  It should be used with caution.

loginInfo is an associative array with the following key/value pairs

['user'] - username

['pass'] - password

['authority-level'] - authority level to be used with this user

['status'] - as an API this should always be True.

This function will reset everyhing, such as which buttons are available - to match the authority level of the user.  However, if the username and password don't match what the authentication system expects, the underlying databases wouldn't be updated and changes that the user makes will disappear with the next page load.

displayAllTypes()Display all locations no matter what type.  Functionally this is the same as displayAllDocTypes.
displayByTypes(typeArray)Display only those locations requested.  The parameter is a simple array of numbers indicating which location types to show.  The location types are the values originally passed to aMapApp3 as part of the locationTypes array at configuration time.
displayAllDocTypes()Display all locations no matter what type.  Functionally this is the same as displayAllTypes.
displayByDocTypes(docTypeArray)Displays only those locations which contain documents of the requested tuypes.  The parameter is a simple array of numbers indicating which document types to look for.  The types are the values originally passed to aMapApp3 as part of the documentTypes array at configuration time.
showMap()Displays the map.  This would be used if initial configuration was set with noShow set to True and the application was now ready to display the map.

In addition, if you use the aLogin2 you can use the aLogin2 API.  This is available using the aMapApp3 property, loginApp. The most common API functions to use this way would be myMapApp.loginApp.login myMapApp.newAccount and myMapApp.loginApp.changePassword.  These can be used as a replacement for the standard login interface provided by aMapApp3 by adding, to the html code something like,

<a href="#" onclick="myMapApp.logApp.login('callbackFunctionName')">Login</a>

While it is also possible to access the aBlog2 API since blogs are associated in individual locations and files, and there isn't a really good way to for the web application to determine which blog goes with which location/file, this would only be useful for the few API calls that impact all the blogs.