Table of Contents for

Opa: Up and Running

To analyze all the special elements in our messages, we will need to parse them. Parsing is the process of analyzing text to determine its structure. The code that performs such an analysis is called a parser. Opa offers extensive support for building parsers, so let’s begin by exploring this support.

Parsing is somewhat similar to pattern matching. Pattern matching analyzes an arbitrary data structure and computes some value depending on the result of this analysis. Parsing is a similar process, only the input is a string. In Opa, parsing can also be applied to one of the foundation data types of web apps: XML. Therefore, parsing in Opa is a way to compute a result depending on the value of a string or an XML fragment; but this book only covers parsing of strings.

The code that performs parsing is called a parser. Opa offers extensive support for building parsers, so let’s begin by exploring it. Opa parsers are introduced with the parser keyword followed by a number of cases. Each case follows this scheme:

case EXPR: VALUE

This consists of the case keyword (just like in pattern matching) and then a parsing expression (more on that shortly) and the value corresponding to the given case (again, just like in pattern matching). Cases are evaluated one by one, in order. Similar to pattern matching, the first succesful VALUE is used. Note that VALUEs in all parser cases must be of the same type t, and then the type of the complete parser expression is Parser.general_parser(t).

Now let’s explore the parsing expressions. The simplest one is just an explicit literal string where the parsed string contains the given text. Hence, the simplest parser one can write is:

simple_parser =
  parser {
    case "Hello Opa": {success}
  }

This has only one case, which expects the precise Hello Opa text. It has type Parser.general_parser({success}). The main function that uses such parsers is:

Parser.try_parse(parser, text)

This function takes two arguments: the first one is the parser to be used and the second one is the text (string) to parse. The result is option(t) if parser was of type Parser.general_parser(t), i.e., it is an optional value of the type produced by the parser.

For example, we will have the following two results:

Parser.try_parse(simple_parser, "Hello Opa") == some({success})
Parser.try_parse(simple_parser, "Hello") == none

word = parser { case word=([a-zA-Z0-9_\-]+) -> Text.to_string(word) }

element = parser {
    case "@" user=word: ~{user}
    case "#" topic=word: ~{topic}
    case &"http://" url=Uri.uri_parser: {link: url}
    }

segment_parser = parser {
    case ~element: element
    case text=word: {~text}
    case c=(.): {text: Text.to_string(c)}
    }

msg_parser = parser { case res=segment_parser*: res }

We are now ready to provide a model for Birdy messages. We create a model file, src/model/msg.opa, and add it to the project (i.e., to the opa.conf file).

We then provide a definition for a message, Msg.t, which consists of the message content (content), its author (author), and the date it was published (created_at). We make it abstract as well:

abstract type Msg.t =
  { string content,
    User.t author,
    Date.date created_at
  }

We also introduce a type for a message segment, Msg.segment, in the sense introduced in the previous section:

type Msg.segment =
  { string text } or
  { Uri.uri link } or
  { User.name user } or
  { Topic.t topic }

Finally, we build a Msg module, with two accessory functions for message fields and a function to create a new message, as well as the parser we developed previously. We expose this parser as an analyze function, which takes a message, Msg.t, and returns the list of segments, list(Msg.segment), it is composed of:

module Msg {

  function Msg.t create(User.t author, string content) {
    { ~content, ~author, created_at: Date.now() }
  }

  function get_author(Msg.t msg) { msg.author }
  function get_created_at(Msg.t msg) { msg.created_at }

  private function list(Msg.segment) analyze(Msg.t msg) {
    word = parser { case word=([a-zA-Z0-9_\-]+) -> Text.to_string(word) }
    element = parser {
    case "@" user=word: ~{user}
    case "#" topic=word: ~{topic}
    case &"http://" url=Uri.uri_parser: {link: url}
    }
    segment_parser = parser {
    case ~element: element
    case text=word: {~text}
    case c=(.): {text: Text.to_string(c)}
    }
    msg_parser = parser { case res=segment_parser*: res }
    Parser.parse(msg_parser, msg.content)
  }

}

It’s time to turn our attention to the user interface. Let’s create an src/view/msg.opa file; we’ll use the same filename as before, as we are still dealing with messages, but we’ll put it in the view directory. Also, the model code was placed in the Msg module, but all the code of this chapter will go into the MsgUI module. We’ll then add it to the project as usual, in src/opa.conf.

We will first write a function to show (render) a message to the user:

function xhtml render(Msg.t msg) {
  msg_author = Msg.get_author(msg)
  <div class=well>
    <p class="author-info">
      <strong><a href="/user/{msg_author}">@{msg_author}</a></strong>
      <span>{Date.to_string(Msg.get_created_at(msg))}</span>
    </p>
    <p>
      {List.map(render_segment, Msg.analyze(msg))}
    </p>
  </div>
}

This function creates a <div> with a well class, which is Bootstrap markup for a page element with an inset effect. The element consists of two paragraphs (<p>). The first one contains a <strong> tag (bold text) which contains a link to the author, msg_author, and a <span> tag which contains the message creation date. Note how we use accessor methods from the Msg module; this is because the Msg.t type is abstract, and hence, its structure is only visible in the birdy.model package and outside of it must be manipulated with functions from that package. This is data abstraction at work.

The second paragraph contains the text of the message itself. To obtain it, we use the Msg.analyze function which gets the list of the message segments, and then we use the List.map function to convert each segment into its HTML representation using the following render_segment function:

private function render_segment(Msg.segment seg) {
  match (seg) {
  case ~{user}:
    <b><a class=ref-user href="/user/{user}">@{user}</a></b>
  case ~{topic}:
    <i><a class=ref-topic href="/topic/{topic}">#{topic}</a></i>
  case ~{link}:
    <a href={link}>{Uri.to_string(link)}</a>
  case ~{text}:
    <>{text}</>
  }
}

This function just does the pattern matching of the segment type, and for every possible variant produces its HTML representation: both user mentions and topics are rendered as links, the former with a bold style (<b>) and linking to /user/[USERNAME] URLs and the latter with italics (<i>) and linking to /topic/[TOPICNAME]. We will talk about how we are going to handle those URLs in User and Topic Pages. Link segments are just rendered as HTML links (<a>) and text as normal text.

There is one small caveat. If you try to use the preceding code to render a message, you will be greeted with the following message:

Can't make an xml with {email : Email.email; username : string}

This is because in the earlier snippet, in the render function, we used an insert with a User.t value of the message author:

[...]
    <strong><a href="/user/{msg_author}">@{msg_author}</a></strong>
[...]

The error message essentially says that the Opa compiler does not know how to display values of that type. We can instruct it by creating an xmlizer, which is a special function that converts an arbitrary data type to HTML. For User.t values, it could look as follows:

@xmlizer(User.t) function user_to_xml(user) {
  <>{user.username}</>
}

The return type of this function must be of type xhtml. The only special thing about this function is the @xmlizer(User.t) annotation, which translates to “This is a function that converts User.t values into HTML.”

There is an equivalent mechanism of stringifiers and an @stringifier(type) annotation, which are used for conversions to strings:

@stringifier(User.t) function user_to_string(user) {
  user.username
}

Let’s add those two functions to our User module.

We will now work on the feature that allows users to enter new messages. To make it more user-friendly, we will add a real-time preview that displays the formatted message while the user is typing.

Let’s start by creating an interactive button that opens a modal window for entering a new message:

window_id = "msgbox"

function html() {
  match (User.get_logged_user()) {
  case {guest}: <></>
  case {user: _}:
    <a class="btn btn-primary pull-right" data-toggle=modal href="#{window_id}">
      <i class="icon-edit icon-white" />
      New message
    </a>
  }
}

The feature of adding new messages is only available to logged-in users who will see a Bootstrap button that opens the modal window identified by window_id [you learned how to deal with modal windows in Bootstrap Widgets: Modal Windows]. For unlogged guests, we just return an empty snippet.

Now we will work on the modal window itself:

private preview_content_id = "preview_content"
private input_box_id = "input_box"

function modal_window_html() {
    match (User.get_logged_user()) {
    case {guest}: <></>
    case ~{user}:
      win_body =
        <textarea id={input_box_id} onready={update_preview(user)} onkeyup=
        {update_preview(user)} placeholder="Compose a message"/>
        <div id=#preview_container>
          <p class=badge>Preview</p>
          <div id={preview_content_id} />
        </div>
      win_footer =
        <>
          Post button will appear here
        </>
      Modal.make(window_id, <>What's on your mind?</>, win_body, win_footer, Modal.
      default_options)
    }
  }

Again, we only create this for logged-in users. The modal body contains a <textarea> with an input_box_id for the user’s message and a <div> element with the preview_content_id preview. Besides that, the input text area contains a placeholder and event handlers for onready and onkeyup events, both invoking the update_preview function. This means this function will be called when the window is created (onready) and every time the user edits the message (onkeyup), and will update the live preview. In the modal footer, for the moment, we add some temporary text for the forthcoming Post button.

Here is a very simple event handler, the update_preview function:

private client function update_preview(user)(_) {
  msg = Dom.get_value(#{input_box_id})
     |> Msg.create(user, _)
  #{preview_content_id} = render(msg)
}

In the preceding code, first we get the content of the text box with Dom.get_value, and then we turn it into a message with the Msg.create function that we wrote previously. In the last line of the function, we update the preview container (accessing it by its ID: preview_content_id) with the rendered version of the message, obtained with our render function.

All that remains to be done is to hook up our message creation button. For the best user experience we will make it accessible all the time, and therefore place it in the top bar of the app. To do so, we add a call to MsgUI.html in the html function in src/view/topbar.opa:

function html() {
  <a class=brand href="/">
    Birdy
  </a> <+>
  MsgUI.html() <+>
  user_menu()
}

It’s better to place the modal window content outside of the top bar, to minimize the depth of the HTML structure. Therefore, we add some modal window HTML to the page_template function in src/view/page.opa:

function page_template(title, content) {
[...]
  <div id=#main>
    <span id=#notice class=container>{notice}</span>
    {content}
    {Signin.modal_window_html()}
    {Signup.modal_window_html()}
    {MsgUI.modal_window_html()}
  </div>
[...]
}

We’re done! If you compile and run your Birdy application, after signing in you should see the “New message” button in the top bar similar to Figure 9-1.

Figure 9-1. Birdy “New message” button is displayed in the top-bar

Clicking on the “New message” button results in a modal window similar to the one shown in Figure 9-2.

Figure 9-2. By clicking on the “New message” button a modal window is displayed

Let’s make the following two improvements to this page:

In addition to this, the character counter will switch to a warning mode when the message size limit is approached, and to an error mode once the limit has been exceeded. In this last case, the submission button will also be disabled.

We’ll start with a few constants for characters limits and UI element identifiers:

private MAX_MSG_LENGTH = 140
private MSG_WARN_LENGTH = 120

private chars_left_id = "chars_left"
private submit_btn_id = "submit_btn"

Getting the current message and closing the window are tasks that will now be performed in more than one place, so it is better to factor them out into dedicated functions:

private client function get_msg(user) {
  Dom.get_value(#{input_box_id})
  |> Msg.create(user, _)
}

private client function close() {
  Modal.hide(#{window_id})
}

Now let’s place the character counter and Post button HTML elements to the win_footer in the modal_window_html function. For a nicer display, we would like to place the character counter on the left side of the footer, and the Post button on the right side. We will use a parent <span> element with Bootstrap’s pull-left class to float the character counter to the left. We will use Bootstrap’s pull-right and btn btn-large btn-primary classes for a nice, highly visible Post button:

[...]
win_footer =
  <span class="char-wrap pull-left">
    <span id={chars_left_id} class="char"/>
    characters left
  </span>
  <button id={submit_btn_id} disabled=disabled class="pull-right btn btn-large btn-primary disabled" onclick={submit(user)}>
    Post
  </button>
[...]

Now we need the submit function that is invoked once the user decides to approve and post his message:

private function submit(user)(_) {
  get_msg(user) |> Msg.store;
  Dom.clear_value(#{input_box_id});
  close();
  Client.reload();
}

In the four lines of this function we respectively are doing the following, in the order shown:

The function that stores messages belongs to the Msg module in src/model/msg.opa. For the moment, we will write an empty temporary function that will be replaced with a real one when we discuss storage in Chapter 10.

function store(Msg.t msg) {
 void
}

The last remaining bit is to update the update_preview function:

private client function update_preview(user)(_) {
  msg = get_msg(user)
  #{preview_content_id} = render(msg)

   // show status
  msg_len = Msg.length(msg)
  #{chars_left_id} = MAX_MSG_LENGTH - msg_len
  remove = Dom.remove_class
  add = Dom.add_class
  remove(#{chars_left_id}, "char-error");
  remove(#{chars_left_id}, "char-warning");
  remove(#{submit_btn_id}, "disabled");
  Dom.set_enabled(#{submit_btn_id}, true);

  if (msg_len > MAX_MSG_LENGTH) {
    add(#{chars_left_id}, "char-error");
    add(#{submit_btn_id}, "disabled");
    Dom.set_enabled(#{submit_btn_id}, false);
  } else if (msg_len > MSG_WARN_LENGTH) {
    add(#{chars_left_id}, "char-warning");
  }
}

The first two lines in the preceding code just update the message preview using the get_msg function that we factorized. Then we check the message length, using the Msg.length function that we need to add to the message model:

function int length(Msg.t msg) {
  String.length(msg.content)
}

if $('foo').class == bar

if class_contains($('foo'), bar)"

We then remove all the warning/error styling from the element indicating the number of characters left and set the Post button to the enabled state. If the message is over its length limit, we add a char-error class to the counter element and disable the Post button. If the message is only over the warning threshold, we just add a char-warning to the counter element.

We are done! In Figure 9-3, the character count number is in orange to warn that only 5 characters are left. In Figure 9-4, the character count number is in red to indicate that we passed 140 characters limit. Both figures show the final version of the modal window we created in this chapter.

Figure 9-3. Birdy message preview with a warning

Figure 9-4. Birdy message preview with an error

In this chapter you learned how to:

In Chapter 10 we will talk about data storage and retrieval. We will extend Birdy with real storage of new messages and with pages containing all messages for a given user or topic.