View source

Rich objects are the primary feature of HyperCities. These contain not just objects that can be placed on a map, but a particular configuration of the geobrowser such as camera angle. All rich objects include rich HTML descriptions. Rich objects can include other objects to display along side them (even full collections), plus other historical maps, and can also set the particular view of the geobrowser, among other things. Some of these features are specific to Google Maps and Earth; it is up to the implementer how to implement these, if at all.

Please note: if a rich object contains other rich objects that also have view data, then the view data of the “main” rich object (the object that includes all the other objects) is what should be used. Also, if a rich object includes other rich objects that themselves have other rich objects (an odd situation, admittedly), only the main object and its immediate children should be displayed (at least, this is the prescribed behavior in the main HC viewer). No other attributes of the child objects should be displayed, such as historical maps, or the like.

Rich objects can belong to one or more collections, as well as to rich objects.

Objects and collections have both a “creator” and an “ownerId” field. The ownerId is a numeric foreign key to the users table, while the creator is a text field filled in at the time of creation. A user can attribute a project to a group, like “Pilipino Workers’ Center.” The same is true for collections.

= JSON Representation of a Rich Object =
<code>
 {
    "creator": "admin", // Creator's name; assigned during object editing
    "owner": 17, // owner's numeric ID
    "bookmarks": [], // Any number of bookmarkers for Geoscribe
    "id": 24169, // object's ID in database
    "objectType": 6, // Object's type
    "copyright": "CCBY", // License under which content is protected
    "markerTypeId": 0, 
    "content": 12132, // ID number of the object’s content in the database; may be null
    "maps": [], // the entire JSON description of every map associated with this object
    "state": "2", 
    "mapType": "EARTH", // Map to use as basemap; no longer relevant in Earth-only HC
    "markerType": null, 
    "linkUrl": "http://linuxdev.ats.ucla.edu/provider/objects/24169", 
    "buildings": null, // Whether 3D buildings are enabled
    "description": null, 
    "mapping": {
        "swLat": "36.65504670", 
        "dateTo": {
            "date": "0525-01-01 00:00:00", 
            "timezone_type": 3, 
            "timezone": "America/Los_Angeles"
        }, 
        // either a link to the KML file of a 3D model, or a string of 
        // KML for any other kind of object
        "kml": "http://schnauzer.ats.ucla.edu/inscriptions/wp-content/uploads/2010/10/LateAntiqueForum.kml", 
        "dateFrom": {
            "date": "0404-12-31 00:00:00", 
            "timezone_type": 3, 
            "timezone": "America/Los_Angeles"
        }, 
        "zoom": "16", // default zoom level in Google Maps
        "neLon": "19.27059636",  // These four coordinates contain
        "neLat": "45.78679485",  // the object's minimum bounding rectangle.
        "swLon": "7.99368023", 
        "markerStyle": 0, // what kind of marker will be displayed; 0 means no marker
        // KML used to position camera in Google Earth
        "view": "<Camera><longitude>12.483669140652</longitude><latitude>41.892244214771</latitude><altitude>2165.514124593</altitude><roll>0</roll><tilt>0</tilt><heading>-0.76050292974789</heading></Camera>"
    }, 
    "coauthors": [
        "17" // ids of any users with editing privileges on the object
    ], 
    "objects": [], // the entire JSON description of every rich object 
                   // associated with this object, except for any of those 
                   // object’s child objects 
    "name": "Late Antique Forum 3D Models", 
    "stateId": "2", 
    "bubble": [{ // JSON objects that show any objects whose info 
                 // bubbles should be opened when the object is loaded. 
                 // This may also be an empty array.
       "id" : 1292, // Object id whose info bubble is showing
       "state" : "max" // or "min"; shows state of bubble
    }], 
    "isEarthObject": 0, 
    "ownerId": 17 // owner’s numeric ID
 }
</code>


= Response codes =
A GET request to /objects or /objects/{id} will return one of the following responses:

{|
!HTTP Code
!Data
|-
|200
|JSON containing matching objects
|-
|404
|ItemNotFound Exception
|}


= Editing and Updating Rich Objects =
To edit or update a rich object, supply the following parameters:
{|
!Name
!Value Type
!Description
|-
|title
|String (Max 255 Characters)
|Title of object
|-
|description
|HTML-formatted Text
|Description of object
|-
|creator
|String (Max 255 Characters)
|Display name of creator; leave blank to use creator's full name.
|-
|coauthors
|comma-delimited list of owner IDs
|users who will also have editing privileges on the objects
|-
|ownerId
|integer (foreign key to users table)
|ID of owner in database
|-
|copyright
|Either 'cc by', 'cc by-sa', 'cc by-nd', 'cc by-nc-sa', or'cc by-nc-nd'
|Specifies which Creative Commons License the content is protected under. For more information, see http://creativecommons.org/about/licenses/.
|-
|state
|1 (Public), 2 (Protected), 3 (Private)
|"public" allows all users to view and add to the collection. "protected" allows all users to view the collection, but only those with a password to add to it. |"private" only allows the owner to view and add to the collection.
|-
|objects
|comma-separated list of IDs
|Objects and collections that will be displayed on the map when viewing the object.
|-
|baseMap
|JSON object, with one element, “baseMap”, which is an array of JSON objects. See "base maps" below.
|Maps to be displayed when viewing the object. This allows both for maps stored in the HyperCities database, and also ArcGIS and WMS map services.
|-
|mapType
|one of the following: “EARTH”, “BLANK”, “SATTELITE”, or “TERRAIN”
|Which Google Map to use as the base layer. This is client-dependent; the default HyperCities client no longer supports this parameter because it users the Google Earth Plugin exclusively.
|-
|bubble
|JSON string (optional), with following elements: {“id” : (object id whose info bubble is in), “state” : (“max” or “min”) }
|What state the Google Maps or Google Earth bubble is in.
|-
|parentIds
|comma-separated list of IDs
|Collections this object will belong to. These must be resubmitted completely every time an object is updated.
|-
|collectionPasswords
|JSON Object of collection ID-password key-value pairs
|User’s guess of any passwords for password-protected collections specified above in parentIds.
|-
|markerState
|integer
|See [[Marker States]]
|-
|latlng
|JSON object with “latlng” member, which is array of objects with lat, lng, and alt elements
|The data that actually appears on the map. These points represent the object’s position: one for a point, and any number for a line or polygon. The mapping field in the output is calculated from these.
|-
|dateFrom
|ATOM-formatted date-time string (YYYY-MM-DDTHH:mm:SS)
|the earliest date at which the object should appear on the map
|-
|dateTo
|ATOM-formatted date-time string (YYYY-MM-DDTHH:mm:SS)
|the latest date at which the object should appear on the map
|-
|zoom
|integer
|Zoom level at which to view the object in Google Maps.
|-
|view
|JSON object with lat, lng, alt, and zoom elements
|Describes the position of the viewport for the object.
|-
|}

== Specifying Base Maps ==
Base maps should be supplied as JSON objects with the following form: 
<code>
 { 
    "id": map ID, 
    "tileUrl": (optional if id is specified), 
    "layers": optional comma-separated list of layer IDs to show from maps that have multiple layers, 
    "opacity" : transparency setting for maps, where 1.0 is completely opaque and 0 is completely transparent, 
    "mapData" : JSON object of additional information to be sent to the map service, 
    "z-index": number indicating order of maps where lower ones are on the bottom, 
    "tileType": "ArcGIS", "WMS", or "0" for Google Maps-style maps, including those in HC. 
 }
</code>