SWebMap

You might also want to see the How to Use the WebMap document.

Introduction
The  semantic component is an interactive map that works seamlessly with the geo-localized information available on a Open Semantic Framework instance. If a web developer has access to an OSF instance, she can create her own sWebMap component in a single line of code. The only thing that is needed is to properly configure the options of the component.

The  marries a JavaScript Google map with the underlying structured data in an OSF instance. Any data that has geo-locational data of any type may utilize the  widget. The  component lets people search, browse, filter and display all kind of information on a map. The map may display three different kind of things:


 * 1) Records that have a single location. They are displayed on the map using a marker icon
 * 2) Records that represent a geographical area. They are displayed on the map using polygon shapes with different colors
 * 3) Records that represent a path. They are displayed on a map using polylines (lines with one or multiple vertices) with different colors.

The  has two different major modes:


 * 1) A mode that displays a single map, with a result set and multiple filtering criteria
 * 2) A mode that displays a main map, with 3 smaller maps that are used as focus maps. These focus maps are used to highlight specific areas of the main map. This mode also displays all the results and filters for each different focus map

Lastly, there are three main categories of filters that can be used to display the records on the map:


 * 1) Dataset filters
 * 2) Type filters
 * 3) Attribute/value filters.

OSF Web Service
The  control communicates with an OSF (Open Semantic Framework) instance. More specifically, a  control will send Search queries to a geo-enabled OSF Web Service Search web service endpoint.

Depending on the options you had specified when you created the  control, each time you move (option), zoom (option) or change the filtering criterias, this will send a query to the Search endpoint. The  control then requests JSON formatted resultset and display the results to the user.

Schemas
All of the records that are returned by the Search web service endpoint of a OSF instance are described using different ontologies. These ontologies should be defined in the OSF instance and the irON Schema; these ontologies may have been generated by the structOntology OSF-Drupal module. It is these schema that should be used by the  control (see the   setting). The structOntology module will generate one irON schema per loaded ontology.

What needs to be done is to load all the irON schema that describes the records that are expected to be manipulated in the  control. If the proper schema are not loaded, the tool will continue to work properly, but it may have to fallback on default behaviors.

Important Predicates
Some predicates/attributes describing a record are important for this  component. This is a list of those important predicates and their usage in the context of the  component. Depending how the record to display in the  component are described, the component may change its behavior, or the way it displays the records on the map. All the predicates below describe records that will be used by the.

There are also important predicates that can be used to describe the classes and predicates of the ontologies loaded and used in the. If these predicates are used then this may have an impact on the behavior of the  widget.

Modes
There are two major modes to the  component:


 * 1) Normal Mode
 * 2) Focus Windows Mode

Let's take a look at each of these modes.

Normal Mode
The normal mode is the default, basic mapping mode. In this mode, users are able to search and browse records in a single map. Results are displayed in a results section, and filters are available to facet the information displayed to the user. Map sessions can be saved, loaded, deleted and shared.

Focus Windows Mode
The focus window mode is a special mode where 3 focus maps have been added to the user interface. The big map shows the area covered by each of the focus map, in different colors. What the user does is to move the focus windows around. Each of the focus windows is related to a particular region of the bigger map. Each time the user clicks on a different focus map, a different set of records is displayed within the selected focus window.

This mode is used to compare different regions on a map. The filters are applied to each focus window. Different records can be selected within each focus window. Maps in focus window mode can be saved, loaded, shared and deleted.

Templating
The  control uses templates to display two kind of information to the user:


 * 1) All the records from a resultset
 * 2) The complete description of an individual record

Two different templating technologies are used. The templating technology used to display the results within a resultset is native to the  control. The templating technology used to display the complete description of an individual record is the same as used by OSF-Drupal to display records' individual page using the structView Drupal module. This other method is discussed at length in the Building OSF-Drupal Templates tutorial. The templates that have been created that way will simply be re-used by the  control. No work needs to be duplicated.

Note that this second templating mechanism is only used by the  control if the   is enabled.

Resultset Templating
Each individual result displayed in the resultset list can be templated. Each result is templated according to its type. If there is no template defined for its type, the default template is used to display the result in the resultset.

Creating a Web Map Template
All of the sWebMap result templates are defined in the  template. Each template is an element of the  JavaScript object variable. Each property of that  object refers to a type of record. The name of each of these attributes are the URIs used to define the type(s) of a record. It is that attribute's name that will bind a record's type to a result display template.

This  JavaScript object is used by the JavaScript PURE Templating Engine as the basis for generating the template display and filling it with the record's description.

We would recommend you to refer to PURE's documentation to understand how the PURE templates works, and how they can be created. Here we will cover how to create PURE templates for displaying records that comes from OSF (Open Semantic Framework).

Here are two basic templates that can be used to template records of type  and  :

\      ',    "http://purl.org/ontology/muni#Schools": ' \        \           \  \ \ \        \           School\'s District:  \ \        \           School\'s Homepage\ \      '  };

Note that if you invoke records with images with an empty  attribute, or links with an empty   attribute, then these HTML element will automatically be removed from the HTML code generated by the template. This happens for the usecases where not every records has an image or a link reference in their description. That way, instead of creating more complex PURE template with pseudo "if" statements, then we simply generate empty  and   elements that get removed from the code generated by the templating engine before being added to the DOM.

The resultTitle Special Class
A special class is available to the template developer:. This class is used to specify that the content of the HTML element that has this class defined is clickable, and that when the user clicks on it, it gets redirected to the record's web page.

This special class is used to instruct the  where the "record's title link" is defined in the template. If this class is not defined for any element of a template, then the user won't be able to get to the record's webpage by clicking on it.

Rendering
The PURE Templating Engine takes three things at input:


 * 1) A template
 * 2) A set of records for which to apply the template
 * 3) A series of directives to modify the template's output.

Once we select a specific template to apply to a specific record's type, then each of the records of that type are processed by PURE using that template. A record is a simple JavaScript object with a series of attribute/value pairs. Here is an example of a record that would be displayed using the  template:

Each of the record's attribute is used in the template's description, and its value is inserted into the HTML element according to the rules embedded into PURE template.

Using Directives
Optionally, PURE processing directives can be defined to apply special processing rules at time of rendering.

The directives are defined in the  JavaScript object that is also included in the   file. Each attribute of this  object is a directive applied to a specific template. The attribute's name is the same as the one of the template.

Here is a simple directive that may be applied to the  template:

This directive checks for all the  elements that have a   class. Then it checks if the current record being templated has the  attribute describing it. If it does, then it checks to make sure the value is not empty. If both assertions are true, then nothing is done. But if one of these two conditions is false, then PURE will assign the style  to the     and so hide it from the display.

These directives have to be created when we want to hide sections, or sub-sections, of a template depending on the information that describes a record being templated. This is what replaces the more traditional  conditional statements. Such conditional statements are not existing in the PURE Templating Engine, so we have to rely on the directives to do to this kind of work.

Detailed View Templating
When a user clicks on a result in the results list, and if the  option is enabled, an overlay popup window appears to the user with the detailed information the system has about this specific record. This information comes from the structView module and the OSF-Drupal templates that are currently used in the OSF-Drupal installation.

If the  option is not enabled, the user is simply redirected to the URI of the record. However, it is possible to simply display information directly in the resultset, without giving the user the possibility to click on it to get more information about the record. To do this, you simply have to create a new PURE template that doesn't use the  class.

The detailed view overlay gets the HTML content to publish on the overlay canvas from the structView module. All of the HTML code, the CSS styles and the JavaScript code are taken from what is generated in the OSF-Drupal template. However, it is possible to add additional CSS to that overlay view by adding the additional CSS content to the  option. This CSS content goes in the header of the web page, so you can refer to a specific CSS file using the  HTML element, or by injecting the CSS code directly using the   HTML element.

Styling
The entire  control can be styled by modifying the   stylesheet. The different portions of the control can be styled individually.

Focus Windows Styling
If the focus windows mode is enabled, three smaller focus windows are displayed to the user. Each focus window can be styled individually, depending if they are selected or not by the user. The styles can be changed by changing these 6 different classes:,  ,  ,  ,   and.

The color of the  CSS attribute is used as the color to use for the drawing the rectangle representing this focus window on the main map.

Loading the JavaScript Libraries
The two core libraries used by the  are   and the. These can be loaded directly from the  domain:

There are a series of external libraries that are used by  that have to be loaded as well. Most of them are jQuery plugins, but a few of them are libraries of their own:

The next step is to load the  related libraries, which includes the   component:

The last step is to load all the  that have to be used by the   component:

Loading the Minimized/Compiled Version
Once your  is in production, you should use the minimized/compiled version of the component. You can easily do this by using the JavaScript files located in the  folder.

Loading the Stylesheets
There are two stylesheets to load. The main  style sheet, and one from the Tipsy library:

Internet Explorer Compatibility Mode
Make sure your HTML page instructs Internet Explorer of the compatibility mode to use to render the webpage. You simply have to put that  tag into the   tag of your HTML webpage.

If you forget to add this meta tag, then Internet Explorer will complain that the JSON object is not defined. In fact, the JSON object has been implemented in Internet Explorer since version 8.