Hyzobox Script Basics

This article explains the basics of Hyzobox script. It describes the parameters of Hyzobox.createInstance method and shows how you can render the games asynchronously (for example after document loaded event).

Hyzobox makes it very easy for publishers to embed Hyzonia games. You just copy four lines of codes from publishers control panel and paste it in your HTML page:

<script type="text/javascript" 
   src="http://www.hyzonia.com/hbox.axd?gt=popndrop"></script>
<script type="text/javascript">
    Hyzobox.createInstance("popndrop", "paradise.hyzonia.com")
      .render();
</script>

Usually you don't need to modify this code unless you are interested in more advanced features of Hyzobox. One popular example is Integration Services, by which you can automatically login your users into the games.

In this article we explore the basics of Hyzobox script in more details.

To embed a game first you have to load Hyzobox base script in your page by:

<script type="text/javascript" 
   src="http://www.hyzonia.com/hbox.axd?gt=popndrop"></script>

Note that this script receives a gt (game type) parameter. Knowing the game type an enhanced version of the script will be loaded. At the time being all game types (PopNDrop, HiddenObjects, BubblePopper, Fishing, UFOs, FunkyMonkey, Shop) use the same base. If you want to have more than one game in a page, you don't need to load this script twice. gt is not case sensitive.

Hyzobox.createInstance() function creates an instance of Hyzobox object. It takes three parameters: game type and the instance name of the game and options. Instance name is usually in this format: [name].hyzonia.com. Note if you are developing a game at Island level, here you should pass the full URI of your Island. By default game type and game instance name are not case sensitive. Options is a JSON object. It is optional. See an example of how it is used here.

Hyzobox.createInstance() returns a reference to the Hyzobox object it creates. You can assign it to a variable:

var hb = Hyzobox.createInstance("popndrop",
   "paradise.hyzonia.com");

Hyzobox object supports a plug-in model, it is possible to load new functionalities for it later (after it instantiated). Depending on the loaded features, Hyzobox instance supports a variety of methods and attributes.

The most important method of Hyzobox object is render(). render() adds the instance to the HTML page. When you call render() with no parameter it uses document.write() to write a div and an iframe. It adds the game instance at exactly the point it was called.

For example:

<script type="text/javascript">
    Hyzobox.createInstance("popndrop", "paradise.hyzonia.com");
</script>

<div id='gameContainer'>
 <script type="text/javascript">
    hb.render();
 </script>
</div>

Here the game will be inserted in the 'gameContainer' div.

This behavior is not always preferred. In some cases you may want to render Hyzobox object after the page is loaded or an event is triggered.

You can pass a reference to an HTML element to render() method. In this case render() uses document.createElement() to create and insert div and iframe inside the given element and DOM. For example:

<div id='gameContainer'>
</div>

<script type="text/javascript">
    var hb = Hyzobox.createInstance("popndrop",
      "paradise.hyzonia.com");
    hb.render(document.getElementById("gameContainer"));
</script>

The output of this code snippet is similar to the previous one, it adds the game inside the 'gameContainer' div. Note that render(refToHTMLElement) could be called at anytime.