JS-GIS 2 API reference

Project objects

Table of contents

TProject object


A TProject object holds all the information required to access GIS data published by a JS-GIS publisher program. The TProject object instance definition should be written by the publisher program itself as it reflects the way GIS data are being exported into static, web-browser compatible files.

The project definition is usually written in a single JavaScript file. Once loaded, the definition should create an instance and assign it to a global TProject variable.

At present, some settings have been implemented as project-wide: map tile size in pixels, image and imagemap file extensions, tileset origin point. Possibly future versions will move those attributes into project components to add flexibility.



String: returns 'TProject'.


TRect object defining the geographic extent of the project.

The extent is recalculated every time a zoom level is added to the project: the result is the minimum extent of all the zoom levels of the project.


TTileSetArray list of all the TTileSet objects representing project's imagemaps, i.e. cliclable map layers.


String: extension of map tiles; defaults to '.png'.


String: extension of imagemap tiles; defaults to '.js'


String: root directory for project tilesets. Defaults to rootDir + 'maps/'


String, contains the descriptive name of the project.


String: the full pathname of a tile file loaded when map tiles are non available (i.e. when the map view falls outside the project extent). Defaults to mapDir + 'nomap' + imgExt


Integer: the width of row and column indexes in the tile file names. Defaults to 2, so tile in (1,4) will be saved as map0104.ext


Integer: height of the map tile, in pixels.


Integer: width of the map tile, in pixels.


String: root directory for the JS-GIS project; defaults to the location of the map page including the JS-GIS library. rootDir is used internally by TProject to obtain the default value for mapDir. If a common directory structure is used, rootDir can be used to easily access subsidiary data, for example documents in rootDir + 'docs/'.


TTileSetArray list of all the TTileSet objects representing project's themes, i.e. maps.


String: returns '2'


TObjArray list of all the project's TZoomLevel objects.


addImagemap(aName, aFolder, aLevelList, aDescription)

Adds an imagemap to the project. Creates a new TTileSet object and inserts it into the imagemaps array. See TTileset() constructor for details.

addTheme(aName, aFolder, aLevelList, aDescription)

Adds a theme to the project. Creates a new TTileSet object and inserts it into the themes array. See TTileset() constructor for details.

addZoomLevel(aName, aFolder, ageoWidth, ageoHeight, anumTilesX, anumTilesY, aScale)

Adds a zoom level to the project.

TZoomLevel object


A TProject's zoom level represents a particular zoom (i.e. a single map tile geographic width) in which GIS data has been exported. It defines the map scale and map zoom (which however may vary according to the number of tiles simultaneously shown on a map window); as a consequence, a zoomLevel defines the number of tile rows and columns the project's extent has been subdivided into.

Due to the current library settings, all the tilesets behave in the same way for each zoom level; thus, the spatial subdivision of the project extent in tiles is a property of the zoom level which is being taken into account.

Zoom level definitions should be added to a project using the TProject.addZoomLevel() method.



TRect object representing the geographic extent of the zoom level. This may or may not exactly match the extent of the owner TProject object, depending on the remainder of the division between project width (or height) and tile width (or height). The origin point is always the same, so

(aZoom.extent.min == aZoom.project.extent.min)

is always true.


TRect object representing the tile extent, where min.x is the lowest tile column number (1), anc max.y is the highest tile row number.



Returns the complete path of the folder storing all the tiled data for this zoom level. The path has a trailing slash, i.e. ends with '/'.

Usually there's no need to access to this method directly; rather use the getPath or getTileURL of a TTileSet or derived object.


This method translates geographic coordinates into tile reference. The tile or group of tiles containing a given object is returned. Tile reference is returned as row and column numbers stored in the y and x coordinates of TPoint or TRect objects.

Note that the lower left corner tile has coordinates (1, 1).

If obj is a TPoint object, getTiles returns a point identifying the column and row in which the object falls.

If obj is a TRect, the method returns a TRect representing the row and column extent containing obj. If the object is contained in a single tile, the min and max coordinates will be the same. The returned rectangle has a yAxis value of -1, indicating a geographic bottom to top order.

TTileSet object


TTileSet is a base class used to represent geographic-referenced data subdivided into a bi-dimensional array of tiles, which correspond to files named and located according to defined rules.

A tileset cannot exist by itself, and is always referred to a project and to its zoom levels.

The tileset doesn't carry any kind of data: it simply allows to retrieve the tiles according to the geographic criteria. Only tile file names are returned, and the client application is supposed to know how to use them.

All the tiles of a tileset are stored in the same directory under a project's zoom level, and the file name follows the form <prefix><row><col>.<extension>. This happens for each zoom level in which the tileset has been defined.

From the publisher's perspective, a tileset is the description of an export of a map or map layer.



String: description of the tileset. Can be used to populate dropdown lists or captions.


String: file name extension (i.e. JPG or JS).


String: name of the subfolder in the zoom level folder.


String: a list of the bound zoom levels, i.e. the zoom levels in which the tileset has been published.


String: short name for the tileset.


String: the prefix used for bulding the tile URL. Defaults to 'tile'.



Boolean: tests if the tileset has been published at the given zoom level. zoom is an integer indicating the zoom level index in the project.zoomLevels array.


Returns the path part of the tile URLs.

getTileName(row, col, zoom)

Returns just the filename part of the URL, without the path and extension. If row or col fall uotside the boundaries of the tileset for the specified zoom level, or the tileset is not available at the specified zoom level, an empty string is returned.

getTileURL(row, col, zoom)

Returns the fully qualified URL for a tile given the row and column number and the zoom level index. If getTileName(row, col, zoom) returns an empty string, returns noTile().


Returns the fully qualified URL of a blank tile. It should be used to represent maps outside the boundaries of the tileset.

TTileSet(aProject, aName, aFolder, aLevelList, aDescription, aExtension)

Class constructor: builds and returns a new TTileSet object.

aProject points to the TProject owner of the Tileset. aName is a descriptive short name, while aDescription is a longer description. aFolder is a string containing the name of the subfolder for the tileset.

aLevelList is a string holding the list of the zoom levels for which the tileset is available: the list is in the form '01234', i.e. all the indexes of the related zoom levels are put together. A value of '34' would indicate thet the tileset is available just at levels 3 and 4.

aExtension is a string containing the file name extension for the tileset.

TObjArray object


TObjArray is an array of objects indexed by insertion order or by a name property.

Used internally by TProject for holding a list of the zoom levels. See also TTileSetArray class.



Array object holding the list of objects. It can be used like a normal array; for example, setting items.length to 0 clears the array.



If id is numeric, returns the id-th element (items[id]). Otherwise, loops trough the array looking for a item.name property equal to id. The matching is case-unsensitive.

TTileSetArray object


Inherits from: TObjArray.

Implements an array of TTileSet objects. Used internally by TProject class to hold the lists of themes and imagemaps.



Returns the index of the first tileset which is available at the given zoom level.

JS-GIS © 2001, 2002 by Luca S. Percich (mailto:luca.percich@reacoop.it)
Last updated: dec 26, 2002