Skip to content

Introduction to JavaScript client

Jump to bottom
bristleback edited this page Aug 3, 2013 · 8 revisions

Bristleback JavaScript client library provides simple and powerful API to cooperate with the server side. Similarly to the server side, client library contains modules for data controller and serialization engine. The main client class - Bristleback.Client - represents single client-server connection. Client class contains basic methods for connecting and checking connection status. All incoming messages are serialized by the serialization engine and passed to the client data controller. While connecting, client decides which protocol to use (in Bristleback, second name for protocol is Data Controller). Client must provide data controller capable of handling chosen protocol. For example, when connecting using protocol with name sample.protocol, fallowing conditions must be fulfilled:

  1. Server contains DataController implementation with name sample.protocol, and this implementation appears on the accepted protocols list.
  2. Client side contains data controller that is registered in Bristleback.controller.controllers map.
Of course, Bristleback provides client side action controller, which is chosen by default when connecting to the server. In next subsection we’ll create sample client site and introduce basic client functionalities.

Table of Contents

Client Hello World

Connecting

On following snippet (which is taken from Project Setup tutorial) there is a webpage containing two buttons for connecting and disconnecting. 

    <html>
    <head>
      <script type="text/javascript" src="./bristleback-0.3.5.js"></script>
    
      <script type="text/javascript">
        var config = {
          serverUrl: "ws://localhost:8765/websocket",
          onOpen: function(event) {
            document.getElementById('status').innerHTML = "The WebSocket Connection Is Open.";
          },
          onClose: function(event) {
            document.getElementById('status').innerHTML = "The WebSocket Connection Is Closed.";
          }
        };
        var client = Bristleback.newClient(config);
        var dataController = client.dataController;
    
        function connect() {
          client.connect();
          Bristleback.Console.enableConsole();
        }
    
        function closeConnection() {
          client.disconnect();
        }
    
      </script>
    
    </head>
    
    <body>
    <div id="status">Click connect button to start playing.</div>
    <div>
      <input type="button" onclick="connect()" value="Connect">
      <input type="button" onclick="closeConnection()" value="Close connection">
    </div>
    
    </body>
    </html>

The code is rather simple, nevertheless we will briefly describe each line. Firstly, we included Bristleback Client library. Then we defined connection configuration object, with connecting and disconnecting callbacks and server url specified. Configuration object has more options that were presented in this sample, all properties have default values. More about configuration object and connecting process is said in Connection section. Next, we create instance of Bristleback.Client class by invoking factory method: 

    var client = Bristleback.newClient(config);

As we said earlier, Client encapsulates WebSocket object, which represents actual connection. Client should be generally used only to connect and disconnect from the server. The list of Bristleback.Client methods can be found in Client Connection chapter. Whole remaining application logic is done using Data Controller: 

    var dataController = client.dataController;

Finally we defined methods for connection/disconnection and added some html code.

Starting from 0.3.5, you can use BB keyword instead of Bristleback, for example: 
    var client = BB.newClient(config);

Defining server actions

Creating server action classes is done using Bristleback.controller.ActionController class, which is the default data controller. Below there is a client side of Action class taken from Action Controller section: 

    var sampleActionClass = dataController.getActionClass("Sample"); // resolving action class
    sampleActionClass 
      .defineAction("hello") //defining new action
      .setResponseHandler(function(helloWorld) { //setting response handler
        document.getElementById('status').innerHTML = helloWorld;
    });

From now on, we can invoke action hello of action class Sample: 

    sampleActionClass.hello("John Rambo", 66);

Defining client actions

Defining client actions is even simpler than creating server actions, just create an object with methods and register it with action data controller: 

    var sampleClientActionClass = {
      sayHello: function(helloWorld) {
        $('#status').text(helloWorld);
      }
    };
    
    dataController.registerClientActionClass("SampleClientActionClass", sampleClientActionClass);

More about client actions on client side can be found in Client actions section. To know how to define client action class on the server, check Client Actions - high level server messages section.

Clone this wiki locally