Table of Contents for

Opa: Up and Running

To start the new chat application, simply write:

Tokyo:~ henri$ opa create chat

This will create a chat directory and generate a scaffolding for a new Opa app, with the following content:

+- chat
| +- Makefile
| +- Makefile.common
| +- opa.conf
| +- resources
| | +- css
| | | +- style.css
| +- src
| | +- model.opa
| | +- view.opa
| | +- controller.opa

The project includes:

To compile and run the project, type:

Tokyo:~ henri$ cd chat; make run

Let’s start with the user interface; here we see the view part of the application, with which you should already be familiar:

module View {

   // View code goes here

  function page_template(content) {
    <div class="navbar navbar-inverse navbar-fixed-top">
      <div class=navbar-inner>
        <div class=container>
          <a class=brand href="#">
            Opa Chat
          </a>
        </div>
      </div>
    </div>
    <div id=#main>
      {content}
    </div>
  }

  function default_page() {
    content =
      <div class="hero-unit">
        Page content goes here...
      </div>
    page_template("Default page", content)
  }

}

The View module has two functions: page_template, which contains a generic template for any page, and default_page, which uses page_template to build a page.

For the chat app, you need to modify the page_template and default_page functions of the View module to obtain the desired look and feel for the app. The template also automatically places a CSS stylesheet in resources/css/style.css, which you may want to modify as well.

Now that you have the skeleton of the user interface in place, it’s time to bring it to life by adding application logic. This is the model part of the application, in which you define the application data, as well as its manipulation and storage, that you wrote in src/model.opa.

A chat app is about communicating messages between users. This means you need to decide what type of messages you wish to transmit.

In its minimal form, a message is a record that contains two fields: author (which is a string, i.e., some text) and text (also a string):

type message = {string author, string text}

Now that you know what a message is, you need to figure out how to pass it around to different clients. Opa provides three methods of communication between clients and the server:

For the chat application, you have a number of clients connected to the chat room, and they all need to be informed of every message posted; therefore, you will use a network:

private Network.network(message) room = Network.cloud("room")

This extract creates a cloud network (ensuring that it will be shared among all running instances of the application) called “room.” The cloud name comes from the world of cloud computing and stresses that the networks can be easily distributed among several servers, although scaling Opa is not yet part of this book.

As is the case with everything in Opa, networks have a type. The type of this network is Network.network(message), which means this is a network used to transmit data of type message.

By declaring this value as private, you ensure that it is not accessible from outside the Model and that other functions need to be used to manipulate it. This concept, known as encapsulation or information hiding, is crucial for writing modular, well-designed programs. We will discuss this further in Packages.

You will need two such functions: one to broadcast a message to all clients and another one to register a callback, which will be invoked whenever a new message has been posted:

function broadcast(message) {
  Network.broadcast(message, room);
}

function register_message_callback(callback) {
  Network.add_callback(callback, room);
}

Both functions simply invoke relevant features from the Network module.

Finally, you need a function to assign usernames to newly connected users. As mentioned earlier, you will simplify the app by choosing those names at random:

function new_author() {
  Random.string(8);
}

The complete source of the model follows:

type message = { string author
               , string text
               }

module Model {

  private Network.network(message) room = Network.cloud("room")

  exposed function broadcast(message) {
    Network.broadcast(message, room);
  }

  function register_message_callback(callback) {
    Network.add_callback(callback, room);
  }

  function new_author() {
    Random.string(8);
  }

}

Now it is time to connect the model and the view.

Connecting the model and the view requires simply calling functions from Model in View. Let’s start with a very simple call: author name generation.

In the View module, update the default_page function as follows:

function default_page() {
  author = Model.new_author();
  page_template("Opa chat", (chat_html(author)))
}

Next, you will learn how to do the following:

function user_update(message msg) {
 line = <div class="row-fluid line">
           <div class="span1 userpic">
            <img src="/resources/img/default-user.jpg" alt="User"/>
           </div>
           <div class="span2 user">{msg.author}:</>
           <div class="span9 message">{msg.text}</>
         </div>;
  #conversation =+ line;
  Dom.scroll_to_bottom(#conversation);
}

function broadcast(author) {
  text = Dom.get_value(#entry);
  Model.broadcast(~{author, text});
  Dom.clear_value(#entry);
}

function chat_html(author) {
  <div id=#conversation
    onready={function(_) { Model.register_message_callback(user_update)}} />
  <div id=#footer class="navbar navbar-fixed-bottom">
    <div class=container>
      <div class=input-append>
        <input id=#entry class=input-xxlarge type=text
          onnewline={function(_) { broadcast(author) }}>
        <button class="btn btn-primary" type=button
          onclick={function(_) { broadcast(author) }}>Post</>
      </div>
    </div>
  </div>
}

Tokyo:~ henri$ make run

This advanced section explains the low-level mechanism of networks, which are also accessible in Opa. As we said earlier, networks are based on a lower-level object named sessions. A session in Opa is a unit of state and concurrency:

Let’s detail a generic use of sessions, as represented in Figure 6-2.

Figure 6-2. Flow of information in Opa sessions

To create a new session, you write:

chan = Session.make(msg_handler, initial_state)

The resultant value, chan, is a channel that can be used to communicate with the session.

The parameters are initial_state, the value for the initial state of the session, and msg_handler, which is the handler used to process messages sent to this session.

Before we look in detail at what the handler is, note that when chan is created server-side, the session will stay server-side. Reciprocally, if the session is created client-side, it will stay client-side.

The message handler is a function that takes two parameters:

The message responds with a Session.instruction. This has the following type:

type Session.instruction('state) = {'state set} or {unchanged} or {stop}

The preceding type is a variant of these three types:

Let’s use this. On a server-side function, you can call:

Session.send(msg1, chan)

This causes asynchronous sending of msg1 to the session identified with chan. Upon receipt of this message, the session will invoke the message handler, in this case resulting in a call to msg_handler(initial_state, msg1).

If the handler responds with {set: state1}, state1 will become the new state of the session.

Later, when the application is executed, a client-side function may then send the following from Client 1:

Session.send(msg2, chan)

Then it may send the following from another client, Client 2:

Session.send(msg3, chan)

As a result, “Client 2” will reciprocally invoke msg_handler(state1, msg2) and msg_handler(state2, msg3).

Thanks to Opa’s transparent client/server communication, although chan resides server-side, it is OK to pass chan as an argument in the program flow to make it accessible client-side, for instance. It’s that simple.

In Opa, you can directly use high-level networks for real-time web applications, but the low-level sessions on which they are built can also be very useful in many more situations.

Now it’s time to apply what you have learned! Here are a few exercises that will test your Opa skills.