SRelationBrowser

Introduction
The sRelationBrowser, also known as the Relation Browser or Concept Explorer or spider, is a component that displays networks of nodes and arcs. It is usually used to display relationships between entities (instance records) described in structXML. A separate document lists some examples.

Each node in the relation browser is an entity, and each arc is a relationship (also known as an "edge", "predicate" or "property") between two entities nodes. The relationship can be be anything.

Additionally this relation browser tool can point to link things related to each focused node. Things can be anything from stories to cities.

The Relation Browser can be used to display and browse small graphs with a few nodes and arcs in a standalone mode, or big graphs with million of nodes and arcs by using a OSF Web Service instance.

Download
The code source of the sRelationBrowser OSF Widget can be downloaded on the OSF Widgets GitHub repository here.

Demo
The sRelationBrowser can be seen in action on different demo websites:


 * 1) the MyPeg Explorer used to browse their own wellbeing indicators ontology
 * 2) the UMBEL ontology browser
 * 3) the CitizenDAN demo explorer used to browse the MUNI ontology

Settings
The settings file of the sRelationBrowser component has to be named  and should be accessible from the   folder.

This settings file define a list of settings specific to the Relation Browser. It changes its behavior, and specify where to get some of its information to display.

Nodes and Edges Skins
Each node and each edge displayed in the Relation Browser has a type. The type of a node is the type of the record it represents; such type can be: a Person, a Document, a City, etc. The type of a edge is the relation it represents; such relation can be: knows, isPartOf, isCapitalOf, etc.

Each node/edge type can be skinned differently in the Relation Browser. The Relation Browser skin file is composed of multiple nodes/edges styles. If a node/edge element doesn't have a  or a   attribute, it means that it defines the default style to apply to a node/edge. If a node has both a  and a   attribute, the   node skin will be selected before. If a node/edge type is not styled in the skin file, then the default node/edge style is used. Each  element has to be added to the   element (same for the   elements).

The record being displayed in the relation browser can be bound to a node skin via the  attribute using two methods: (1) by its , or by the   attribute. The  property has priority over the   one. That way, someone can easily fine-tune how certain nodes, or a certain sub-set of nodes, will be skinned in the relation browser.

The skin file of the sRelationBrowser component has to be named  and should be accessible from the   folder.

Related Things
Things can be related to each concept displayed in the relation browser component. All of these relationship are described in a dataset hosted on a OSF Web Service instance. The related things are queried to the SPARQL endpoint of the OSF Web Service instance. The sRelationBrowser.xml setting file instructs the sRelationBrowser component the related things attribute to use to find the related things. Then, possible related things will be displayed in the related things panel in the right sidebar of the component, or within the parent HTML web page where the flex component get embedded.

Important Predicates
Some predicates/attributes describing a record are important for this sRelationBrowser component. This is a list of those important predicates and their usage in the context of the sRelationBrowser component.

Styling Breadcrumb
The Breadcrumb component can be styled in the theme's CSS file. It has 3 style properties, and can be styled like:

MXML Usage Examples
In this example, we assume that the  variable is a , where the record description is defined, accessible at the creation time of the sRelationBrowser. are the types to focus on at load time. The types should be part of the schema. The schema is the conceptual structure to load in the relation browser.

Configuring the sRelationBrowse on a Web Page
This section explains you how you can configure the  on any HTML web page.

The  OSF Widget is part of an entire OSF Widget library of tools. However, it is not the component itself that gets embeded in a webpage, but the Portable Control Application. Depending how the  is configured on the web page, and depending on the information provided as input, the sRelationBrowser will be run when the webpage will be loaded. Remember that the behave differently depending on the data records it gets as input.

Embedding the Portable Control Application Into a Web Page
The first step is to embed the Portable Control Application into your web page. This is not different than embedding any Flash movie into a web page.

Dowloading the Portable Control Application
The first thing to do is certainly to download the latest version of the Portable Control Application from here.

Defining the Portable Control Application Folder
Then, before adding any code to the HTML web page, you have to determine where the Portable Control Application application and related files is located on your web server. Once you defined that place, you have to extract the content of that file, compile it using Flash Builder and then to copy and paste the content generated into the  or   folder of your Flash Builder installation. For this documentation, let's say that all files are accessible here:

Importing JavaScript and Style Sheets Files
Now that you know where the Portable Control Application files are located, you have to import all the necessary JavaScript and CSS files that are located into that location. All these files are automatically generated by Flash Builder and are only used in specific situations.

Let's import these JavaScript files into the  section of your HTML page:

Then let's import this CSS files into the  section of the same HTML page:

Embeding the Flash Movie Into the Web Page
The next step is to embed the Flash movie into your webpage. This can easily be done using this HTML code:

Configuring the FlashVars
The last step you have to do is to configure the FlashVars for your setting. You can read about each of these FlashVar on that zWiki page Portable Control Application's Flash Variables Explained

Defining a basic structXML Schema
One of the FlashVar that has to be defined has to refer to a irXML Schema. This schema is what is used by the Portable Control Application to select the proper OSF Widget to use to display information about the input record.

The most basic workflow is as follow:


 * 1) Check the type of the input record
 * 2) Download the input schema
 * 3) Check if one of the type(s) of the input record is related to a OSF Widget using a   attribute.
 * 4) If yes, then let's display information about this input record using the related OSF Widget.

Here is the most simple irXML Schema that will make the link between the input record (see below) and the sRelationBrowser OSF Widget.

Defining the Input Record
The last step is to define the first input record to feed to the Portable Control Application. This input record is the first node that will be selected in the relation browser. After that, depending on how you configured the relation browser, you will get the information about related records from a OSF Web Service instance, or from the other records you could have defined into the Flashar input resultset.

All the input records are serialized using the structXML serialization format. The most simple input instance record to use as input record is:

Configuring the Settings and Skins
The last step will be for you to define the settings and the skins that this Relation Browser instance will use. Check the sections above that talks about these two things and that describes each and every settings that can be defined for a running Relation Browser instance.

Displaying Node Details Information in HTML
It is possible to display some details information about the selected node in the Relation Browser somewhere in the parent HTML web page. It is done using the Flash ExternalInterface object. This object will call a JavaScript function that has been defined within the web page where the Flex component get embeded. Ultimately, the Relation Browser create and populate a details object and send it to a JavaScript function. This JavaScript function will take that details object and will display its information somewhere in the web page.

Details Data Structure
The data structure transmitted between the Flex component and the JavaScript function is quite simple. It consists in these three properties:

The AS3 object that is transmitted to the JavaScript function is:

JavaScript Function
The JavaScript function that is call from the Relation Browser has to be called. Here is an example of such a simple function:

Then this JavaScript function will populate an HTML elements structure such as:

If you define this JavaScript function and this HTML table within a web page that embed the Relation Browser, each time the user clicks on a node, its detail information will be displayed in this HTML table.

Also note that you have to make sure to enable this feature by setting the  setting in the   setting file.

Displaying Related Things in HTML
It is possible to display a list of related things to the selected node in the Relation Browser somewhere in the parent HTML web page. It is done using the Flash ExternalInterface object. This object will call a JavaScript function that has been defined within the web page where the Flex component get embeded. Ultimately, the Relation Browser create and populate a list of related things object and send it to a JavaScript function. This JavaScript function will take that details object and will display its information somewhere in the web page.

Details Data Structure
The data structure transmitted between the Flex component and the JavaScript function is quite simple. It consists in these two properties:

The AS3 object that is transmitted to the JavaScript function is:

JavaScript Function
The JavaScript function that is call from the Relation Browser has to be called. Here is an example of such a simple function:

For each  in the   like, this function will create a new   element, for each , that will be appended to the   parent.

Then this JavaScript function will populate an HTML elements structure such as:

If you define this JavaScript function and this  within a web page that embed the Relation Browser, each time the user clicks on a node, its related things will be displayed in this HTML.

Also note that you have to make sure to enable this feature by setting the  setting in the   setting file.

Displaying Nodes and Edges Types Filters in HTML
It is possible to display a list of node types and edge types filters somewhere in the parent HTML web page. It is done using the Flash ExternalInterface object. This object will call a JavaScript function that has been defined within the web page where the Flex component gets embeded. This function should display a list of things (normally combo-boxes) that will enable users to show or hide node and/or edge types. Then, when one of the things (combo-box) gets clicked, a JavaScript function will call a remote function within sRelationBrowser to tell it to hide some node or edge type.

Three important behaviors have to be taken into account when using this display:


 * 1) Users can not filter-out the type of the node currently selected. Its type(s) won't be sent to the JavaScript application, so it can not act as a filtering choice.
 * 2) When users filter-out edge types, it will remove all of the nodes that are the source, or the target, of an edge being filtered.
 * 3) If the node that is the source or the target of a filtered-out edge type is the selected node, the edge won't be removed.

These behaviors are designed to ensure the consistency of the graph being displayed related to the selected node by the user.

Details Data Structure
The data structure transmitted between the Flex component and the JavaScript function is quite simple. It consists in these two properties:

JavaScript Function
The JavaScript function that is call from the Relation Browser has to be called. Here is an example of such a simple function:

For each  in the   array, and for each   in the   array, this function will create a checkbox with a right-side label.

Then this JavaScript function will populate an HTML elements structure such as:

Also, each checkbox have a  properly that will respectively call the functions   and. These two functions will call back, respectively, the functions  and   that are in the sRelationBrowser application. Here is an example for each of these functions:

Note that you can tweak these functions at will. For example, you could choose to only display node types filters.

If you define these JavaScript functions and these  within a web page that embed the Relation Browser, each time the user clicks on a node, nodes and edges filters will be displayed in this HTML.

Also note that you have to make sure to enable this feature by setting the  setting in the   setting file.

Related Libraries
This tool is based on the Relation Browser Flex project. It has been enhanced for some special purposes of the OSF Widgets, but the basis of this component is based on the Relation Browser application.

This relation browser project is itself related to the Flare visualization framework.