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

{{draft}}

==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:
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-green.gif</div>  - Open. Logins are unrestricted.</p>
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-yellow.gif</div>  - Restrictions. The cavern is open but some restrictions are in place, e.g. there is downtime scheduled to occur shortly.</p>
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-red.gif</div>  - Closed. No user logins are permitted.</p>

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|Usage section]]. Some examples are given in the following images:

<center>http://assets.openuru.org/wiki/cavstat/cavstat1.png<br>
'''Full Cavern Status with border line added'''</center>

<center>http://assets.openuru.org/wiki/cavstat/cavstat2.png<br>
'''Minimised Cavern Status'''</center>

<center>http://assets.openuru.org/wiki/cavstat/cavstat3.png<br>
'''Cavern Status with alternative colors'''</center>

==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:

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

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 <code>frameborder = "0"</code> hides the rather ugly boundary that would otherwise be shown.

To avoid using an iframe or have more control over presentation, see [[#Advanced_topics|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).

Example:
<syntaxhighlight lang="html4strict">
<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>
</syntaxhighlight>

==Advanced topics==
=== PHP ===
If your page is written in PHP, you could use the [http://www.php.net/manual/en/book.curl.php 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 <code>?type=raw</code> control.

This will produce a code fragment that looks similar to:
<syntaxhighlight lang="html4strict">
<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>
</syntaxhighlight>

Include the following functions in your PHP:
<syntaxhighlight lang="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;
}
}
</syntaxhighlight>

Fetch the code fragment using a line similar to this:

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

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.

=== jQuery ===
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".
<syntaxhighlight lang="jquery">
function CavernStatus(el){
$.ajax({
type:'GET',
url:'http://www.openuru.org/tools/cavstat.php',
data: 'type=raw',
success: function(data){
//In this point, if you want, you can manipulate the HTML elements received from OpenUru
$(el).html(data);
},
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
dataType: 'html',
})
}
</syntaxhighlight>
You can insert manipulation of the HTML received from OpenUru and Error Handling where specified.

Call this 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. Optionally you can call it every X seconds to make the widget update dinamically.
<syntaxhighlight lang="html4strict">
<script type="text/javascript">
$(function(){//Short version of $.ready()
CavernStatus('#widget')//Initial Loading
setInterval("CavernStatus('#widget')",600000)//Update the widget every 10 minutes.
})
</script>
</syntaxhighlight>
[[Category:Documentation]]
[[Category:OpenUru.org]]

Cavern Status Widget

2011-10-15T13:45:22Z

Leonardo: /* JQuery */

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

{{draft}}

==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:
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-green.gif</div>  - Open. Logins are unrestricted.</p>
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-yellow.gif</div>  - Restrictions. The cavern is open but some restrictions are in place, e.g. there is downtime scheduled to occur shortly.</p>
<p><div style="float: left">http://assets.openuru.org/wiki/img/led-red.gif</div>  - Closed. No user logins are permitted.</p>

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|Usage section]]. Some examples are given in the following images:

<center>http://assets.openuru.org/wiki/cavstat/cavstat1.png<br>
'''Full Cavern Status with border line added'''</center>

<center>http://assets.openuru.org/wiki/cavstat/cavstat2.png<br>
'''Minimised Cavern Status'''</center>

<center>http://assets.openuru.org/wiki/cavstat/cavstat3.png<br>
'''Cavern Status with alternative colors'''</center>

==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:

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

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 <code>frameborder = "0"</code> hides the rather ugly boundary that would otherwise be shown.

To avoid using an iframe or have more control over presentation, see [[#Advanced_topics|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).

Example:
<syntaxhighlight lang="html4strict">
<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>
</syntaxhighlight>

==Advanced topics==
=== PHP ===
If your page is written in PHP, you could use the [http://www.php.net/manual/en/book.curl.php 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 <code>?type=raw</code> control.

This will produce a code fragment that looks similar to:
<syntaxhighlight lang="html4strict">
<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>
</syntaxhighlight>

Include the following functions in your PHP:
<syntaxhighlight lang="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;
}
}
</syntaxhighlight>

Fetch the code fragment using a line similar to this:

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

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.

=== jQuery ===
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".
<syntaxhighlight lang="jquery">
function CavernStatus(el){
$.ajax({
type:'GET',
url:'http://www.openuru.org/tools/cavstat.php',
data: 'type=raw',
success: function(data){
//In this point, if you want, you can manipulate the HTML elements received from OpenUru
$(el).html(data);
},
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
dataType: 'html',
})
}
</syntaxhighlight>
You can insert manipulation of the HTML received from OpenUru and Error Handling where specified.

Call this 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. Optionally you can call it every X seconds to make the widget update dinamically.

====Example:====
<syntaxhighlight lang="html4strict">
<script type="text/javascript">
$(function(){//Short version of $.ready()
CavernStatus('#widget')//Initial Loading
setInterval("CavernStatus('#widget')",600000)//Update the widget every 10 minutes.
})
</script>
</syntaxhighlight>
[[Category:Documentation]]
[[Category:OpenUru.org]]