DJS Tutorial

  DJS is a distributed object library for Server-WebBrowser communication. This tutorial shows how to create a web application using DJS.

===============
Getting started
===============

- Creating a DJS connection class

  A DJS connection class is where you write the scripts to manipulate the browser-side objects from server. The DJS connection class must be subclass of 'DJS::DJSConnection'. An instance of DJS connection class will be created when the connection between browser and DJS server is established. There are four methods in 'DJS::DJSConnection' that can be overridden to tell DJS what to do.

  on_open()       - Called when the connection is established.
  on_error(err)   - Called when an browser-side error occurs.
  on_message(msg) - Called when an message is received from browser.(not implemented)
  on_close()      - Called when the connection is shutdown.(not implemented)

  Here is an example:
#
  class MyConnection < DJS::Connection
    def on_open
      window.alert "Hello world!"
    end
    def on_error(error)
      p error
    end
  end
#

- Starting DJS server

  After a DJS connection class is defined, you can start DJS server using 'DJS::start(klass)' method. Your DJS connection class must be passed as the argument.
#
  DJS.start(MyConnection, {:host => 127.0.0.1, :port => 8080})
#

- Adding DJS library to HTML

  Add DJS JavaScript library 'djs.js' in your HTML. And call 'djs.start(host)' to connect to a DJS server.
#
  <script type="text/javascript" src="djs.js"></script>
  <script type="text/javascript">
    window.onload = function() {
      djs.start("ws://127.0.0.1:8080");
    }
  </script>
#

- Stopping DJS server

  Use 'DJS.stop' to stop a DJS server.
#
  DJS.stop
#

========
API Docs
========

* Module: DJS

  - DJS.start(klass, opts = {})
    
    Start DJS server.

    Parameters:
      klass (Class) - A class that extends DJS::Connection
      opts (Hash) - Options. Default values are as below:
        :buff_size => 200 - Messages stored before synchronization with browser.

  - DJS.stop

    Stop DJS server.

  - DJS.connections

    Return all DJS connection instances that the DJS server is holding currently.

    Returns:
      (DJS::Connections) - An DJS::Connections instance that contains all DJS::Connection instances the DJS server is holding currently.

    Examples:
      DJS.connections.do_something
  

* Class: DJS::Connection

  - sync

    Synchronize with browser immediately.

  - window

    A reference for browser-side object 'window'.

   Returns:
     (DJS::ProxyObject) - A DJS::ProxyObject that references to browser-side object 'window'.

   Examples:
     window.alert "Hello world."

* Class: DJS:ProxyObject

  - sync, to_s, to_f, to_i, to_a, to_h, to_b

    Synchronize with browser immediately and return the true value of the referenced object.

    Returns:
      (Object) - Primitive type if the referenced object is primitive, otherwise the DJS::ProxyObject itself.

    Examples:
      value = document.getElementById("text").value.sync

=====
Hints
=====

- Define a event handler as 'object.event_name = :event_handler_name'
  Examples:
    def button_click_handler(event)
      button = event.srcElement
    end
    document.getElementById("button").onclick = :button_click_handler