To install Opa, get the package for your architecture from Opa’s website. At the time of this writing, installers are available for all major platforms: Mac OS X, Windows, Linux (generic, Ubuntu, and Fedora), and FreeBSD. These installers work with 64-bit architectures and, on some platforms, with 32-bit architectures.

On Mac OS X, you need to have Apple’s Xcode command-line tools installed as well.

As an option, you can compile Opa from source, but we strongly recommend using packages to begin with.

Once you have downloaded Opa, you can that check it’s correctly installed by opening a terminal and running the following:

Tokyo:~ henri$ opa --version Opa compiler (c) MLstate -- version 1.0.7 -- build 4040

This gives you the Opa version and build number. Opa then checks that its runtime dependencies are also installed in your system and should guide you to install them if necessary. You are all set!

Tokyo:~ henri$ npm install -g ursa formidable

In this section, you will write and then run your first program. You’ll then learn what the code actually means, how to build the application, and what happens behind the scenes.

Writing and Running the Code

You will write your Opa application code in a text editor. Any basic editor works, but we recommend using one of the editors for which Opa-specific plug-ins exist, including:

• Sublime Text2
• Emacs
• Vim
• Eclipse

Please check the online Opa documentation for up-to-date information on how to set up your preferred text editor.

Now open your editor and create a file that is named hello.opa and that contains the following content:

Server.start(Server.http,
  { title: "Hello, world",
    page: function() { <h1>Hello, world</h1> }
  }
)

This is a very simple application that just displays a static Hello, world message. You can run the application by typing the following command in a terminal:

Tokyo:~ henri$ opa hello.opa --
Http serving on http://localhost:8080

We will come back to this code later to discuss what actually happens here. For now, just point your browser to http://localhost:8080 and you should see something similar to Figure 1-1.

Figure 1-1. Our first Opa program in action

Tokyo:~ henri$ ./hello.js --port 2012

Server.start(Server.http,
  { title: "Hello, world",
    page: function() { <h1>Hello, world</h1> }
  }
)

Tokyo:~ henri$ opa file.opa

Tokyo:~ henri$ ls
_build          program.js      program.opa

Tokyo:~ henri$ ./program.js
Http serving on http://localhost:8080

Tokyo:~ henri$ opa file.opa
--> some node modules are missing, please run: npm install mongodb formidable nodemailer imap

In our short “Hello, World” application, all the code went into a single hello.opa file. For real programs, you’ll want to split the code among different files.

For instance, the popular MVC (Model-View-Controller) approach is to separate three things in an application: the model, which represents the data and its treatment; the view, which is the user interface of the data; and the controller, which synchronizes the model and the view.

It’s very easy to start a new application with Opa thanks to a scaffolding mechanism that automatically creates an empty MVC application for you. Just type:

Tokyo:~ henri$ opa create myapp
OpaCreate: Generating myapp/Makefile...
OpaCreate: Generating myapp/Makefile.common...
OpaCreate: Generating myapp/opa.conf...
OpaCreate: Generating myapp/resources/css/style.css...
OpaCreate: Generating myapp/src/controller/main.opa...
OpaCreate: Generating myapp/src/model/data.opa...
OpaCreate: Generating myapp/src/view/page.opa...

Now you can type:

$ cd myapp
$ make run

to create a myapp application.

You can compile it and run it using the following command:

Tokyo:~ henri$ cd myapp; make run

To see the source of the application, take a look at the generated files and open main.opa, data.opa, and page.opa with your favorite editor:

Tokyo:~ henri$ ls -R src
controller              model           view

src/controller:
main.opa

src/model:
data.opa

src/view:
page.opa

We will discuss the code in Chapter 2, but for now it’s important to know the following:

Now that you have written your first Opa application, you are ready to proceed with the main goal of this first part of the book: creating a simple wiki app. Our high-level specification for the app is as follows:

The application is not overly complicated, but it still has a number of interesting features that will give you a great opportunity to learn how to tackle different issues in Opa. In the following chapters, you will learn how to:

But before you do that, you need to learn a bit more about Opa, which you will do in Chapter 2.

In this chapter, you got a feel for what Opa is. You learned how to:

As with most programming languages, Opa supports strings, integers, and floats, but Opa also supports native web values such as HTML and CSS elements. As you can see, comments in Opa consist of text preceded by double slashes, //:

"hi" // a string
12 // an integer
3.14159 // a float
<p>Paragraph</p> // an HTML fragment
#id // a DOM identifier
css {color: black} // a CSS property

HTML values are fragments of HTML5. Each fragment has an opening tag such as <p> and a closing tag such as </p>. The <p> tag is the tag that defines a paragraph. We will provide a more complete list of tags shortly, but for now here are the main ones (see Table 2-1):

You can embed HTML fragments, as shown here:

<div>
  Content <span>button</span>
  <ul>
    <li>First item</li>
    <li>Second item</li>
  </ul>
</div>

Tags can have attributes. For instance, the a tag has the href attribute, which specifies the HTML reference it points to. So to insert a link to http://google.com, you can write:

<a href="http://google.com">Google</a>

HTML fragments, when grouped together, create a document. We will discuss all the relevant properties of a document in Chapter 5. For now, it’s sufficient to know that tags can have a unique ID using the id attribute.

For instance, <div id="iamunique">...</div> creates an iamunique ID that can be accessed by the DOM identifier #iamunique.

All Opa values can be named, to be reused later in your program. Here is an example:

customer = "John Doe"
price = 12.99
tax = price * 0.16
total = price + tax

Note that you can play with these basic values by inserting them into the former Hello, World application. For instance, try:

Server.start(Server.http,
  { title: "Hello, world",
    page: function() {
      customer = "John Doe";
      price = 12.99;
      tax = price * 0.16;
      total = price + tax;
      <p>Customer {customer} has to pay {total}</p>
    }
  }
)

Here are a few things to note regarding the preceding code:

Thus far, you have learned how to build static content. Each time you run your application by pointing your browser to http://localhost:8080, you get the same content.

The Web was born this way, although originally the mechanism was different, as developers used to write static HTML content within files and used a static server program, such as Apache, to serve the files to users’ browsers. The pages would use the HTML <a> tag to create links between pages or between different sites.

But we are here to build applications. An application consists primarily of web values that can do the following:

The most basic user action is the mouse click. Modern applications do not use the link tag to react to users’ mouse clicks. So we will use an HTML attribute, onclick, which is present in many tags.

Let’s create a small application that displays “Thank you” once the user clicks on “Click me”:

Server.start(Server.http,
  { title: "Hello, world",
    page: function() {
      <div onclick={function(_) { #thankyou = "Thank you" }}>Click me</div>
      <div id="thankyou"/>
    }
  }
)

Run the application now! You should see something similar to Figure 2-1. You can restart your application by refreshing the page in your browser.

Figure 2-1. The same dynamic application as in Figure 1-1 with a bit of design

The most important new line in this program is:

<div onclick={function(_) { #thankyou = "Thank you" }}>Click me</div>

which combines two things:

We won’t explain every bit of code in that line right now (you will know everything by the end of this chapter), but it is important to note the following:

To continue our quest, you need to understand two powerful programming mechanisms:

It turns out that you are already using both! The record lies behind the following:

{ title: ..., page: ... }

The function was already used twice:

One of the main features in terms of Opa structuring values is records. As you will see throughout this book, Opa records are extremely powerful and you will use them a lot. Their nickname is “Power Rows.”

Records are a set of values, each defined by its field name. Values for each field can be of any type, including records or even more complex types:

// this is a record with 3 fields
{ first_name: "John", last_name: "Doe", age: 18 }

// this is a record with 2 fields, one of them being a record itself
{ product: "book", price: { base: 29.99, tax: 4.80 } }

Naturally, it’s useful to name values so that you can construct more complex ones step by step:

level1_pricing = { base: 29.99, tax: 4.80 }
book = { product: "book", price: level1_pricing }

As we said earlier, all programs, including the very first one you wrote, use records:

  { title: "Hello, world",
    page: function() { <h1>Hello, world</h1> }
  }

The code includes a record that has two fields: title, which is a string, and page, which is another value that we will discuss next.

Records in Opa can be extended, that is, you can add new fields later in your program:

level1_pricing = { level1_pricing with total: 29.99 + 4.80}

Now that you know about basic values and records, it’s time to learn more about types. You should be familiar with types. You have seen strings and integers, and as a developer, you know they represent different types of values. So does Opa!

"Hey" // this has type string
10 // this has type int

You can enforce types by writing them if you want, but in most cases, Opa infers them for you and you can safely omit them:

string text = "Hey"

Opa uses the type information to help you. For instance, Opa won’t let you mix different types as doing so is either a bug or a bad coding practice. Try writing:

1 + "Hello"

and see how Opa reacts.

Often, the mistake is not straightforward and involves two different parts of the code. Opa handles this particularly well. If you write:

a = 1;
b = "Hello";
a + b

Opa will tell you what the error is and why it occurred. Try it!

You will get the following error message:

Error: File "typeerror.opa", line 3, characters 1-5, (3:1-3:5 | 21-25)
Type Conflict
  (1:5-1:5)           int
  (2:5-2:11)          string

  The types of the first argument and the second argument
    of function + of stdlib.core should be the same

The preceding error message says that:

To make it easier to read type error messages, you can name types:

type mytype = string
mytype text = "Hey"

This becomes useful with records. Each record (as with all other values in Opa) has its corresponding type, even though you will not have to spell it out. For instance:

{ title: "The Firm",
  author: { first_name: "John", last_name: "Grisham" } }

has type:

type book = { string title,
              {string first_name, string last_name} author }

which you should read as: “Type book is a record with two fields: title and author. Field title has type string, whereas author is a field whose type is a record with two string fields: first_name and last_name.”

After such type declaration, you could as well write:

book some_book = { title: "The Firm",
                   author: {first_name: "John", last_name: "Grisham"} }

In the preceding code, you gave a name (some_book) and an explicit type (book) to the value shown previously.

Sometimes the expressions describing record fields can get long and complex:

author = { first_name: long_expression_to_compute_first_name,
           last_name: long_expression_to_compute_last_name}

In this case, to improve readability we will often compute and bind them first:

author =
  first_name = long_expression_to_compute_first_name
  last_name = long_expression_to_compute_last_name
  {first_name: first_name, last_name: last_name}

For this frequent case where fields are initialized from variables with the same name, Opa provides an abbreviation and allows you to replace the last line in the preceding code with:

  {~first_name, ~last_name}

Here {~field, ...} stands for {field: field, ...}. If all fields are constructed in this way, you can even put the tilde in front of the record and write:

  ~{first_name, last_name}

You will often construct one record from another, as in:

grisham = {first_name: "John", last_name: "Grisham"}
steinbeck = {first_name: grisham.first_name, last_name: "Steinbeck"}

Opa facilitates this frequent-use case with the following construction:

{record with field1: value1, ... fieldN: valueN}

The value of this expression is the same as that of record except for fields field1 to fieldN, which are given values value1 to valueN. For instance, the steinbeck value in the previous code can be replaced with:

steinbeck = {grisham with last_name: "Steinbeck"}

Records are ever-present in Opa. Their power comes from the fact that all record manipulations are typechecked:

This power does not cost you anything, as you can just use records as you would in a dynamic language without ever explicitly declaring their types.

One last aspect of the mighty record is variants.

Variants are the way to properly represent multiple-choice lists. Imagine that you want to define a currency type for an online store that handles payments in US dollars (USD), Canadian dollars (CAN), and British pounds (GBP). You could use the string type to define that value. But what if you write the following at some point?:

price1 = { amount: 4.99, currency: "USF" }

The typo will remain unnoticed, the compiler won’t complain, and the related bugs will have to be hunted down during the app testing. As a result, depending on the code structure, the item might not be billed.

Instead, you can write:

type currency = { USD } or { CAN } or { GBP }
// here price is a previously defined book value
price = { amount: 29.99, currency: { USD }}

The or keyword states that the type currency will be one of the three options: USD, CAN, or GBP. Opa provides very useful typechecking for variants. For instance, it checks that values are only allowed variants or that you always take all variants into account. You should use them instead of strings as much as possible.

We will discuss variants in more detail in Chapter 7.

Before we move on to the main example of this part of the book, let’s take a look at some building blocks of the language that you will need to understand.

Structuring programs is very important. You never want to write your program as a single piece of code; rather, you want to break it down into blocks. The two main block levels are:

Using functions, you make your program more readable and your code reusable.

Functions are written and called very easily:

// the following function computes the tax of a given price
function compute_tax(price) {
  price * 0.16;
}

// we now can call (or invoke) the compute_tax function as much as we want
tax1 = compute_tax(4.99);
tax2 = compute_tax(29.99);

Here we have the function keyword, then the name of the function, compute_tax, and a list of its arguments in between parentheses. In this case, there’s only one argument: price, followed by the function body inside curly braces. Opa does not have an explicit return keyword and instead adopts the convention that the last expression in the function is its return value. Here, it means the function returns the value of price times 0.16.

The use of functions in this example means that when the tax level changes, you only have to modify one line of your program, instead of chasing down all the places where the tax is computed in your application. For this reason, you should always use functions whenever you can, and never copy and paste code. Each time you are tempted to copy and paste your code, you should use a function instead.

The coding style that Opa promotes is called the functional programming style. Among other things, this means that functions play a central role and are very powerful. The functional programming style is often described as elegant, and we will show you why. But for now, it helps to know that the main difference between functional programming and classic programming is that in the former, values are not mutable by default.

For instance, in Opa, the main definition of values such as the following is the binding of a value:

name = expression

However, this does not create a variable in the classic programming style. The previous expression just means we give name to the expression and can subsequently use name to refer to the value denoted by expression.

The main reason for this is that immutable code is easier to reason about. In the absence of variables, the result of a function depends only on its arguments. Contrast this with a function whose behavior depends on a bunch of global variables. This is one of the main reasons why in the excellent book Effective Java (Addison-Wesley), where mutability is the norm, the author advises that you use immutability whenever possible, explaining:

Our argument for immutability also concerns scaling web applications and services. The architecture prevalent today for scaling up is to use stateless servers that can be multiplied without limits. Should a server fail, a new one pops in, and traffic is directed to random servers. But this implies that no application has unsaved data or state. The problem here is that mutable variables often contain such information, and this information will not be synchronized with these other servers unless the synchronization has been done manually (which is a painful process). Therefore, not using state (and variables) is a good programming practice, today more than ever.

x = 10
f = function() { return x + 1 }
x = 20
f()

x = 10
f = function() { x + 1 }
x = 20
f()

Bindings and functions are deeply linked. Let’s play with them a bit by writing a function that computes the Euclidean distance between two points:

function distance(x1, y1, x2, y2) {
  dx = x1 - x2
  dy = y1 - y2
  Math.sqrt_f(dx*dx + dy*dy)
}

In the preceding code, the function distance first binds the value x1-x2 to dx, and similarly binds y1-y2 for dy, and then uses dx and dy in the final expression. Math.sqrt_f is a function from the Math module (more about modules later) of the standard library for computing the square root of a given floating-point number.

In fact, the bindings inside functions can include local functions, so the previous could be rewritten as follows, introducing the intermediate sqr function:

function distance(x1, y1, x2, y2) {
  dx = x1 - x2
  dy = y1 - y2
  function sqr(x) { x*x }
  Math.sqrt_f(sqr(dx) + sqr(dy))
}

Finally, functions can be anonymous, in which case they do not have a name but they can be used inside any expression. The anonymous variant of the incr function in the preceding code would be:

function(x) { x + 1 }

This variant can be stored in a named value:

incr = function(x) { x + 1 }

Anonymous functions are particularly useful for passing arguments to other functions; for instance, to specify how the app should react to a user’s actions.

As you can see, functional programming allows much better control of programming scope. In pure JavaScript, you would write:

var foo;
if (x==10) { foo = 20; } else { foo = 30; }

This would introduce a variable, and then set its value, even if foo is unmodified in the rest of the program. In Opa, you simply write:

foo = if (x==10) { 20; } else { 30; }

The preceding code will have the guarantee that foo is not further modified.

At the beginning of this chapter, we played with types. Opa is indeed a statically typed language. This means that every value has a type assigned to it, and this assignment takes place at compilation time. Being typed is orthogonal to being a functional language. This is important, as the compiler uses this information to detect and report all kinds of flaws in the program.

So why were there no types in the code snippets shown in the preceding section? In Opa, explicitly writing types is often not required as the types are inferred in the absence of explicit type annotations. This means you could write the distance function with explicit types as follows (the additions are in bold):

function float distance(float x1, float y1, float x2, float y2) {
  float dx = x1 - x2
  float dy = y1 - y2
  Math.sqrt_f(dx*dx + dy*dy)
}

Arithmetic operators work both for int and for float types, so the only reason all values are given the float type is because of the Math.sqrt_f function (its int counter-part is called Math.sqrt_i).

The type inference that the compiler performs may not seem too impressive on this trivial example, but in later chapters, when we deal with more complex types, its benefits will become more pronounced. The type checker algorithm that performs type inference and verification is a very complex and sophisticated algorithm—especially the one in Opa, which required tremendous effort on the part of Opa developers to specify and implement.

In this chapter, we learned the fundamental concepts of Opa, in particular:

In the next chapter we will talk about servers: how to handle resources and different URLs of an application.

A resource is anything that can be sent from the server to the client. Figure 3-1 presents different types of web resources, including:

Figure 3-1. Different types of web resources

Opa contains directives to embed resources. The simplest one is @static_resource:

resource logo = @static_resource("img/logo.png")

The string given as the argument to this directive is a path to the resource, which can be relative to the directory from which the project will be compiled.

This directive acts as a function; that is, you can bind its result to a variable (here, logo) and use it in your program. The type of this variable is resource, which is an object that can be sent from the server in response to the client’s request.

Sometimes you may have several resources you want to use: for example, a directory full of images. Instead of including each image one by one, you can use @static_resource_directory:

resources = @static_resource_directory("resources")

This line of code will include all resources based on all files from a given directory (here, resources) and its subdirectories.

What is the type of this variable? Such an embedded directory is represented as a mapping from filenames (string) to resources (resource), and hence has the type map(string, resource). We will talk more about maps in Maps (Dictionaries).

Embedding resources is the first step. The next step is to instruct the web server to serve them for certain requests. Remember the Server.start function and how you used it in your first Opa app in Writing and Running the Code? The second argument defines how different requests should be handled. To serve resources from the resources directory you first need to embed them:

resources = @static_resource_directory("resources")

Now you need to create a server for them:

Server.start(Server.http, {resources: resources})

Note that before you used a {title: ..., page: ...} variant for this second argument to create a single-page app, that is, to direct all client requests to page. This new variant, {resources: ...}, creates a server that just responds to requests for resources.

Imagine that the local resources directory has the following structure:

+- resources
  +- imgs
  |  +- opa-logo.png
  +- css
  |  +- style.css

In this case, running the preceding application and directing the browser to http://localhost:8080/resources/css/style.css would give you the stylesheet. What if you tried some other URL? This would result in the infamous "Error 404: Not Found" error.

OK, so what if you wanted to extend your “Hello web” application slightly and use some resources in it? You could use two servers:

 // serve resources
Server.start(Server.http, {resources: @static_resource_directory("resources")})

 // serve the main page
function page() {
  <img src="resources/img/logo.png" alt="Opa"/>
  <hr/>
  <h1>This is a demo of a very simple Opa app.</h1>
}
Server.start(Server.http, { title: "Hello web", page: page })

Note how this code combined the directive to embed the resources and the server declaration in one; this is entirely permissible.

What happens if you declare more than one server? For every request, the servers will be tried one by one. If a request can be handled by the resources server, it handles it. Otherwise, the request will be handed over to the second server, which in this case can handle each and every request.

Another way to achieve the same effect is to simply use a list of servers in the second argument of Server.start. In this case, the preceding program could be written more concisely as:

function page() {
  <img src="resources/img/logo.png" alt="Opa"/>
  <hr/>
  <h1>This is a demo of a very simple Opa app.</h1>
}
Server.start(Server.http,
  [ { resources: @static_resource_directory("resources") },
        { register: {css:["/resources/css/style.css"]} },
    { title: "Database Demo", page: page }
  ]
)

Now compile your application:

Demo:~ ida$ opa simple_demo.opa

And run it:

Demo:~ ida$ ./simple_demo.js
Http serving on http://Demo.local:8080

When you open it in the browser, you will see input similar to that shown in Figure 3-2, which has a little CSS file included.

Figure 3-2. Our first program with resources

In addition to embedding static, ready-to-use resources, it is also possible to create them on the fly. You will rarely do this for such things as images and stylesheets, but you will often do this to create HTML pages dynamically; for example, pages based on the state of the database or on user input.

Opa offers many functions for this; the ones we will typically use are:

xhtml Resource.page(string title, xhtml body)
xhtml Resource.styled_page(string title, list(string) stylesheets, xhtml body)

Resource.page takes two parameters, title and content, and constructs a page resource with this data. Resource.styled_page is similar, but it takes one extra argument: a list of URLs of CSS stylesheets to be used to style the application. You will see an example of how to use it in the following section.

All the applications you have developed so far have consisted of just a single page, but in practice most bigger sites will have multiple pages. The standard way to handle this is with Uniform Resource Locators, more commonly known as URLs.

scheme://domain:port/path?query_string#fragment_id

http://example.com/over/there/index.html?type=animal;name=ferret#nose

With what you’ve learned so far, it is very easy to build sites consisting of multiple pages. You can do this via yet another variant of the argument accepted in the Server.start function: {dispatch: dispatch_fun}, where dispatch_fun is a function that takes a structured URL as an argument and produces a resource to deliver to the user. This process is often referred to as URL dispatching.

You learned about resources in Web Resources and about how to create them dynamically in Constructing (Dynamic) Resources. But what is a structured URL? It is a structural representation of a URL with all its components separated. Since your application will work within a single domain, you are working with relative URLs here, or URLs relative to the domain of the application, without the scheme and domain parts.

Here is the definition of the type representing such URLs in Opa:

type Uri.relative =
  { list(string) path,
    list((string, string)) query,
    option(string) fragment,
    bool is_directory,
    bool is_from_root }

The preceding code consists of the following:

For example, consider the following address within a website:

/over/there/index.html?type=animal;name=ferret#nose

The structured representation of this address in Opa will be:

{ path: ["over", "there", "index.html"],
  query: [("type", "animal"), ("name", "ferret")],
  fragment: some("nose"),
  is_from_root: true,
  is_directory: false }

Due to HTTP, the fragment identifier is not transmitted from the client to the server via a normal web request.

To practice URL dispatching in Opa, let’s write a simple program that will construct a page consisting of the relative address requested by the user. If that address refers to a path starting with bold, the remaining part of the address will be printed in bold. If it starts with italic, it will be shown in italic.

Hopefully, the following short program should not be too difficult to understand now:

function start(url) {
  match (url) {
    case {path: ["bold" | text] ... }:
      Resource.page("Bold", <b>{text}</b>)
    case {path: ["italic" | text] ...}:
      Resource.page("Italic", <i>{text}</i>)
    case {~path ...}:
      Resource.page("Regular", <>{path}</>)
  }
}

Server.start(Server.http, {dispatch: start})

In this chapter you learned how to deal with URLs and resources in Opa. Specifically, you learned:

In the next chapter you will learn about data storage, or how to permanently store some application data in a database.

To get started, let’s look at a very simple database declaration, containing only a single int, a counter of sorts:

database db {
  int /counter = 0;
}

As you can see, Opa features a database block with a given name and a list of declarations of database values enclosed in curly braces.

Every declaration consists of a type (here, int), a path (here, /counter), and optionally, a default value (here, 0).

The default value is used when you attempt to read a path’s value that does not exist. In cases where the path was never written or was removed, the default value is returned.

Locations in Opa’s database are called paths, as they bear a strong similarity to filesystem paths. Every value is available at a path consisting of the database name, followed by the path of the value, in our case /db/counter. You can read a given value by simply writing its path, as in:

counter_value = /db/counter

Similarly, you can write the value using path <- value notation:

/db/counter <- 42;

A few extra operators are also available for manipulating int paths:

/db/counter++;
/db/counter += 10;
/db/counter -= 3;

The last element in CRUD is Delete, which is also very easy with Opa. To delete the counter, you write:

Db.remove(@/db/counter)

Of course, this is just the beginning of the “database story” in Opa. You will learn more as we go along.

To illustrate the usage of the database, let’s extend our simple Opa program from Writing and Running the Code and add a database to it. We’ll also use a function that involves the onclick attribute from Dynamic Content to count clicks.

database int /counter = 0;
function action(_) {
    /counter++;
    #msg = <div>Thank you, user number {/counter}!</div>
}
function page() {
    <h1 id="msg">Hello</h1>
    <a onclick={action}>Click me</a>
}
Server.start(Server.http,
  [ { resources: @static_resource_directory("resources") },
    { register: {css:["/resources/css/style.css"]} },
    { title: "Database Demo", page: page }
  ]
)

Compile and run this application in your terminal:

Demo:~ ida$ opa opa_database_demo.opa --

You will get a result similar to the screenshot shown in Figure 4-1.

Figure 4-1. Opa database demo app

You will learn more about databases in the following chapters. But first, let’s take a look at maps.

The data model for the wiki app you will build is quite simple: you want a collection of topics. A topic is represented by a string and it should be associated with content. You will use the Markdown markup format for the content. We will explain how to handle this format in Markdown, but for now, all you need to know is that Markdown is internally represented as a string.

For your data model you need a mapping from strings (topics) to strings (Markdown content). This is what maps are for.

Map is an abstract data type that associates keys with values. It is often called a dictionary or an associative array, and is, in many programming languages, implemented using hash tables.

All you need to know for now is that in Opa, the type of the dictionary is map(key, val), where key is the type of keys and val is the type of values. For instance, map(int, string) is a type of dictionary mapping int keys to string values.

In memory, it is simple to play with maps. The only thing to remember is that they are used in a functional way [for a refresher, refer to Functional Programming].

You can, for example, store values in successive versions of maps and retrieve them like so:

m0 = Map.empty
m1 = Map.add(1, "Paris", m0)
m2 = Map.add(2, "London", m1)

// result is an option
result = Map.get(2, m2)
value = Option.default("Not found", result)

Note that although m0, m1, and m2 are separate values, they point to one another and the final data structure is stored efficiently in memory.

Storing maps in databases is even easier than manipulating them in memory, thanks to the DbGen automation layer that Opa provides. For the wiki, you will want a database mapping from strings to strings, which you can obtain with the following declaration:

database wiki {
  map(string, string) /page
}

The read/write notation that we discussed earlier has a variation that allows you to easily index a given map element by providing its key in square brackets. So read and write operations on maps become:

Paris_content = /wiki/page["Paris"]   // read
/wiki/page["Paris"] <- Paris_content  // write

At this point, you know enough to write two useful functions for data manipulation in the wiki; save_data(topic, source) saves source as new content for topic:

function save_data(topic, source) {
  /wiki/page[topic] <- source;
}

And load_data(topic) retrieves content for topic:

function load_data(topic) {
  /wiki/page[topic];
}

What will happen when you try to load data for a nonexisting page? Remember our discussion about default values in CRUD (Create, Read, Update, and Delete)? This notion extends to maps as well: if you ask for nonexisting data, you will get the default value, which is an empty string.

It is possible to change this default value, although the syntax will be slightly different, as you would be providing a default for an individual element in a map, not the map itself. You will need to add a new line in your database definition:

/page[_] = "This page is empty. Double-click to edit."

The final database declaration for the wiki app looks like this:

database wiki {
  map(string, string) /page
  /page[_] = "This page is empty. Double-click to edit."
}

In this chapter you learned the basics of handling data storage in Opa. You should now know how to:

In the following chapter we will look in more detail at the topic of utilizing HTML and CSS to build user interfaces (UIs) in Opa.

For presentation, Opa uses the modern web standards HTML5 and CSS3 [we will discuss these in more detail in Adding Style (CSS)]. You already saw a glimpse of how Opa deals with HTML in Writing and Running the Code and we will expand on that here.

function sample_page() {
  <header>
    <h3>HTML in Opa</h3>
  </header>
  <article>
    <div class="container">
      <p>Learning by examples.</p>
    </div>
  </article>
}

function sample_page() {
  <header>
    <h3>HTML in Opa</>
  </>
  <article>
    <div class=container>
     <p>Learning by examples.</>
    </>
  </>
}

x + " + " + y + " = " + (x+y);

"{x} + {y} = {x+y}";

function gen_page(header, class, content) {
  <header>
    <h3>{header}</h3>
  </header>
  <article>
    <div class={class}>
      <p>{content}</p>
    </div>
  </article>
}

function xhtml gen_page(xhtml header, string class, xhtml content) { ... }

function sample_page() {
  gen_page(<>HTML in Opa</>, "container", <>Learning by examples.</>)
}

function page() {
  <p onclick={clicked}>Click me!</p>
}

function void clicked(Dom.event event) {
  ...
}

function clicked(_event) { ... }

function clicked(_) { ... }

function page() {
  <p onclick={function(_) { ... }}>Click me!</>
}

#id = content

#id += content
#id =+ content

function page() {
  <h1>Guess what is the number between 1 and 10 I'm thinking of?</h1>
  <div id=#response onclick={show_number}>Click to find out!</div>
}

function show_number(_) {
  #response = <>I was thinking of {1 + Random.int(10)}</>
}

function show_number(_) {
  #response = <>I was thinking of {1 + Random.int(10)}</>
}

function page() {
  <h1>Guess what is the number between 1 and 10 I'm thinking of?</h1>
  <div id=#response onclick={show_number}>Click to find out!</div>
}

Server.start(Server.http, { title: "Guess", ~page })

<h1>Guess what is the number I'm thinking of</>
<input id=#guess/>
<span onclick={show}>Check</>
<div id=#message/>

secret = 1 + Random.int(10);

message =
  if (guess==secret) { <span class="success">Congrats! < /span> }
  else if (guess<secret) { <>More than this</> }
  else { <>Less than this</> };

function show(secret, _) {
  ...
}
function page() {
  ...
  <span onclick={show(secret, _)}>Check</>
  ...
}

function show(secret, _) {
  guess = Dom.get_value(#guess);
  message = ...
  #message = message;
}

guess = String.to_int(Dom.get_value(#guess));

function show_number(_) {
  #response = <>I was thinking of {1 + Random.int(10)}</>
}

function page() {
  <h1>Guess what is the number between 1 and 10 I'm thinking of?</h1>
  <div id=#response onclick={show_number}>Click to find out!</div>
}

Server.start(Server.http, { title: "Guess", ~page })

Now we are ready to write the user interface part of the wiki app. In this section you will write a display function that takes a single argument, topic, and constructs a page for it. We will assume that you have at your disposal the following functions for data storage, which we discussed in Chapter 4:

The main idea is that the page can have two modes:

In this example you will have elements for both modes always present on the page, but only one mode will be visible at a time and the other one will be hidden. Dynamically changing the content would also work, but since you did that already in Example: A Guessing Game, let’s try this approach now.

function display(topic) {
  content = render(load_data(topic));
  xhtml =
    <header>
      <h3>OpaWiki</h3>
    </header>
    <article>
      <h1>About {topic}</h1>
      <div id=show_container>
        <small><strong>Tip:</strong> Double-click on the content to start
editing it.</small>
        <section id=content_show ondblclick={function(_) { edit(topic) }}>
{content}</section>
      </div>
      <div id=edit_container hidden>
        <small><strong>Tip:</strong> Click outside of the content box to save changes.</small>
        <textarea id=content_edit rows=30 onblur={function(_) { save(topic) }}/>
      </div>
    </article>;
  Resource.page("About {topic}", xhtml);
}

import stdlib.tools.markdown

function xhtml xhtml_of_string(Markdown.options options, string source)

function render(markdown) {
  Markdown.xhtml_of_string(Markdown.default_options, markdown);
}

function edit(topic) {
  Dom.set_value(#content_edit, load_data(topic));
  Dom.hide(#show_container);
  Dom.show(#edit_container);
  Dom.give_focus(#content_edit);
}

function save(topic) {
  content = Dom.get_value(#content_edit);
  save_data(topic, content);
  #content_show = render(content);
  Dom.hide(#edit_container);
  Dom.show(#show_container);
}

A close companion of HTML is CSS, which stands for Cascading Style Sheets. Whereas HTML is used to describe the content and structure of web pages, CSS takes care of presentation semantics (i.e., appearance and formatting). Knowledge of CSS will help you create more beautiful pages, although you will learn how to style pages without writing CSS yourself in Bootstrap: Nice, Out-of-the-Box Styling. Still, a basic working knowledge of CSS comes in handy in the web world, so we suggest that you learn the basics of CSS.

In Opa, you can work with CSS in three ways:

In addition to discussing these three methods of working with CSS, in this section we will explain how to add some style to the wiki.

function page() {
  <p style="color: white; background: blue; padding: 10px;">Click me</>
}

function page() {
  style = css { color: white; background: blue; padding: 10px;}
  <p style={style}>Click me</>
}

function page() {
  <p style={css { color: yellow; background: blue; padding: 10px;}}>Click me</>
}

function paragraph(style, content) {
  <p style={style}>{content}</>
}

function xhtml paragraph(css_properties style, xhtml content)

function xhtml block(Css.size width, Css.size height, xhtml content) {
  style = css { width: {width}; height: {height} }
  <div style={style}>{content}</>
}

Server.start(Server.http,
  [ {resources: @static_resource_directory("resources")},
    {register: {css:["/resources/css/style.css"]} },
    ...
  ]
)

function page_with_style(body) {
  Resource.styled_page("This is a page with style",
  ["resources/custom_style.css"], body)
}

Wiki with Style

For the wiki application, you just need to add a simple CSS file, resources/style.css, to add a bit of presentation information and, more importantly, hide the editing mode container initially:

include:code/wiki/resources/style.css[]

Now all you are missing is the following server declaration:

Server.start(Server.http,
  [ {resources: @static_include_directory("resources")},
    {register: [{doctype: {html5}}, {css: ["/resources/style.css"]}]},
    {dispatch: start}
  ]
);

At this point, you should have a complete and ready-to-run wiki. You compile it with:

opa wiki.opa

And you run it with:

thistle $ ./wiki.js
Http serving on http://thistle:8080

Now the server is running. Pointing your browser to http://localhost:8080 should give a result similar to the screenshots shown in Figure 5-1, which show the app in both display mode and editing mode.

Figure 5-1. Our wiki application in display (left) and editing (right) modes

Typically, web applications are designed by professional web designers. However, in very basic projects, or at the early stages of major projects, a professional web designer may not be readily available. In such cases, you can use a frontend framework such as Bootstrap for the design task.

The Opa authors have high regard for this project, and therefore made sure that using Bootstrap in Opa is as easy as it gets. To use Bootstrap in your Opa project, just type a single line:

import stdlib.themes.bootstrap

import stdlib.themes.bootstrap.v2.1.0

Now you can start using Bootstrap-compatible HTML markup and enjoy good-looking pages without any hassle!

In the following code, we will illustrate the power of Bootstrap on the wiki application. All you need to do is replace the xhtml in the display function with the following one, which is using Bootstrap conventions:

  <div class="navbar navbar-fixed-top">
    <div class=navbar-inner>
      <div class=container>
        <a class=brand href="#">
          Opa Wiki
        </a>
      </div>
    </div>
  </div>
  <div class=container>
    <h1>About {topic}</>
    <div id=show_container>
      <span class="badge badge-info">Tip</span>
      <small>
        Double-click on the content to start editing it.
      </small>
      <div class="well well-small" id=content_show ondblclick={function(_) { edit(topic) }}>
        {content}
      </div>
    </div>
    <div id=edit_container hidden>
      <span class="badge badge-info">Tip</span>
      <small>
        Click outside of the content box to confirm the changes.
      </small>
      <textarea id=content_edit rows=30 onblur={function(_) { save(topic) }} />
    </div>
  </div>

Once you do that, you no longer need the full CSS we introduced before, and you can replace it with the following:

include:code/wiki/resources/style_additional.css[]

This code only hides the editing container, adds a little extra space between elements, and makes the editing text area the full width of your screen. This uses much simpler CSS yet produces a much more pleasant result, as you can see in Figure 5-2.

Bootstrap offers even more than this screenshot can capture, including responsive design; that is, web pages that display nicely on most devices and screen sizes. As mobile browsers become increasingly important, you will want to build responsive applications!

Figure 5-2. Our wiki application with Bootstrap styling in editing (left) and display (right) modes

We have been lucky to have a UX and UI designer in-house at MLstate. This section is a Q&A with Ida Swarczewskaja, who gives us her best tips on how to work with design and designers when coding with Opa.

In this chapter you learned how to build user interfaces; in particular, how to:

At this point, you have completed your simple wiki application and learned a lot along the way.

In Part II of this book you will develop a micro-blogging application, similar to Twitter, though without all the bells and whistles. This will be a great opportunity to learn more advanced topics. Ready? Let’s get started!

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.

You learned about primitive values (int, float, string) in Primitive Values and about records in Records. Now it is time to extend your type arsenal.

type bool = {false} or {true}

type bool = {void false} or {void true}

type Date.weekday = {monday} or {tuesday} or {wednesday} or {thursday}
  or {friday} or {saturday} or {sunday}

type User.logged = {guest} or {User.t user}

function int int_of_bool(bool b) {
  match (b) {
  case {true}: 1
  case {false}: 0
  }
}

function string greet(User.logged u) {
  name =
    match (u) {
    case {guest}: "guest"
    case {user: user}: User.get_name(user)
    }
  "Hello, {name}"
}

function string greet(User.logged u) {
  "Hello, " + match (u) {
              case {guest}: "guest"
              case {user: user}: User.get_name(user)
              }
}

type nullable_int = {null} or {int value}

type option('a) = {none} or {'a some}

function bool is_some(option('a) v) {
  match (v) {
  case {some: _}: true
  default: false
  }
}

b1 = is_some({some: 5})       // b1 == true
b2 = is_some({some: "Text"})  // b2 == true
b3 = is_some({none})          // b3 == false

Option.default(default_value, option_value)

option(void) v = none
match (v) {
        case {none}: 1;
}

Warning pattern
File "match1.opa", line 2, characters 1-30, (2:1-4:1 | 23-52)
Incomplete pattern matching: case {some} is missing
Error: Fatal warning: 'pattern'

type outcome('ok, 'ko)= { 'ok success } or { 'ko failure }

type list('a) = {nil} or {'a hd, list('a) tl}

l1 = {hd: 1, tl: {hd: 2, tl: {hd: 7, tl: nil}}}

l2 = [1, 2, 7]

l3 = [0 | l2]  // == [0, 1, 2, 7]

l4 = [0, 3 | l2] // == [0, 3, 1, 2, 7]

type bin_tree('a) = {leaf} or {'a value, tree('a) left, tree('b) right}

To pattern-match on recursive types, such as the list introduced in the preceding section, we just follow the same rules we used for records:

match (l) {
case {nil}: ...
case ~{hd, tl}: ...
}

Here, Opa also offers syntactic sugar, allowing us to replace the preceding code with:

match (l) {
case []: ...
case [hd | tl]: ...
}

The interesting point here is that the tl binding in the second case will be of the same type as the whole list l. To make this more concrete, let’s try to write a function that computes the length of a list:

function int length(list('a) l) {
  match (l) {
  case []: 0
  case [hd | tl]: ?
  }

The case when the list is empty is easy, as we just return 0 (since that is the length of an empty list). However, how do we handle the second case? What is the length of a list with an element hd followed by a list tl? Well, it is the length of tl plus one (for hd). This is exactly what we can write in Opa, too (we replace hd with an underscore, as we do not need to inspect the head of the list and hence do not need this binding):

function int length(list('a) l) {
  match (l) {
  case []: 0
  case [_ | tl]: 1 + length(tl)
  }

Note how the length function is called in the definition of the length function. This is what makes it a recursive function. While writing such functions, we need to be careful, though. What would happen if we just wrote the following?:

function f() {
  f()
}

Invocation of such a function would cause an infinite loop, just as if we wrote while (true) { } in a language like Java.

One final remark: all top-level functions (i.e., functions that are defined in a file or in a module, but not local functions that are defined within other functions) can use recursion directly. However, if you want to use recursion in a local function, you will need to precede function with the recursive keyword.

For instance, we can write the following sample functions:

function f(x) {
  if (x==1) { 1; }
  else g(x)
}
function g(x) {
  f(x-1)
}

function f(x) {
  recursive function aux(x) {
    if (x==1) { 1; }
    else aux(x-1)
  }
  aux(x)
}

If you’re familiar with some programming languages, you may have been wondering why we have not talked about loops yet. The reason is simple: there aren’t any in Opa.

If you have no prior experience with functional programming, the notion of a lack of loops can be truly confounding; how can you write programs without loops? It turns out that just as you can do without variables [see Bindings Versus Variables], you can also do without loops.

In Chapter 6, you wrote a function to compute the length of a list using recursion instead of iteration (i.e., loops). It turns out that recursion is a very powerful notion and it can replace loops altogether.

Opa has an even more powerful weapon in its arsenal: iterators. Iterators in Opa have a slightly different meaning than in imperative languages; they are functions that capture some important schema for manipulating collections.

To make this discussion more concrete, let’s discuss three important iterators on lists: List.filter, List.map, and List.iter:

Here is a summary of those iterators:

List.map(_ * 3, [1, 2, 3, 4]) = [3, 6, 9, 12]
List.filter(_ < 3, [1, 2, 3, 4]) = [1, 2]
List.iter(f, [1, 2, 3, 4]) = f(1); f(2); f(3); f(4)

Now that you’ve learned about pattern matching, polymorphic types, iterators, recursive types, and functions, it’s time to apply this knowledge to a real project.

In Coding a Mini Wikipedia of this book, all the applications we developed, except for the chat app, consisted of a single source file. This is fine for very simple projects, but it’s unlikely to work very well for more elaborate ones. It is time to learn how to create such projects.

The overhead of creating such projects is minimal, but Opa features a tool that helps in setting up new projects. To get started, change to a root directory in which you can create the new project, and enter the following:

Tokyo:opa henri$ opa create birdy --template mvc

This will create a new birdy directory containing a complete scaffolding for it. The resultant directory is similar to the one in Chapter 6 and has the following structure:

+- birdy
| +- Makefile
| +- Makefile.common
| +- opa.conf
| +- resources
| | +- css
| | | +- style.css
| +- src
| | +- model
| | | +- data.opa
| | +- view
| | | +- page.opa
| | +- controller
| | | +- main.opa

This newly created project includes the following:

The opa-create tool allows for some customization; for instance, it supports multiple templates that can be set with the --template TEMPLATE_NAME argument. Version 1.1 of Opa supports three templates:

Every template provides a Makefile that eases the compilation of the project with:

make

and compilation followed by execution with:

make run

Your application should look like Figure 7-1.

Figure 7-1. Birdy application created with MVC

Let’s take a quick look at the opa.conf file. In our newly created project, it will look as follows:

birdy.controller:
  import birdy.view
  src/controller.opa

birdy.view:
  import birdy.model
  import stdlib.themes.bootstrap
  src/view.opa

birdy.model:
  src/model.opa

Usage of such a configuration file is optional, but it can be quite convenient as it creates a central point listing all project files and packages, as well as dependencies between them. You can consider this as a way to sanitize your project further.

Packages are the main unit of abstraction in Opa. For Birdy, there are three packages: birdy.controller, birdy.view, and birdy.model. Each section starts with optional import statements, followed by the list of paths to files constituting the given package (one file per project in this example).

Packaging is very important in Opa, as typechecking and compilation are done separately at the package level. Packages are therefore highly reusable bits of code and a major addition to JavaScript, which even lacks modules.

Packaging is also very powerful when combined with abstract data types, which hide types from other packages. We will introduce the latter feature in the next chapter.

In this chapter you learned more about Opa types; in particular, you learned how to use:

Using Opa, you generated an MVC template for your first big project, Birdy, looked inside the opa.conf file, and learned about packages. In the next chapter you will learn how to manage user accounts in Birdy.

Before we jump into proper login/registration features, let’s take a moment to slightly customize the default view to better suit the needs of our application.

First, take a look at the code of the view part of the application, as it was generated by opa create. You will find it in src/view/page.opa and it should look as follows:

module Page {

   // View code goes here

  function page_template(title, content) {
    html =
      <div class="navbar navbar-fixed-top">
        <div class=navbar-inner>
          <div class=container>
            <a class=brand href="./index.html">birdy</>
          </div>
        </div>
      </div>
      <div id=#main class=container-fluid>
        {content}
      </div>
    Resource.page(title, html)
  }

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

}

This code defines a Page module with two functions: page_template, which is a template of any page, parameterized by its title and content; and default_page, a default page using the page_template function and which, for now, is set up to be displayed for every page of the application (we will explain this in more detail later).

Now we will build the Birdy home page using page_template and Bootstrap’s hero-unit element. Hero-unit is a clearly visible box for taglines and other important content.

We will put the HTML content of the home page into the main_page_content value:

  main_page_content =
    <div class=hero-unit>
      <h1>Birdy</h1>
      <h2>Micro-blogging platform.<br/>
        Built with <a href="http://opalang.org">Opa.</a>
      </h2>
    </div>

We won’t use the default_page function. Instead, we will create a main_page function and use a page_template function to display the content:

  function main_page() {
    page_template("Birdy", main_page_content)
  }

The last thing to do is to register main_page as the default page of the application. This is taken care of by the controller, the code of which is in src/controller/main.opa. We talked about URL dispatching in URL Dispatching, so the code in that file should not present any surprises and all we have to do for now is replace Page.default_page with Page.main_page:

module Controller {

  // URL dispatcher of your application; add URL handling as needed
  dispatcher = {
    parser {
    case (.*) : Page.main_page()
    }
  }

}

After making those changes, run the application and it should look like Figure 8-1.

Figure 8-1. Birdy home page v01

We will use Bootstrap to build the modal window UI so that we don’t have to deal with graphical widgets manually in Opa: don’t reinvent the wheel unless you have to! Modal windows are windows that block the main application and require the user to interact with the window before returning control back to it. Figure 8-2 presents a demo of a modal window from the Bootstrap page.

Figure 8-2. Modal window demo from the Bootstrap page

To offer these features, Bootstrap provides the CSS and DOM nomenclature we discussed in previous chapters, as well as a set of components with interaction aspects implemented in a JavaScript library.

Opa is directly and fully compatible with JavaScript, so it will be very easy to use this library and others.

We will start by creating the “Sign up” feature and its user interface. First we’ll create a new View file, src/view/signup.opa, and add it to the project by modifying the view part of opa.conf. Then we’ll import the stdlib.widgets.bootstrap.{modal} package, which provides the Bootstrap’s modal window, drop-down, and alert features in the opa.conf file:

[...]
birdy.view:
        import birdy.model
  import stdlib.widgets.bootstrap.{modal}
        import stdlib.themes.bootstrap
        src/view/page.opa
  src/view/signup.opa
[...]

Note that we are splitting the view into several source files and placing them in a view subdirectory.

For now, in the Signup module we would like to have two pieces of the user interface: the modal window and a button to activate it. Since the id attribute of the window will be used to identify it, it is a good practice to make a constant referring to it:

module Signup {

  window_id = "signup"

}

Now we will create the code for the modal window itself. For this, we will use the Modal.make function of the bootstrap.modal package. It takes five arguments: the window identifier, HTML markup of its header, body, and footer, and the options for the modal window.

function modal_window_html() {
  win_body =
    <div>
      Sign up form will appear here
    </>
  win_footer =
    <>
      Submit button will appear here
    </>
  Modal.make(window_id, <>New to Birdy?</>, win_body, win_footer, Modal.
  default_options)
}

For now, win_body and win_footer are just placeholders for the registration form and the Submit button that we will put there in Form Handling in Opa: Registration Form.

It is time to create a “Sign up” button on the home page that will fire up the modal window. It will be just a regular HTML link, with the data-toggle=modal attribute (which indicates that it’s a toggle for the modal window) and the href attribute pointing to the ID of the window:

  signup_btn_html =
    <a class="btn btn-large btn-primary" data-toggle=modal href="#{window_id}">
      Sign up
    </a>
}

With those two elements in place, we can put the markup for the modal window, which is invisible by default until window opening is triggered, in page_template in src/view/page.opa:

function page_template(title, content) {
  html =
    <div class="navbar navbar-fixed-top">
      <div class=navbar-inner>
        <div class=container>
          <a class=brand href="./index.html">birdy</>
        </div>
      </div>
    </div>
    <div id=#main class=container-fluid>
      {content}
      {Signup.modal_window_html()}
    </div>
  Resource.page(title, html)
}

Here is the code to place the “Sign up” button into main_page_content:

  main_page_content =
    <div class=hero-unit>
      <h1>Birdy</h1>
      <h2>Micro-blogging platform.<br/>
        Built with <a href="http://opalang.org">Opa.</a>
      </h2>
      <p>{Signup.signup_btn_html}</p>
    </div>

Our application now looks similar to Figure 8-3, which has some additional style.

Figure 8-3. Birdy home page v02

Web forms are used to collect input from the user. Opa makes it very easy to use them by means of the stdlib.web.forms package, which we first need to import in the opa.conf file:

import stdlib.web.forms

The two main modules of this package are Field and Form. The former one is used to create fields of the form and the latter to compose a form of them.

Our registration form will consist of four fields: one each for entering the username, email, password, and a repetition of the password (used to rule out the possibility of making a typo while providing the password). We will turn each field into a private variable in our Signup module. For instance, the one for the username field will look as follows:

private fld_username =
  Field.text_field({Field.new with
    label: "Username",
    required: {with_msg: <>Please enter your username.</>},
    hint: <>Username is publicly visible. You will use it to sign in.</>
  })

We used the Field.text_field function to create a new text field. The type of the field will influence the type of the value we obtain when reading the state of the field. The text field will give us a value of type string, but, for instance, the input field for an email will return a value of type Email.email. What if the user enters text that is not a valid email address? We will discuss that topic in a moment.

There is only one argument to the Field.text_field method, and it is a record with a description of this field. It is usually a good idea to extend the default Field.new value, only alerting the relevant aspects. In our case, we:

In a similar manner, we can create a field for the user’s email, but now using the Field.email_field function:

private fld_email =
  Field.email_field({Field.new with
    label: "Email",
    required: {with_msg: <>Please enter a valid email address.</>},
    hint: <>Your activation link will be sent to this address.</>
  })

Next in line is the field for the password:

private fld_passwd =
  Field.passwd_field({Field.new with
    label: "Password",
    required: {with_msg: <>Please enter your password.</>},
    hint: <>Password should be at least 6 characters long and contain at least one digit.</>,
    validator: {passwd: Field.default_passwd_validator}
  })

We use the Field.passwd_field which also creates a field with an associated value of type string, but the field shows asterisks instead of the actual text to protect the password from onlookers, and the obtained string value is a hashed value of the password, ready to be stored in the database. Storing plain-text passwords is unacceptable from the point of view of security, and this feature of Opa form management enforces the good practice of properly processing the password before storing it. Whenever a web application or service is able to send you an email that contains your password in clear text (e.g., when you’ve forgotten it), you know you are in trouble!

The only other new aspect is the validator, which is a passwd validator for password, and is parameterized by the specification of the site’s requirements on the passwords that can be used by its users. In this case, we are happy with the default specification of Field.default_passwd_validator, which corresponds to the requirements that are outlined in the hint.

Finally, our last field is the repeated password:

private fld_passwd2 =
  Field.passwd_field({Field.new with
    label: "Repeat password",
    required: {with_msg: <>Please repeat your password.</>},
    validator: {equals: fld_passwd, err_msg: <>Your passwords do not match.</>}
  })

The only new piece here is the equals validator that checks that a value of the field is precisely the same as the previous one, fld_passwd here. The beauty of Opa’s type safety is also visible here: we can only enforce equality for two fields of the same type. If we tried to ensure equality of, for example, one field with an email and another one with a password, we would end up with a compile type error message.

Now that we have all the fields in place, we can construct a form with those fields and put it in place of the previous placeholder in our modal window. The new version of the modal_window_html function becomes:

function modal_window_html() {
    form = Form.make(signup, {})
    fld = Field.render(form, _)
    form_body =
      <>
        {fld(fld_username)}
        {fld(fld_email)}
        {fld(fld_passwd)}
        {fld(fld_passwd2)}
      </>
    win_body = Form.render(form, form_body)
    win_footer =
      <a href="#" class="btn btn-primary btn-large" onclick={Form.submit_
      action(form)}>Sign up</>
    Modal.make(window_id, <>New to Birdy?</>, win_body, win_footer, Modal.
    default_options)
}

Let’s go through this code step by step. First, we create a new empty form by calling the Form.make function. It takes two arguments: a function to call on successful form submission (signup, which we will write next) and a configuration record, which allows a certain degree of customization for the form. Here we are happy with the defaults, and therefore just supply it with an empty record.

Second, we construct form_body, which is just a regular xhtml value. We place form fields there with calls to the Field.render function, which takes two arguments: the form and its field to render. Since we will be repeatedly displaying fields of a single form, we first create a convenient abbreviation, fld, and use it subsequently to construct the form_body value.

Then, we replace the previous placeholder that we used for the window body (win_body) with the form, which we get using the Form.render function with two arguments: the form and its body.

Finally, we add a “Sign up” button. Its onclick event invokes the Form.submit_action function, which takes care of form processing by doing the following:

It is worth noting that Opa takes care of all the form handling for us, including (client-side) form validation, presentation of error messages, and presentation of explanatory text to the user (optionally, only for the active field), among other features.

Now it is time to focus on the missing signup function, which is called when the form validates successfully:

private client function signup(_) {
  email = Field.get_value(fld_email) ? error("Cannot read form email")
  username = Field.get_value(fld_username) ? error("Cannot read form name")
  passwd = Field.get_value(fld_passwd) ? error("Cannot read form passwd")
  Modal.hide(#{window_id})
  new_user = ~{email, username, passwd}
  #notice =
    match (User.register(new_user)) {
      case {success: _}:
        Page.alert("Congratulations! You are successfully registered. You will receive an email with account activation instructions shortly.", "success")
      case {failure: msg}:
        Page.alert("Your registration failed: {msg}", "error")
    }
}

First, we read the values of the three form fields using the Field.get_value function. The fourth, repeated password, being redundant, is skipped. On the next line we hide the modal window, with Modal.hide. Then we construct a record, new_user, holding all user-provided information, and call a function to register this new user, User.register, which we will build in Modeling and Adding Users. This function will return a value of type outcome(void, string). Depending on this outcome, we construct an appropriate alert message and put its content in the element with the notice ID, which will be used for system messages and which we will pass to the function page_template:

<span id=#notice class=container>{notice}</span>

  ...
    <div id=#main class=container>
      <span id=#notice />
      {content}
    </>
  ...

[...]
birdy.view:
  import birdy.model
  import stdlib.widgets.bootstrap.{modal,alert}
[...]

function alert(message, cl) {
    <div class="alert alert-{cl}">
      <button type="button" class="close" data-dismiss="alert">×</button>
      {message}
    </div>
  }

function page_template(title, content, notice) {
    html =
      <div class="navbar navbar-fixed-top">
        ...
      </div>
      <div id=#main class=container-fluid>
        <span id=#notice class=container>{notice}</span>
        {content}
        {Signup.modal_window_html()}
      </div>
    Resource.page(title, html)
}

function main_page() {
    page_template("Birdy", main_page_content, <></>)
  }

So far you’ve learned about the view part of the registration process, so now it is time to turn our attention to the model.

We will need to create two new files:

Let’s add them to the src/model/opa.conf file:

[...]
birdy.model:
      src/model/data.opa
      src/model/user.opa
      src/model/topic.opa

Before we start working on model files, let’s learn some type definitions.

Let’s start with a type definition for the username:

abstract type User.name = string

This is an abstract type. This means the type can be treated as a string within the package in which this type declaration occurs; however, outside of this package it is opaque, and therefore can only be manipulated by functions from the package. This is a very powerful abstraction mechanism that allows you to hide implementation details and expose only those operations on values of a given type that you choose to expose. It also helps tremendously in terms of making sure that value invariants are preserved, as we will discuss soon.

Then we introduce the user’s status:

abstract type User.status = {active} or {string activation_code}

The user account can be either active or awaiting activation, in which case we store the activation_code.

We then declare a type for topics in /src/model/topic.opa:

abstract type Topic.t = string

This is just a synonym for a string, but by making it abstract we make sure that it is opaque and can only be manipulated within the package.

We are now ready to give a definition of the user’s account in the src/model/user.opa file:

abstract type User.info =
  { Email.email email,
    string username,
    string passwd,
    User.status status,
    list(User.name) follows_users,
    list(Topic.t) follows_topics
  }

This definition consists of the user’s email, username, password (passwd), status, a list of people the user is following (follows_users), and the list of topics the user follows (follows_topics, a feature that is sadly missing in the Twitter service).

With those declarations in place, we will provide the following database definition, consisting of a set of users indexed by their usernames in src/model/data.opa:

database birdy {
  User.info /users[{username}]
}

You can choose to have many separate database declarations in modules to which they relate, or one central declaration in a dedicated place. For Birdy, we chose the latter approach.

Now we are ready to write our User.register function in src/model/user.opa:

 exposed function outcome register(user) {
    activation_code = Random.string(15)
    user =
      { email: user.email,
        username: user.username,
        passwd: user.passwd,
        follows_users: [],
        follows_topics: [],
        status:{~activation_code}
      }
    x = ?/birdy/users[{username: user.username}]
    match (x) {
      case {none}:
        /birdy/users[{username: user.username}] <- user
        send_registration_email({~activation_code, username:user.username, email: user.email})
        {success}
      case {some: _}:
        {failure: "User with the given name already exists."}
    }
  }

Let’s digest the code step by step. First, we randomly generate the activation_code for the new user. The Random.string function constructs a string of a given length consisting exclusively of lowercase letters. A more generic Random.generic_string function is also available, which takes a string s and a number n and constructs a random string of length n consisting of characters present in s.

Next, we construct a value, user, that represents a new user (it will be of type User.info). Finally, we query the database and check whether a user with the given name already exists. If that is the case, we return failure, indicating that the username is already taken. Otherwise, we add this value to the database, invoke send_registration_email (we will work on that next), and indicate success.

The next step is to send an email to the user, in order to verify that her email address is correct. The email will contain a link with the randomly generated activation code. By clicking on it, the user will complete account activation.

First we will import two packages, stdlib.web.mail and stdlib.web.mail.smtp.client, into the model part of the configuration file. The former is a generic package for email-related activities and the latter is the client for the SMTP, the protocol used for sending emails.

birdy.model:
      import stdlib.web.mail
      import stdlib.web.mail.smtp.client
      src/model/data.opa
      src/model/user.opa
[...]

At the same time, we’ll update the view part by adding the import stdlib.web.client package:

birdy.view:
[...]
      import stdlib.web.client

The stdlib.web.mail package contains, among other things, these two type definitions:

type Email.content = {string text} or {xhtml html} or {string text, xhtml html}

type Email.send_status = { void bad_sender } or { void bad_recipient } or
{ void sending } or { string ok } or { string error }

The stdlib.web.mail.smtp.client contains, among other things, two functions for sending email:

Email.send_status try_send (Email.email from, Email.email to, string subject, Email.content content, Email.options options)

void try_send_async (Email.email from, Email.email to, string subject, Email.content content, Email.options options, (Email.send_status → void)
continuation)

The Email.content type defines the content of the email, allowing the user to provide only a text version, only an HTML version, or both. Then the first five arguments of both functions are the same and include the email address of the sender (from) and recipient (to), the email subject, the email content, and sending options.

The try_send function sends the email synchronously, returning the status of the operation. The try_send_async function sends it asynchronously, and once the sending is complete, it invokes the continuation function with the status of the operation.

Now let’s write the missing send_registration_email function, where we use the asynchronous method of sending emails and ignore the status:

private function send_registration_email(args) {
  from = Email.of_string("no-reply@{Data.main_host}")
  subject = "Birdy says welcome"
  email =
      <p>Hello {args.username}!</p>
      <p>Thank you for registering with Birdy.</p>
      <p>Activate your account by clicking on
        <a href="http://{Data.main_host}{Data.main_port}/activation/{args.
        activation_code}">
          this link
        </a>.
      </p>
      <p>Happy messaging!</p>
      <p>--------------</p>
      <p>The Birdy Team</p>
  content = {html: email}
  continuation = function(_) { void }
  SmtpClient.try_send_async(from, args.email, subject, content, Email.
  default_options, continuation)
}

The email contains an activation link that consists of the name of the domain at which the application is deployed (which is parameterized as a constant), followed by the /activation/ path and then the sequence of characters constituting the activation code itself.

If we deploy our application on the example.com domain, the Data module should contain a constant declaration:

module Data {
  main_host = "example.com"
}

An example activation link would be:

http://example.com/activation/swxrjvaprz

To be able to test emails deploying the application locally, we will declare main_host and main_port separately:

module Data {
  main_host = "localhost"
  main_port = ":8080"
}

As you can see, sending emails does not differ much from constructing regular web pages (although clearly you should refrain from using event handlers in email messages), allowing code reuse between those two features.

Now you can run the application and test the sign-up form. It should look similar to Figure 8-4, which has some additional styling.

Figure 8-4. Birdy sign-up form

Before we more forward, we would like to show you how to add an option to be able to test the application locally without sending users’ activation links via email.

We have to modify our user register function and add an additional user status of NO_ACTIVATION_MAIL, which should be set to active like so:

exposed function outcome register(user) {
    activation_code = Random.string(15)
    status =
      #<Ifstatic:NO_ACTIVATION_MAIL>
      {active}
      #<Else>
      {~activation_code}
      #<End>
    user =
      { email: user.email,
        username: user.username,
        passwd: user.passwd,
        follows_users: [],
        follows_topics: [],
        ~status
      }
    x = ?/birdy/users[{username: user.username}]
    match (x) {
      case {none}:
        /birdy/users[{username: user.username}] <- user
        #<Ifstatic:NO_ACTIVATION_MAIL>
        void
        #<Else>
        send_registration_email({~activation_code, username:user.username, email: user.email})
        #<End>
        {success}
      case {some: _}:
        {failure: "User with the given name already exists."}
    }
  }

In the function <Ifstatic> , <Else> and #<End> are compilation directives. So, if you run your Birdy application using this command:

Moorea:~ ida$ NO_ACTIVATION_MAIL=1 make run

all new users’ accounts will be activated immediately following registration. No account activation email will be sent. We will use this command for Birdy testing so that we don’t need to set a domain name.

The last thing we need to do to complete the registration process is to handle user account activation.

We need to handle URLs of the form /activation/ACTIVATION_CODE that we generated previously. This is the role of the controller. First, let’s change its style, from parsing against an unstructured string to matching against a structured representation of a URL, as we discussed in URL Dispatching.

To do that, we first replace { custom: Controller.dispatcher } with {dispatch: Controller.dispatcher } in the server definition in src/controller/main.opa. Then we need to change the definition of the Controller.dispatch function accordingly. The new version will look as follows:

function dispatcher(Uri.relative url) {
  match (url) {
  case {path: ["activation", activation_code] ...}:
    Signup.activate_user(activation_code)
  default:
    Page.main_page()
  }
}

We’ve included two cases here. The first one handles URLs following the pattern /activation/ACTIVATION_CODE and dispatches rendering of those requests to Signup.activate_user, with the given ACTIVATION_CODE as the only function argument. The second one is a catchall case that dispatches all other requests to the main page that we developed previously.

That was the controller part. Now let’s change the view part. We need to add the function activate_user to our Signup module:

function activate_user(activation_code) {
  notice =
    match (User.activate_account(activation_code)) {
    case {success: _}:
      Page.alert("Your account is activated now.", "success") <+>
      <div class="hero-unit">
        <div class="well form-wrap">
          {Signin.form()}
        </div>
      </div>
    case {failure: _}:
      Page.alert("Activation code is invalid.", "error") <+>
      Page.main_page_content
    }
  Page.page_template("Account activation", <></>, notice)
}

This produces a page using Page.page_template. The content depends on the result of the call to the model function User.activate_account, which tries to activate the user account with the given activation code. Depending on whether that is successful or not, we display to the user an appropriate notification message placing it inside the notice element.

Finally, let’s set the model part and the User.activate_account function:

exposed function outcome activate_account(activation_code) {
  user = /birdy/users[status == ~{activation_code}]
      |> DbSet.iterator
      |> Iter.to_list
      |> List.head_opt
  match (user) {
  case {none}: {failure}
  case {some: user}:
    /birdy/users[{username: user.username}] <- {user with status: {active}}
    {success}
  }
}

Note that we use pipes here. A pipe, |>, takes the result and sends it to the following function.

First, we search for all accounts whose status is inactive and whose activation code corresponds to the one given as a parameter to this function. That gives us a database set, which we then convert to a list and try to get its head.

If there is no head in the list, this means no user account is pending with the given activation code, so we respond with a {failure} result. Otherwise, we have the corresponding user and we just update his status to {active} and return {success}, in which case he will see the notification message saying that activation was successful. Now the user can sign in, so it is time to develop the login feature for our application.

How do we keep track of information related to the currently connected user?

Before we answer that question, let’s begin with two user-related type definitions, in the src/model/user.opa file:

type User.t = { Email.email email, User.name username }

Values of type User.info contain all the information about the user, including his (hashed) password. Therefore, we should be careful with passing those values to the client side, as that would be inefficient: most of this data is not needed most of the time, and moreover, the values contain sensitive information.

A typical approach in such a situation is to create a simplified type containing a subset of the data and use it in most of the places. This is the role of the User.t definition. For more complex types, it often makes sense to create simplified “views” on a type, as one of the fields. In our case, that would mean:

type User.t = { Email.email email, User.name username }
abstract type User.info =
  { User.t data,
    string passwd,
    User.status status,
    list(User.name) follows_users,
    list(Topic.t) follows_topics
  }

But for our application, we will stick with the previous definitions instead.

We can now introduce a type to store information about the currently logged-in user:

type User.logged = {guest} or {User.t user}

You can see that this type is functionally equivalent to option(User.t), as it essentially stores an optional value of type User.t. But having such dedicated descriptive types often leads to much cleaner code and easier understanding of the code.

So now we are ready to answer the question we posed earlier: how do we associate data with the currently connected user? In Opa, this is achieved with the UserContext module:

private UserContext.t(User.logged) logged_user = UserContext.make({guest})

The UserContext.make function creates a new user-aware value, and the argument given to it is the initial value for every user. We can then read it with the UserContext.get function or modify it with UserContext.set, in which case it will only be modified for the relevant user.

To get username and email out of User.info, we will use the following function:

private function User.t mk_view(User.info info) {
  {username: info.username, email: info.email}
}

We can now write the login function:

exposed function outcome(User.t, string) login(username, passwd) {
  x = ?/birdy/users[~{username}]
  match (x) {
  case {none}: {failure: "This user does not exist."}
  case {some: user}:
    match (user.status) {
    case {activation_code: _}:
      {failure: "You need to activate your account by clicking the link we sent you by email."}
    case {active}:
      if (user.passwd == passwd) {
        user_view = mk_view(user)
        UserContext.set(logged_user, {user: user_view})
        {success: user_view}
      } else
        {failure: "Incorrect password. Try again."}
    }
  }
}

We query the database for a user with the given username, and if it is absent, we fail with the “This user does not exist.” message. Otherwise, we check the user’s status. If it’s awaiting activation, we fail with the appropriate message. Finally, we compare the user’s password with the given one. If they match, we use UserContext.set to note that the user is now logged in, and we succeed with the value representing the user; otherwise, we fail with “Incorrect password…”

We can now turn our attention to the view layer. Let’s create a new file, src/view/signin.opa, with a new Signin module and add it to the configuration file.

We begin by constructing the login form; first, we create its fields:

window_id = "signin"

  private fld_username =
    Field.text_field({Field.new with
      label: "Username",
      required: {with_msg: <>Please enter your username.</>}
    })

  private fld_passwd =
    Field.passwd_field({Field.new with
      label: "Password",
      required: {with_msg: <>Please enter your password.</>}
    })

No surprises here: just two fields for the username and password, and we saw them both in the sign-up form. Now let’s build the form itself:

private function register(_) {
    Modal.hide(#{window_id});
    Modal.show(#{Signup.window_id});
  }

function modal_window_html() {
  form = Form.make(signin(none, _), {})
  fld = Field.render(form, _)
  form_body =
    <>
      {fld(fld_username)}
      {fld(fld_passwd)}
      <div id=#signin_result />
      <div class="control-group">
        <div class="controls">New to Birdy? <a onclick={register}>Sign up</>.
        </div>
      </div>
    </>
  win_body = Form.render(form, form_body)
  win_footer =
    <a href="#" class="btn btn-primary btn-large" onclick={Form.submit_
    action(form)}>Sign in</>
  Modal.make(window_id, <>Sign in</>, win_body, win_footer, Modal.default_
  options)
}

This code is very similar to its sign-up counterpart. Perhaps the only novel part is that the form body, apart from the two fields, contains a link allowing a user without an account to sign up. The onclick action of this link simply closes the sign-in modal window and opens the one for signing up.

To handle the sign-up action, we will call modal_window_html in page_template in src/view/page.opa:

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

For a better user experience, we will add the following function that displays the “Sign in” form on the page where the user is redirected after successful account activation:

function form() {
  form = Form.make(signin(some("/"), _), {})
  fld = Field.render(form, _)
  form_body =
    <div class="signin_form">
      <legend>Sign in and start messaging</legend>
      {fld(fld_username)}
      {fld(fld_passwd)}
      <a href="#" class="btn btn-primary btn-large"
         onclick={Form.submit_action(form)}>Sign in</>
    </div>
  Form.render(form, form_body)
}

The last bit is the signin function to be called to process the form:

private function signin(redirect, _) {
    username = Field.get_value(fld_username) ? error("Cannot get login")
    passwd = Field.get_value(fld_passwd) ? error("Cannot get passwd")
    match (User.login(username, passwd)) {
    case {failure: msg}:
      #signin_result =
        <div class="alert alert-error">
          {msg}
        </div>
      Dom.transition(#signin_result, Dom.Effect.sequence([
        Dom.Effect.with_duration({immediate}, Dom.Effect.hide()),
        Dom.Effect.with_duration({slow}, Dom.Effect.fade_in())
      ])) |> ignore
    case {success: _}:
      match (redirect) {
      case {none}: Client.reload()
      case {some:url}: Client.goto(url)
      }
    }
  }

Here we fetch the values of the form fields and invoke the model’s User.login function. In case of failure, we put an error message in the signin_result placeholder and then perform a simple animation to fade in this message. In case of success, we redirect the user to her wall page, the /user/USERNAME URL, which will contain the user’s own messages, messages posted by users she follows, and messages mentioning topics she follows; a first-time user will land on an empty page where she can start posting messages. We will develop this later in User and Topic Pages.

We need to add an accessory function in the User module for the username exposed as a string (remember that the User.name type is abstract):

function string get_name(User.t user) {
  user.username
}

As we decided in the beginning of the application development process, the “Sign in” link should be placed on the top bar of the page. To do this, we will create a contextual element that displays a “Sign in” link for users who have not yet logged in, and a drop-down menu with a link to log out (or other features) for logged-in users.

We will need to know who is logged in and be able to log them out, so let’s start by adding two appropriate functions in our User module:

function User.logged get_logged_user() {
  UserContext.get(logged_user)
}

function logout() {
  UserContext.set(logged_user, {guest})
}

Since we will be using a drop-down menu, let’s add dropdown to the import stdlib.widgets.bootstrap package of the configuration file, create a new src/view/topbar.opa file with a Topbar module in the birdy.view package, and add it to the configuration file as well.

In our Page module, we will move the top-bar markup to this newly created Topbar module, so we replace this:

...
  <div class=container>
    <a class=brand href="./index.html">birdy</>
  </div>
...

with this:

...
  <div class=container>
    {Topbar.html()}
  </>
...

Now we will add the HTML elements taken from the Page module to the Topbar module. We will also create a user_menu element.

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

Now let’s use the Bootstrap nav element to style the “Sign in” link and the drop-down menu:

signinup_btn_html =
  <ul class="nav pull-right">
    <li>
      <a data-toggle=modal href="#{Signin.window_id}">Sign in</a>
    </li>
  </ul>

function user_menu() {
  match (User.get_logged_user()) {
    case {guest}: signinup_btn_html
    case ~{user}: user_box(user.username)
  }
}

The user_menu function checks whether the user is currently logged in. If the user is logged in, we add the user_box to the top bar; if not, we include a reference to the “Sign in” link.

private function user_box(username) {
  id = Dom.fresh_id()
  <ul id={id} class="nav pull-right">
    <li class="dropdown">
      <a href="#" class="dropdown-toggle" data-toggle="dropdown">
        {username}
        <b class="caret"></b>
      </a>
      <ul class=dropdown-menu>
        <li><a onclick={logout} href="#">Sign out</></>
      </>
    </>
  </>
}

The user_box function first obtains a unique DOM ID for the drop-down menu. Thus far, we have always used manually chosen identifiers, which is fine for fixed elements, and therefore, we could have used them here as well. However, if we generate DOM elements programmatically, we may need some other way of assigning identifiers to them. This is the role of Dom.fresh_id.

Once again we will use the Bootstrap nav element to style our username link and a dropdown menu. We create a <ul> element with appropriate markup for a Bootstrap drop-down menu. Use of the data-toggle attribute with Bootstrap allows us to activate the menu by clicking on the username link. The drop-down menu items are encoded via the <ul> tag. For now we only have a single entry for Sign out, which calls the logout function when the user logs out:

private function logout(_) {
  User.logout();
  Client.reload()
}

The logout function logs the user out and reloads the page, via Client.reload, to refresh the top bar; our element will now indicate that no user is logged in.

Compile and run your Birdy application now to test the “Sign in” form, which should look similar to Figure 8-5.

Figure 8-5. Birdy “Sign in” form