Difference between revisions of "Cavern Status Widget"

Revision as of 12:49, 18 October 2011

This is a simple widget that you can use in webpages to display the current status of the MOULagain servers.

http://assets.openuru.org/wiki/icons/note-edit-48x48.png

This page contains draft content
The content of this page is a "work-in-progress" and is subject to change. Do not place undue reliance on the completeness or accuracy of the material presented here!

General

During the development of the styling for the OpenUru.org website, it was felt that offering an indication of whether the MOULa cavern was open or not could be a useful feature. This already (partly) existed in the Cyan MOULa client launcher, in the form of the "welcome" message displayed during startup. By "piggybacking" on the source of that message, and after negotiating with Cyan on a standard for flags within the messages, it became possible to provide green, yellow or red status lights:

http://assets.openuru.org/wiki/img/led-green.gif

- Open. Logins are unrestricted.

http://assets.openuru.org/wiki/img/led-yellow.gif

- Restrictions. The cavern is open but some restrictions are in place, e.g. there is downtime scheduled to occur shortly.

http://assets.openuru.org/wiki/img/led-red.gif

- Closed. No user logins are permitted.

A link back to the "Play" page at mystonline.com was included in the displayed status to help support Cyan Worlds, as well as the entirety of the status message, which may at times include promotional messages for other Cyan products.

In response to enquiries following the announcement of this feature, a widget was split out from the site styling to allow others to include this in their own webpages. The widget can be made to display in various forms and styles using the control options described in the Usage section. Some examples are given in the following images:

http://assets.openuru.org/wiki/cavstat/cavstat1.png
Full Cavern Status with border line added

http://assets.openuru.org/wiki/cavstat/cavstat2.png
Minimised Cavern Status

http://assets.openuru.org/wiki/cavstat/cavstat3.png
Cavern Status with alternative colors

Usage

The simplest way to use the Cavern Status Widget is by inserting an iframe in your webpage at the point you'd like the widget to appear:

  <iframe src="http://www.openuru.org/tools/cavstat.php" width="550px" height="120px" frameborder="0">
    <p>Your browser does not support iframes.</p>
  </iframe>

The width and height settings in the iframe determine the size of the space allowed in your page for the status message. If the message box can't be fitted inside that space, then scroll bars may appear. Setting frameborder = "0" hides the rather ugly boundary that would otherwise be shown.

To avoid using an iframe or have more control over presentation, see Advanced topics.

Usage Notes

Recent updates to the code behind the widget introduced local caching of the status message that is fetched from Cyan's support server. This has a number of effects:

Page display is faster since there no longer is a need to wait on an additional GET each time the status message is displayed.
Page load will not "hang" for an extended time if the Cyan support server is offline.
Loading on the Cyan support server is limited and flattened out.
The displayed state of the Cavern may "lag" the true state by up to one minute (the cache refresh interval).

Please remember that the Cavern Status display is not dynamic: It will only update if you refresh or reload the page you are viewing. There is no universally easy way to have the server "push" a real-time update to your browser.

Controlling the appearance

You can control the appearance of the status message so that it blends better with your webpage: Add a '?' after the call to cavstat.php then list the parameter=value pairs, separating each with '&' and making sure to avoid leaving any spaces. The possible parameters are:

color= The color of the text as a hex value, omitting the usual leading '#' symbol. Defaults to black if parameter omitted.

bgcolor= The background color of the box containing the status message, as a hex value, omitting the usual leading '#' symbol. Defaults to grey (DDDDDD) if parameter omitted.

txtsize= The size of the body text of the message, e.g. 12pt, 14px, 1.1em. Defaults to 1.0em if parameter is omitted.

hdsize= The size of the heading text of the message, e.g. 12pt, 14px, 1.1em. The headings are bold, so you may want to reduce the size compared to the main text to restore some "balance". Defaults to 0.8em if parameter is omitted.

width= The width of the box containing the status message, in px or %. Note that the iframe may also have a width specified and you may need to adjust both get a satisfactory result. Defaults to 500px if parameter is omitted.

height= The height of the box containing the status message, in px or %. Note that the iframe may also have a height specified and you may need to adjust both get a satisfactory result. Defaults to 60px if parameter is omitted.

border= The color of the border around the box containing the status message, as a hex value, omitting the usual leading '#' symbol. The border is a 1px solid line and is only displayed if a value is specified, otherwise the box will be borderless (default).

type= Controls the display and styling type:
- maxi : The default display - shows the cavern status indication and a link to Cyan's "Play" page on the first line, and the Cyan "Developer's message" on the second line.
- midi : Single line display, with only the cavern status and the "Play" link.
- mini : Single line display, with only the cavern status included.
- raw : Most inline styling is removed and all other parameters are ignored. Used when applying local styling in more advanced uses (see below).
- jsonp : Provides the output in JSON-P (Javascript Object Notation with Padding) format, intended for javascript/jQuery users. See the additional notes below on using this option.

Example:

  <iframe src="http://www.openuru.org/tools/cavstat.php?bgcolor=ffdddd&hdsize=0.9em&border=000099" width="550px" height="120px" frameborder="0">
    <p>Your browser does not support iframes.</p>
  </iframe>

Advanced topics

PHP

If your page is written in PHP, you could use the cURL library to fetch the widget output and build it into your page. This would allow you to use the IDs and classes along with your own page CSS to apply styling. For this, you need to ensure that all unwanted inline styling is removed from the widget by using the ?type=raw control.

This will produce a code fragment that looks similar to:

  <div id="cspanel">
    <span class="cshead">Cavern Status:</span>
    <img src="http://www.openuru.org/sitestyle/img/led-green.gif"> Open for exploration! 
    <div id="cavstat_link">
      - <a href="http://mystonline.com/play/"> Sign up to play at MystOnline.com!</a>
    </div>
    <div id="cavstat_row2">
      <span class="cshead">Developer Message:</span> Welcome to Myst Online: Uru Live!
    </div>
    <div style="font-size: 8px; text-align: right;"><a href="http://www.openuru.org/">www.openuru.org</a></div>
  </div>

Include the following functions in your PHP:

  // Check availability of site
  function isURLOnline($sSiteToCheck)
  {
  	if(phpversion() > "5.2")
    {
      if(function_exists('get_headers')==True && ini_get('allow_url_fopen') == true)
      {
        $sIUOTemp = @get_headers($sSiteToCheck);
        if($sIUOTemp == '')
        {
          return True; // Assume it's online even when nothing is returned
        }
        else
        {
          if(strpos($sIUOTemp[0], '200') == true)
          {
            return True;
          }
          else
          {
            return False;
          }
        }
      }
      else
      {
        return True; // Assume true if we can't check it .......
      }
    }
    else
    {
      return True; // get_headers apparently isn't available in PHP4
    }
  }

  // Gets a URL's content
  function getURL($sURL)
  {
    if(isURLOnline($sURL) == false)
    {
      $sURLTemp = 'Unable to connect to server';
      return $sURLTemp;
    }
    else
    {
      if(@function_exists('file_get_contents') && @ini_get('allow_url_fopen') == true)
      {
        // Use file_get_contents
        $sURLTemp = @file_get_contents($sURL);
      }
      else
      {
        // Use cURL (if available)
        $curl = @curl_init();
        curl_setopt($curl, CURLOPT_URL, $sURL);
        curl_setopt($curl, CURLOPT_VERBOSE, 1);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HEADER, 0);
        curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
        $sURLTemp = @curl_exec($curl);
        @curl_close($curl);
      }
      return $sURLTemp;
    }
  }

Fetch the code fragment using a line similar to this:

  $cavernStatus=getURL("<nowiki>http://www.openuru.org/tools/cavstat.php?type=raw</nowiki>");

This will give you the entire fragment in a string, $cavernStatus, that you can then echo to your own page or manipulate as you wish.

JSON-P

Setting the type argument in a request to "jsonp" will return output formatted for Javascript Object Notation with Padding, essentially an object of data passed to a callback function. This method is essential if you are trying to fetch the CAVCON data with javascript (due to the same-origin-policy applied by most browsers). To know more about JSONP, its usage and the reason of its existance read Wikipedia's Article. When using this option, it is also necessary to specify the function name of the callback procedure that will parse the returned array in the client, so a second argument, jsoncallback, must be supplied as in the following example:

http://www.openuru.org/tools/cavstat.php?type=jsonp&jsoncallback=anyFunctionName

Note that the name of the callback function is not important as far as the server is concerned, but it must be supplied otherwise an error message will be returned.

In response, the server will return data similar to the following:

anyFunctionName({"LED": "http://www.openuru.org/sitestyle/img/led-green.gif", 
"State": "Open for exploration!", "Link": "Sign up to play at MystOnline.com!", 
"LinkURL": "http://mystonline.com/play/", "Message": "Welcome to Myst Online: Uru Live! 
Bug Chucker now available on Android Marketplace!", "Origin": "www.openuru.org", 
"OriginURL": "http://www.openuru.org/"})

For clarity, the array returned in the padded object consists of the following members:

"LED": A URL to the applicable colored status "lamp"; red green or yellow,
"State": Text string indicating the state of the cavern,
"Link": Text message intended to be used as anchor text for LinkURL,
"LinkURL": URL to the current MOULa sign-up/play page at mystonline.com,
"Message": The Cyan developer message, as shown on the MOULa startup dialogs,
"Origin": Text message intended to be used as anchor text for OriginURL.
"OriginURL": URL of the site that the status message has been delivered from.

There is no requirement that the end user implements all of these, or that they represent them in any particular manner giving the page designer complete freedom to manage the usage, format and layout as best suits their intended page layout.

jQuery

The following code can be used to dynamically update the cavern widget on a webpage. This is an independent code, it does not need the PHP code above, just include the jQuery library in your webpage.

Include the following code in the scripts of your webpage. The code assumes you are not using the "No Conflict" option of jQuery. If you are using it, change all the calls to "$" with calls to "jQuery".

function CavernStatus(el){
  $.ajax({
    type:'GET',
    url:'http://www.openuru.org/tools/cavstat.php',
    data: 'type=jsonp',
    dataType: 'jsonp',
    jsonp: 'jsoncallback',
    crossDomain: true,
    success: function(data){
      //In this point, if you want, you can manipulate the HTML elements received from OpenUru
      output='<div id="cspanel"><span class="cshead">Cavern Status:</span><img src="'+data.LED+'"> '+data.State+'<div id="cavstat_link"> - <a href="'+data.LinkURL+'" target="_blank"> '+data.Link+'</a></div><div id="cavstat_row2"><span class="cshead">Developer Message:</span> '+data.Message+' </div><div style="font-size: 8px; text-align: right;"><a href="'+data.OriginURL+'">'+data.Origin+'</a></div></div>';
      $(el).html(output);
    },
    error: function(jqXHR, textStatus, errorThrown){//What to do if error happens
      //You can choose to let the user know the request didn't succeed
    },
    timeout: 1500//Script timesout in 1.5 seconds if server doesn't respond
  })
}

In the code above you can see the output variable that contains the HTML code that will be generated in your web page, you can customize it to follow your website design or preferences. To know more about the member variables of the data object please consult the section JSONP above. Optionally you can insert some error handling code in the error function, where we placed just a comment.

Call the CavernStatus function somewhere in your code (usually when document is ready, with $.ready()), passing the jQuery selector for the element where you want to put the widget. Call it every X seconds to make the widget update dynamically. In this example we assume the id of the element that will contain the Cavern Status Widget is "widget"

<script type="text/javascript">
$(function(){//Short version of $.ready()
  CavernStatus('#widget')//Initial Loading
  setInterval("CavernStatus('#widget')",600000)//Update the widget every 10 minutes.
})
</script>

In Memoriam: Tai'lahr