Workspace and Mapspace JSON format

Introduction

Mapspace JSON format is a serialization version of the options that a workspace can use to initiate. It includes almost any serialization of any class in the Mapspace JavaScript API because a workspace is the top class that can contain any other classes. Workspaces contains viewers, viewers can contain layers, controls, interactions, and so on.

Mapspace JSON format definition

The format is described using JSON. As a JSON file is just a stringfied version of a JavaScript object, and these can be described with JSON descriptors, so we will use here that system. On a general case, if not said the contrary, any property described is always optional. Classes have always default values for all the missing properties as far as it is possible. In some cases, a value is needed. In that case, it will be enphasized in the doc.

What is a workspace?

A workspace is an instance of Mapspace.Workspace. It contains the defintion and setup for a collection of viewers, and that include all the viewers options, and the relations (sync options) between them. It also stores definitions for UI controls that are not only related for one viewer, but for all at the same time.

As a workspace can be serialized in a string back and forth, the serialization version can be used as a way to store the status of a web app in a given moment to recover that config status a moment later.

In the Getting Started you can see an example for creating a workspace with two viewers.

Mapspace JSON format

A Mapspace JSON format can store a Mapspace.WorkspaceOptions object, that is a plain object with some properties. Some of the properties are not serialized. The definition of what is serialized and what is not is defined in Mapspace.serialization.definitions global object. A workspace contains one layout defined as Mapspace.Layout. A layout contains an array of Mapspace.LayoutView.

A Mapspace.LayoutView contains a Mapspace.Viewer, an array of Mapspace.ControlDefinition, and an array of Mapspace.SyncProperties.

Currently controls are not serialized when serializing and deserializing a workspace.

When serializing a Mapspace.Viewer (and any other object inside a viewer that is an instance of a class) a JSON representation of the object is created and an extra classType property is added with the class name. For example, valid class names for Mapspace.Viewer instances are Mapspace.ortho.Viewer, Mapspace.oblique.Viewer, Mapspace.street.Viewer, Mapspace.threed.Viewer. This way when deserializing the API knows what class must be instantiated to rebuild the object serialized.

For example, in the following code a point geometry is created and the Mapspace JSON object serialized is shown:

var point = ol.geom.Point([10.5, 45.6], ol.geom.GeometryLayout.XY);

var bjsonPoint = Mapspace.serialization.serialize(point, true);

//bjsonPoint will be equivalent to this object:
var bsjonPoint = {
    coordinates: [10.5, 45.6],
    layout: 'XY',
    classType: 'ol.geom.Point'
};

Example of serialization / deserialization

This code is a new way of initialize the workspace create in the Getting Started:

$(function() {
    Mapspace.USERKEY = 'Set your own user key here';
    var workspace;
    var workspaceOptionsSerialized = `{
        "name": "Getting Started workspace",
        "description": "A serialization of the Getting Started workspace",
        "modificationdate": "21/06/2018 9:46:30",
        "layout": {
            "name": "Map & Street layout",
            "views": [
                {
                    "column": 0,
                    "viewer": {
                            "center": [10.743704, 59.911299],
                            "resolution": 2.38,
                            "layers": [
                                {
                                    "name": "Ortho WMTS",
                                    "source": {
                                        "userLayerName" : "-Default-",
                                        "classType": "Mapspace.ortho.source.WMTS"
                                    },
                                    "classType": "Mapspace.layer.Tile"
                                }
                            ],
                            "classType": "Mapspace.global.Viewer"
                    }
                },
                {
                    "column": 1,
                    "viewer": {
                        "center": [10.743704, 59.911299],
                        "classType": "Mapspace.street.Viewer"
                    },
                    "syncOptions": [
                        {
                            "syncedViewIndex": 0,
                            "center": true,
                            "FOV": true
                        }
                    ]
                }
            ]
        }
    }`;

    var workspaceOptions = Mapspace.serialization.deserializeWorkspace(workspaceOptionsSerialized);
    workspaceOptions.target = 'viewer';
    workspace = new Mapspace.Workspace(workspaceOptions);
});

You can see this code in action in the Examples.

And this is the code to generate the serialization from a given workspace:

    var workspaceOptionsSerialized = Mapspace.serialization.serializeWorkspace(workspace);