SRelationBrowser

From OSF Wiki
Jump to: navigation, search

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.

Settings

The settings file of the sRelationBrowser component has to be named sRelationBrowser.xml and should be accessible from the settings 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.

<?xml version='1.0' encoding='UTF-8'?>
 
<!-- Default relation browser settings file. Modify it for the purpose of your application -->
 
<settings>
 
  <!-- Display the "related things" section. -->
  <displayRelatedThingsPanel>true</displayRelatedThingsPanel>
 
  <!-- Display the "related things" within the parent HTML page that embed the Flex component -->
  <displayRelatedThingsHTML>false</displayRelatedThingsHTML>
 
  <!-- display the breadcrumb component -->
  <displayBreadcrumb>true</displayBreadcrumb>
 
  <!-- Display the "concept information" section. -->
  <displayConceptsInformationPanel>true</displayConceptsInformationPanel>
 
  <!-- Display the "concept information" within the parent HTML page that embed the Flex component -->
  <displayConceptsInformationHTML>false</displayConceptsInformationHTML>
 
  <!-- Display the nodes and edges filters within the parent HTML page that embed the Flex component -->
  <displayFiltersHTML>false</displayFiltersHTML>
 
  <!-- Restrict the type of the nodes that can be filtered. If the array is empty, all types will be filterable -->
  <filtersNodeTypes>[]</filtersNodeTypes>
 
  <!-- Restrict the type of the edges that can be filtered. If the array is empty, all types will be filterable -->
  <filtersEdgeTypes>[]</filtersEdgeTypes>
 
  <!-- URI of the property describing the relationship between a concept and a thing -->
  <relatedThingsRelations>[http://umbel.org/umbel#isAbout]</relatedThingsRelations>
 
  <!-- Title to display for the "related things panel" -->
  <relatedThingsPanelTitle>Related Things</relatedThingsPanelTitle>
 
  <!-- URI of the property defining the label to use to display the name of a related Thing -->
  <relatedThingsLabels>[http://purl.org/ontology/iron#prefLabel]</relatedThingsLabels>
 
  <!-- URI of the dataset where the stories records are indexed -->
  <thingsDataset>http://my-domain.com/wsf/datasets/123/</thingsDataset>
 
  <!-- Dataset URI where the concepts records to display in the relation browser are indexed -->
  <conceptsDataset>http://my-domain.com/wsf/datasets/127/</conceptsDataset>
 
  <!-- A set of attributes to display in the relation browser. If no attributes URI are defined
       all object property will be displayed in the relation browser. -->
  <linkingAttributes>[]</linkingAttributes>
 
  <!-- OSF Web Service sparql web service endpoint -->
  <sparqlWebServiceEndpoint>http://my-domain.com/ws/sparql/</sparqlWebServiceEndpoint>
 
  <!-- URL of the structView module where the things can be viewed when clicked by the user -->
  <structViewUrl>http://my-domain.com/conStruct/view/</structViewUrl>
 
  <!-- behavior of the browser when the user click on a Thing or wikipedia link -->
  <navigatorBehavior>_blank</navigatorBehavior>
 
  <!-- display the breadcrumb component ina JavaScript breadcrumb component -->
  <displayBreadcrumb>true</displayBreadcrumb>
 
  <!-- display the breadcrumb component within the flex component -->
  <displayBreadcrumbHTML>false</displayBreadcrumbHTML>
 
  <!-- 
    Width of the rectangle that should normally be used to have the graph in normal size.
    This size changes depending on the node sizes, number of nodes in the graph, etc.
   -->
  <fullSizeWidth>600</fullSizeWidth>
 
  <!-- 
    Height of the rectangle that should normally be used to have the graph in normal size.
    This size changes depending on the node sizes, number of nodes in the graph, etc.
   -->
  <fullSizeHeight>600</fullSizeHeight>
 
  <!-- The initial scale to use to display the graph. This scale is took into account the entire life of the browser -->
  <initialScale>1</initialScale>
 
  <!-- Size of the innerRadius of the graph's radial layout. This will impact the "spread" of the graph -->
  <innerRadius>240</innerRadius>
 
  <!-- List of URIs of node types to ignore when getting node data from the graph structure -->
  <ignoreNodeTypes>[]</ignoreNodeTypes>
 
  <!-- List of URIs of node to ignore when getting node data from the graph structure -->
  <ignoreNodeUris>[]</ignoreNodeUris>
 
  <!--
    URI of the properties for which you want the values of the selected node. The values of each of
    these properties will be added to an object which will be returned by the JavaScript function
    nodeAttributesValues(obj) called by the Flex external interface.
  -->
  <nodeAttributesValues>[]</nodeAttributesValues>
 
</settings>

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 type or a uri attribute, it means that it defines the default style to apply to a node/edge. If a node has both a type and a uri attribute, the uri 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 <node /> element has to be added to the <nodes> element (same for the <edge /> elements).

The record being displayed in the relation browser can be bound to a node skin via the type attribute using two methods: (1) by its rdf:type, or by the sco:relationBrowserNodeType attribute. The sco:relationBrowserNodeType property has priority over the rdf:type 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 sRelationBrowserSkins.xml and should be accessible from the settings folder.

<?xml version="1.0" encoding="UTF-8"?>
 
<skin>
  <nodes>
    <node type="http://umbel.org/umbel#SubjectConcept">
 
      <!--
        Label to use to refer to this type of node, within the user interface. For example, this is used
        by the filtering control to display the proper names for these nodes.
 
        By default, the end of the URI of the type will be used as the label.
      -->
      <label></label>
 
      <!--
        Display, or hide, the label for that node type/specific node.
      -->
      <displayNodeLabel>true</displayNodeLabel>
 
      <!-- The tooltips, textColor, textFont and alphaTransparency properties are applicable for all forms of nodes -->
 
      <!--
        Display tooltips of small scale nodes.
 
        Values: "true" or "false"
      -->
      <tooltips>true</tooltips>
 
      <!--       
        Define the font of the text label on the node
 
        Values: by example: "Verdana"
      -->
      <textFont>Verdana</textFont>
 
      <!--       
        Define the color of the text label on the node
 
        Values: any HTML code color in hex form, such as "0x000000" (black). The alpha channel 
                is not part of the hex value of the color.
      -->     
      <textColor>0x000000</textColor>      
 
      <!-- Defines the size of the text to display in the node. -->
 
      <textSize>12</textSize>      
 
      <!--
        The best way to skin a node is by using an image to display at the position of the node
        in the graph. If an image is specified, the other properties: lineWeight, lineColor, 
        fillColor and shape are all ignored.
 
        Values: A URL to an image to use to display at the position of the node. An empty value
        if the user wants to disable this property.
      -->
      <image></image>
 
      <!--
        Shape of the node to display.
 
        Values: "circle", "block", "polygon", "square", "cross", "X", "triangleUp", "triangleDown", 
                "triangleLeft", "triangleRight", "diamond".
      -->
      <shape>circle</shape>  
 
      <!--
        Defines the size of the line of the border of the shape to display for the node.
 
        Values: "1" to "20"
      -->
      <lineWeight>1</lineWeight>
 
      <!--
        Defines the color of the line of the border of the shape to display for the node.
 
        Values: any HTML code color in hex form, such as "0xFFFFFFFF" (white). The two 
                first bytes of the hex value define the alpha (transparency) value
                of the color ("00" means completely transparent, "FF".
                means completely opact.
      -->
      <lineColor>0xFF000000</lineColor>
 
      <!--
        Defines the color to use within the borders of the share to display for the node.
 
        Values: any HTML code color in hex form, such as "0xFFFFFFFF" (white). The two 
                first bytes of the hex value define the alpha (transparency) value
                of the color ("00" means completely transparent, "FF".
      -->
      <fillColor>0xFFAABBCC</fillColor>
 
      <!--
        Defines the radius of the node. The radius defines the boundaries of the node in the graph.
        All the nodes will attach to the radius of a node, and not its actual specific shape. The
        radius is an invisible boundary where the edges get attached.
      -->
      <radius>20</radius>
 
      <!--     
        Scale factor of the node's shape background. A scale factor of 1.25 means that it is 125%
        its normal size.        
      -->
      <backgroundScaleFactor>1</backgroundScaleFactor>      
 
      <!--      
        Scale factor of the node's text label. A scale factor of 1.25 means that it is 125%
        its normal size.        
      -->
      <textScaleFactor>1</textScaleFactor>     
 
      <!--      
        X Offset where to start displaying the text within the node's shape. The coordinate
        is relative to the node. An offset of 0 means no offset. The offset can be positive 
        or negative.       
      -->
      <textOffsetX>0</textOffsetX>     
 
      <!--      
        Y Offset where to start displaying the text within the node's shape. The coordinate
        is relative to the node. An offset of 0 means no offset. The offset can be positive 
        or negative.      
      -->
      <textOffsetY>0</textOffsetY>     
 
      <!--      
        Displaying the label, within the node, in a multi-line format. Multi-lines means that
        each word of a label is displayed on a single line.       
      -->
      <textMultilines>false</textMultilines>     
 
      <!--      
        Maximum width of the text. If the text's width is longer than this value,
        then it will be truncated and a "..." will be appended at the end of the label.
        Also, tooltips for this item will be enaled.      
      -->
      <textMaxWidth>256</textMaxWidth>     
 
      <!--      
        Maximum height of the text. If the text's height is longer than this value,
        then it will be truncated and a "..." will be appended at the end of the label.
        Also, tooltips for this item will be enaled.      
      -->
      <textMaxHeight>256</textMaxHeight>           
 
      <!--
        This defines a color to overlay on the central, selected, node of the graph. This overlay
        is defined by a series of color offsets ranging from -255 to 255. The color is defined by
        4 different offsets: [alpha, red, green, blue].
 
        By example, if if have an overlay defined as: [0, 150, -50, 0], this will be traducted
        by an image where the red color is 150 brighter, and the green color 50 lighter.
 
        This is mainly used if you want to make the central node of your graph brighter 
        related to others.
      -->
      <selectedNodeColorOverlay>[0, 0, 0, 0]</selectedNodeColorOverlay>
 
      <!--
        This defines a color to overlay on the central, selected, node of the graph. This overlay
        is defined by a series of color offsets ranging from -255 to 255. The color is defined by
        4 different offsets: [alpha, red, green, blue].
 
        By example, if if have an overlay defined as: [0, 150, -50, 0], this will be traducted
        by an image where the red color is 150 brighter, and the green color 50 lighter.
 
        This is mainly used if you want to make the central node of your graph brighter 
       related to others.
      -->
      <overNodeColorOverlay>[0, 0, 0, 0]</overNodeColorOverlay>
 
      <!-- Automatically center the text within the nodes -->
      <automaticCentering>true</automaticCentering>
 
    </node>
  </nodes>
 
  <edges>
    <edge type="http://www.w3.org/2004/02/skos/core#broaderTransitive">
 
      <!--
        The label to display in the center of the edge. Usually, this label is a single 
        character that get overlay-ed on the image of the edge.   
      -->
      <displayLabel></displayLabel>
 
      <!--
        A more detailed label that describe the relationship associated with the edge
        that get displayed, within a tooltip, when the user mouse-over the edge.
      -->
      <tooltipLabel></tooltipLabel>
 
      <!-- 
         Defines the type of the arrow of the edge. 
 
         Values: "none", "triangle", "lines" 
 
         Note: "none" specifies a non-directed edge; "triangle" and "lines" specifies 
               a directed edge.
      -->
 
      <directedArrowHead>none</directedArrowHead>
 
      <!--       
        Define the font of the text label on the node
 
        Values: by example: "Verdana"
      -->
      <textFont>Verdana</textFont>
 
      <!--      
        Define the color of the text label on the node
 
        Values: any HTML code color in hex form, such as "0x000000" (black).
      -->     
      <textColor>0x000000</textColor>      
 
      <!-- Defines the size of the text to display in the node. -->
 
      <textSize>12</textSize>    
 
      <!--
        An image that get displayed on the edge, in the middle of the two connected nodes. The
        text that is displayed is displayed *over* this image.
 
        Values: A URL to an image to use to display at the position of the node. An empty value
        if the user wants to disable this property.
      -->
      <image></image>
 
      <!--
        Defines the size of the line of the border of the shape to display for the node.
 
        Values: "1" to "20"      
      -->
      <lineWeight>1</lineWeight>
 
      <!--
        Defines the color of the line of the border of the shape to display for the node.
 
        Values: any HTML code color in hex form, such as "0xFFFFFF" (white). The two 
                first bytes of the hex value define the alpha (transparency) value
                of the color ("00" means completely transparent, "FF".     
      -->
      <lineColor>0xFF000000</lineColor>
 
    </edge>
  </edges>
</skin>

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.

Prefixed Attribute Predicate URI Usage
TDB by the setting relatedThingRelation TDB by the setting relatedThingRelation The attribute that is used to relate things to concepts displayed by the sRelationBrowser component. This attribute is defined in the sRelationBrowser.xml settings file.
iron_prefLabel http://purl.org/ontology/iron#prefLabel Preferred label to be displayed in the detail panel
iron_description http://purl.org/ontology/iron#description Description of the concept to be displayed in the detail panel
iron_prefURL http://purl.org/ontology/iron#prefURL Preferred url to be displayed/linked-to in the detail panel

Styles

Style Name Description
sRelationBrowser Style for the main sRelationBrowser component
sRelationBrowserNameHBox
sRelationBrowserPrefLabelHBox
sRelationBrowserDescriptionVBox
infoboxDescription
sRelationBrowserToolsBoxVBox
sRelationBrowserInfoboxPanel
sRelationBrowserInfoxBoxVBox
sRelationBrowserRelatedThingsPanel

Styling Breadcrumb

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

Breadcrumb
{
  borderColor: #CCCCCC;
  themeColor: #FFFFFF;
  backgroundFillColors: #FFFFFF, #FBF6E1;
  color: #000000;
}

Using the sRelationBrowser in Standalone Mode

AS3 Usage Examples

  /** Create a resultset object instance from the input structXML data */
  var resultset:Resultset = new Resultset(XML(inputData));

  /** Create the sRelationBrowsercomponent */
  var semanticRelationBrowser:sRelationBrowser = new sRelationBrowser();

  /** Target type to focus on at load time */
  var targetTypes:Array = ["http://mytype"];

  /** Create the schema */
  var schema:Schema = new Schema();
  schema.loadSchema("http://schema.file.url");


  /** Initialize the semantic control */
  semanticRelationBrowser.percentWidth = 100;
  semanticRelationBrowser.percentHeight = 100;
  semanticRelationBrowser.semanticDataProvider = resultset;
  semanticRelationBrowser.targetTypes= targetTypes;
  semanticRelationBrowser.schema= schema;

  /** Add the sRelationBrowser to the main application */
  this.addChild(semanticRelationBrowser);

MXML Usage Examples

  <sRelationBrowser semanticDataProvider="{semanticDataProvider}"
                   targetTypes="{targetTypes}"
                   schema="{schema}" />

In this example, we assume that the {semanticDataProvider} variable is a Resultset, where the record description is defined, accessible at the creation time of the sRelationBrowser. targetTypes 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 sRelationBrowser on any HTML web page.

The sRelationBrowser 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 Portable Control Application 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 Portable Control Application 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 /bin/ or /bin-debug/ folder of your Flash Builder installation. For this documentation, let's say that all files are accessible here:

    http://my-site.com/flex/pca/

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 <head /> section of your HTML page:

  <script src="http://my-site.com/flex/pca/AC_OETags.js" language="javascript"></script>
 
  <!--  BEGIN Browser History required section -->
  <script src="http://my-site.com/flex/pca/history/history.js" language="javascript"></script>
 
  <!--  END Browser History required section -->
 
  <script language="JavaScript" type="text/javascript">
  <!--
  // -----------------------------------------------------------------------------
  // Globals
  // Major version of Flash required
  var requiredMajorVersion = 10;
  // Minor version of Flash required
  var requiredMinorVersion = 0;
  // Minor version of Flash required
  var requiredRevision = 0;
  // -----------------------------------------------------------------------------
  // -->

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

  <!--  BEGIN Browser History required section -->
  <link rel="stylesheet" type="text/css" href="http://my-site.com/flex/pca/history/history.css" />
  <!--  END Browser History required section -->

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:

  <div style="width: 280px; height: 280px; z-index: -999;">
    <script language="JavaScript" type="text/javascript">
    <!--
    // Version check for the Flash Player that has the ability to start Player Product Install (6.0r65)
    var hasProductInstall = DetectFlashVer(6, 0, 65);
 
    // Version check based upon the values defined in globals
    var hasRequestedVersion = DetectFlashVer(requiredMajorVersion, requiredMinorVersion, requiredRevision);
 
    if ( hasProductInstall && !hasRequestedVersion ) {
      // DO NOT MODIFY THE FOLLOWING FOUR LINES
      // Location visited after installation is complete if installation is required
      var MMPlayerType = (isIE == true) ? "ActiveX" : "PlugIn";
      var MMredirectURL = window.location;
        document.title = document.title.slice(0, 47) + " - Flash Player Installation";
        var MMdoctitle = document.title;
 
      AC_FL_RunContent(
        "src", "http://my-site.com/flex/pca/playerProductInstall.swf",
        "FlashVars", "MMredirectURL="+MMredirectURL+'&MMplayerType='+MMPlayerType+'&MMdoctitle='+MMdoctitle+"",
        "width", "100%",
        "height", "100%",
        "align", "middle",
        "id", "PortableControlApplication",
        "quality", "high",
        "bgcolor", "#869ca7",
        "name", "PortableControlApplication",
        "allowScriptAccess","sameDomain",
        "type", "application/x-shockwave-flash",
        "pluginspage", "http://www.adobe.com/go/getflashplayer",
        "wmode", "transparent"
      );
    } else if (hasRequestedVersion) {
      // if we've detected an acceptable version
      // embed the Flash Content SWF when all tests are passed
      AC_FL_RunContent(
          "src", "http://my-site.com/flex/pca/PortableControlApplication.swf",
          "width", "100%",
          "height", "100%",
          "align", "middle",
          "id", "PortableControlApplication",
          "quality", "high",
          "bgcolor", "#869ca7",
          "name", "PortableControlApplication",
          "allowScriptAccess","sameDomain",
 
          "allowFullScreen", "true",
 
          /* Relation Browser / LBNL */
          "flashVars", "baseAppUrl=[...]&inputSchemas=[...]&inputTargetRecords=[...]&inputTargetTypes=[...]&inputData=[...]",
          "type", "application/x-shockwave-flash",
          "pluginspage", "http://www.adobe.com/go/getflashplayer",
          "wmode", "transparent"
      );
      } else {  // flash is too old or we can't detect the plugin
        var alternateContent = 'Alternate HTML content should be placed here. '
        + 'This content requires the Adobe Flash Player. '
         + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>';
        document.write(alternateContent);  // insert non-flash content
      }
    // -->
    </script>
 
    <noscript>
        <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
          id="PortableControlApplication" width="100%" height="100%"
          codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
          <param name="movie" value="http://my-site.com/flex/pca/PortableControlApplication.swf" />
          <param name="quality" value="high" />
          <param name="bgcolor" value="#869ca7" />
          <param name="allowScriptAccess" value="sameDomain" />
          <param name="allowFulllScreen" value="true" />
          <param name="wmode" value="transparent" />
          <embed src="http://my-site.com/flex/pca/PortableControlApplication.swf" quality="high" bgcolor="#869ca7"
            width="100%" height="100%" name="PortableControlApplication" align="middle"
            play="true"
            loop="false"
            quality="high"
            allowScriptAccess="sameDomain"
            allowFullScreen="true"
            type="application/x-shockwave-flash"
            pluginspage="http://www.adobe.com/go/getflashplayer"
            wmode="transparent">
          </embed>
      </object>
    </noscript>
  </div>

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 sco:displayControl 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.

  <?xml version="1.0" encoding="utf-8"?>
  <schema>
    <version>0.1</version>
    <prefLabel>Simple Schema</prefLabel>
 
    <typeList>
      <umbel_SubjectConcept>
        <description>Subject Concept</description>
 
        <prefLabel>Subject Concept</prefLabel>
 
        <displayControl>sRelationBrowser</displayControl>
      </umbel_SubjectConcept>
    </typeList>
 
  </schema>

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:

  <?xml version="1.0" encoding="utf-8"?>
  <resultset>
    <prefix entity="owl" uri="http://www.w3.org/2002/07/owl#"/>
    <prefix entity="rdf" uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/>
    <prefix entity="rdfs" uri="http://www.w3.org/2000/01/rdf-schema#"/>
    <prefix entity="wsf" uri="http://purl.org/ontology/wsf#"/>
 
    <subject type="http://umbel.org/umbel#SubjectConcept" uri="http://purl.org/ontology/my-ontology/myRecord">
      <predicate type="http://www.w3.org/2004/02/skos/core#prefLabel">
        <object type="rdfs:Literal">My Input record</object>
      </predicate> 
    </subject>
 
  </resultset>

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:

Property Description
prefLabel The preferred label used to refer to the selected node.
prefURL The preferred URL where we can get more information about the selected node, on the Web.
description The description of the selected node.

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

  {prefLabel: type.prefLabel, prefURL: type.prefURL, description: type.description}

JavaScript Function

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

  function displayNodeDetails(details)
  {
    if(details != null)
    {
      document.getElementById('detailsPrefLabel').innerHTML = details.prefLabel;
      document.getElementById('detailsPrefURL').innerHTML = details.prefURL;
      document.getElementById('detailsDescription').innerHTML = details.description;
    }
  }

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

  <table>
    <tr>
      <td>prefLabel</td>
      <td id="detailsPrefLabel"></td>
    </tr>
    <tr>
      <td>prefLabel</td>
      <td id="detailsPrefURL"></td>
    </tr>
    <tr>
      <td>prefLabel</td>
      <td id="detailsDescription"></td>
    </tr>
  </table>

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 displayConceptsInformationHTML setting in the sRelationBrowser.xml 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:

Property Description
prefLabel The preferred label used to refer to the selected node.
link Link where a web page about the related things can be accessed.

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

  {prefLabel: thingPrefLabel, link: thingPageLink}

JavaScript Function

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

  function displayRelatedThings(links)
  {
    if(links != null)
    {
      cell = document.getElementById("relatedTechnologies");
 
      if(cell.hasChildNodes())
      {
        while(cell.childNodes.length >= 1)
        {
          cell.removeChild(cell.firstChild);       
        } 
      }
 
      for(var i in links)
      {
        if(links[i].link)
        {
          var thing = document.createElement("DIV");      
          thing.setAttribute("id", "relatedThing_" + i);
 
          var ahref = document.createElement("A");
          ahref.setAttribute("href", links[i].link);
 
          ahref.innerHTML = links[i].prefLabel;
 
          thing.appendChild(ahref);
 
          document.getElementById('relatedThings').appendChild(thing);    
 
          var br = document.createElement("BR");      
 
          document.getElementById('relatedThings').appendChild(br);    
        }
      }  
    }    
  }

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

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

  <div id="relatedThings">
 
  </div>

If you define this JavaScript function and this div 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 div.

Also note that you have to make sure to enable this feature by setting the displayRelatedThingsHTML setting in the sRelationBrowser.xml 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.
    1. 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:

Property Description
nodes A list of unique nodes type currently handled by the sRelationBrowser session.
edges A list of unique edges type currently handled by the sRelationBrowser session.

JavaScript Function

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

  // these two variables have to be global in scope
  var removedNodes = new Array();
  var removedEdges = new Array();
 
  // Make sure IE likes indexOf
  if(!Array.indexOf)
  {
    Array.prototype.indexOf = function(obj)
    {
      for(var i=0; i<this.length; i++)
      {
	if(this[i]==obj)
        {
	  return i;
	}
      }
      return -1;
    }
  }
 
  function populateFilterControl(nodes, edges)
  {
    var cell = document.getElementById("nodesFilters");
 
    if(cell.hasChildNodes())
    {
      while(cell.childNodes.length >= 1)
      {
        cell.removeChild(cell.firstChild);       
      } 
    }
 
    cell = document.getElementById("edgesFilters");
 
    if(cell.hasChildNodes())
    {
      while(cell.childNodes.length >= 1)
      {
        cell.removeChild(cell.firstChild);       
      } 
    }
 
    if(nodes != null)
    {
      for(var i in nodes)
      {
        var cb = document.createElement("INPUT"); // create input node
        cb.setAttribute("id", "filterNode_" + i);
        cb.setAttribute("type", "checkbox");
 
        if(removedNodes.indexOf(nodes[i].type) == -1)
        {
          cb.setAttribute("checked", true);
          cb.setAttribute("defaultChecked", true);
        }
 
        var funcCall = 'filterNodeChange(this, "filterNode_' + i + '", "' + nodes[i].type + '")';
        cb.onclick = new Function(funcCall);
 
        var nodeLabel = document.createTextNode(nodes[i].label); 
 
        document.getElementById('nodesFilters').appendChild(cb);    
        document.getElementById('nodesFilters').appendChild(nodeLabel);    
 
        var br = document.createElement("BR");      
        document.getElementById('nodesFilters').appendChild(br);   
      }       
    }
 
    if(edges != null)
    {
      for(var i in edges)
      {
        var cb = document.createElement("INPUT"); // create input node
        cb.setAttribute("id", "filterEdge_" + i);
        cb.setAttribute("type", "checkbox");
 
        if(removedEdges.indexOf(edges[i].type) == -1)
        {
          cb.setAttribute("checked", true);
          cb.setAttribute("defaultChecked", true);
        }
 
        var funcCall = 'filterEdgeChange(this, "filterEdge_' + i + '", "' + edges[i].type + '")';
        cb.onclick = new Function(funcCall);
 
        var edgeLabel = document.createTextNode(edges[i].label); 
 
        document.getElementById('edgesFilters').appendChild(cb);    
        document.getElementById('edgesFilters').appendChild(edgeLabel);    
 
        var br = document.createElement("BR");      
        document.getElementById('edgesFilters').appendChild(br);   
      }    
    }
  }

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

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

  <div id="nodesFilters">
 
  </div>
 
  <div id="edgesFilters">
 
  </div>

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

  function filterNodeChange(cb, id, type)
  {
    if(cb.checked)
    {
      // Make sure that it is not in the removedNodes array anymore
      var i = removedNodes.indexOf(type);
 
      if(i != -1) 
      {
        removedNodes.splice(i, 1);
      }
 
      // Now call the Flex APP to hide that node
      getFlexApp('idOfTheFlexApplicationInHtml').showNodeByType(type);
    }
    else
    {
      removedNodes.push(type);
 
      // Now call the Flex APP to hide that node
      getFlexApp('idOfTheFlexApplicationInHtml').hideNodeByType(type);
    }
  }
 
  function filterEdgeChange(cb, id, type)
  {
    if(cb.checked)
    {
      // Make sure that it is not in the removedNodes array anymore
      var i = removedEdges.indexOf(type);
 
      if(i != -1) 
      {
        removedEdges.splice(i, 1);
      }
 
      // Now call the Flex APP to hide that node
      getFlexApp('idOfTheFlexApplicationInHtml').showEdgeByType(type);
    }
    else
    {
      removedEdges.push(type);
 
      // Now call the Flex APP to hide that node
      getFlexApp('idOfTheFlexApplicationInHtml').hideEdgeByType(type);
    }
  }  
 
  function getFlexApp(appName)
  {
    if (navigator.appName.indexOf ("Microsoft") !=-1)
    {
      return window[appName];
    }
    else
    {
      return document[appName];
    }
  }


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 div 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 div.

Also note that you have to make sure to enable this feature by setting the displayFiltersHTML setting in the sRelationBrowser.xml 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.