Skip to content

Vizit Installation

Overview

This document explains how to embed Vizit in your website and also defines the parameters that are available in Vizit. It is intended for IT specialists, website administrators and web developers.

Note: For WordPress installations there is the Biovista Vizit WP plugin that simplifies installation even further. If your site is not managed by WordPress continue reading.

In order to embed Vizit in a web page you need to:

  • Include the Vizit script in the head section.
  • Allocate a space in the page through a div tag with a special id.
  • Prepare your server to handle search engines indexing.
  • Optionally utilize the javascript API of Vizit for interacting with Vizit programmatically.

There is no limit on how many times you can reuse Vizit throughout your website. However, only one Vizit instance can exist per page.

Getting started

Embedding Vizit in your website is easy. The code below demonstrates a minimal, yet working, bare-bones Vizit installation.

<html>
<head>
   <!--
       First step

       Load the Vizit code from the customer
       specific server, denoted by ${CLIENT_COMPANY}.
       This is the name the customer has used to
       register with Biovista (in lowercase).
   -->

   <script type="text/javascript" language="javascript"
       src="//${CLIENT_COMPANY}-ws.biovista.com/vizit/vizit/vizit.nocache.js">
   </script>
</head>

<body>
   <!--
       Second step

       Setup your HTML and allocate a div for Vizit
   -->

   <div id="bv-graphpanel" style="height: 600px"></div>

   <!--
      The Vizit div can be located anywhere in the page
   -->
</body>
</html>

The div with id bv-graphpanel is required in order to host Vizit. The height inside the style attribute can be specified in px or as a percentage following the standard HTML layout rules. The width may also be specified in the same vein. If the width is not specified, the Vizit graph will try to expand to the full available space following the standard block behavior of div elements. Note that if you don’t specify a div with the bv-graphpanel id Vizit will use the full browser’s window instead.

Google Indexing & Social Network support

Vizit is a modern web application that uses the url fragment (after #) to store, share and retrieve graphs. Normally the url after the # is not visible server side and until very recently it was not crawlable by Googlebot (which did not run javascript). To overcome this hurdle Google pusblished a set of guidelines called Ajax Crawling in 2009. This is essentially a promise that Google will revisit the page that has a hashbang (#!) in its url with the ?escaped_fragment (ugly url) parameter which is server visible and thus an appropriate snapshot could be served to the Googlebot. Note that Vizit is flexible and can be configured to not issue hashbang (#!) urls, effectively turning off indexing. For example a Vizit live graph link looks like: https://www.biovista.com/vizit/#!bv_gid=7446988030071c3745d24e53f5e70631. The GoogleBot crawler will note the hashbang(#!) and will try to crawl the following ugly url instead: https://www.biovista.com/vizit/?escaped_fragment=bv_gid=7446988030071c3745d24e53f5e70631.

Note: It is considered bad practice to link directly to ugly urls. While the proposal was officially deprecated (as of October 2015)

  • Google still uses it and indexes graphs based on it
  • Twitter uses it to pick up the image for the link to share
  • LinkedIn uses it to pick up the image for the link to share
  • Google+ uses it to pick up the image for the link to share
  • Facebook uses it to pick up the image for the link to share
  • Pinterest, Weibo, Tumblr do not implement ajax crawling but they provide an API that Vizit employs in order to enrich the post with an image of the graph and a back link to the originating page. The post has to be done through Vizit though.

and therefore it is strongly advised that Administrators and web developers wanting to integrate Vizit, to follow the Ajax Crawling proposal.

Here is how to do it assuming an Apache & PHP setup

  1. Donwload & Install the PHP vizit-redirect-crawl.php file
  2. Configure the vizit-redirect-crawl.php by editing the header of the file
  3. Setup appropriate pass-through redirection for ugly urls & vizit images:
RewriteCond %{QUERY_STRING} ^_escaped_fragment_
RewriteRule ^.*$ vizit-redirect-crawl.php [L,PT]

RewriteRule ^vizit-image/(.*)\.png$ /vizit-redirect-crawl.php?img=$1 [L,PT]

This way graph images are automatically included when a user posts a graph in a social network and the results can be visible to Google Images search.

Update: Googlebot has started running javascript and rendering the DOM tree therefore there are no actions required in order to support Google’s new crawling strategy. However the implementation of ajax crawling is still strongly recommended for social network support because posts with images have higher engagement and click through rates.

Integration Checklist

Please check the following list in order to make sure Vizit is properly installed and integrated to the hosting page.

  • Client Side:
    1. Vizit loads its configuration properly: Click on the + button in the top left and then on the drop down menu to select entity type. If the entity types (Gene, Disease, etc.) are displayed properly then Vizit is correctly installed and authorized. Tip: Contact Biovista to make sure your domain is authorized.
    2. When the url of the hosting page contains a graph (#!bv_gid= or #bv_gid=) then Vizit loads the graph and scrolls into position. Tips: Check the scrolling behavior of the hosting page.
      1. If the hosting page has placed Vizit behind an element such as a drawer or an image requiring user action (e.g. click to load) to display it then the hosting page must remove the hiding element and allow the loading of the Vizit script. Tip: Check Vizit page as an example of such behavior.
      2. If the hosting page normally autoloads a graph it should refrain from that so Vizit can load the graph specified in the url. Tip: Check Vizit page as an example of such behavior.
      3. If the hosting page automatically adds an entity and expands it should refrain from that so Vizit can load the graph specified in the url. Tip: See above tips.
  • Server Side:
    1. When the hosting page is invoked with url that contains the ?escaped_fragment=bv_gid= parameter the following must happen:
      1. A list of the entities involved is printed in a prominent place. Tip: Make sure the call to https://${CLIENT_COMPANY}-ws/ws/rest/v1/vizit/html succeeds.
      2. A graph image is displayed. Tip: Make sure the vizit-image RewriteRule is applied correctly.
      3. The graph image must point to the original graph url. Tip: Make sure the second argument ($vizit_url) is correctly guessed.
      4. The hosting page title contains some of the entities. Tip: Make sure the call to https://${CLIENT_COMPANY}-ws.biovista.com/ws/rest/v1/vizit/graph-entities succeeds.
    2. When a graph url is shared either via Vizit interface or directly by copying pasting the url the following should happen:
      1. LinkedIn automatically picks up the image. Tip: check head tag.
      2. Google+ automatically picks up the image. Tip: check head tag.
      3. Facebook automatically picks up the image. Tip: check head tag.
      4. Twitter automatically picks up the image. Tip: check head tag.
      5. Pinterest, Weibo, Tumblr automatically pick up the image with a backlink to the originating page for posts done using Vizit’s sharing button. Their support differs from the other social networks and the image of the graph is posted correctly only when sharing from inside Vizit.

Supported Browsers

Vizit is a modern HTML5 application. It requires a HTML5 capable browser that supports modern standards such as SVG and CORS. Browsers that are known to work are:

  • Firefox latest (versions 24 and later should work)
  • Chrome latest (versions 32 and later should work)
  • IE 11 latest (versions 10 and later should work)
  • Safari latest (versions 6 and later should work)
  • Mobile browsers in iOS and Android phones and tablets

Note: It is advised to update your browser for security reasons regardless of Vizit compatibility.