How To Create a tryerlang.org Tutorial

Creating tutorials for tryerlang.org is intended to be a straightforward process. Users can create their own tutorials and submit them to us so that they will be included in tryerlang.org. Please note that some Erlang knowledge is required for this.

Designing a "string" tutorial

We want to create a new Erlang tutorial, explaining the user how to use the Erlang string module. To keep things simple, we will focus on just three of the module functions:

• len/1
• tokens/2
• to_upper/1

To create our brand new tutorial, we will need to create a very simple Erlang module implementing the logic for our tutorial and a couple of HTML files, containing the step-by-step instructions for the final users and the success messages (the ones that you can see on the bottom and on the top of the tryerlang.org shell when you execute a tutorial). Let's see how to do this in detail.

The Logic Module

A tryerlang.org tutorial is a very simple Erlang Behaviour, requiring two functions (list/0 and check_result/3) to be implemented.

Let's create a blank Erlang module, declaring that we want to implement the tutorial behaviour. Let's also export the two functions required by the "tutorial" behaviour.

We will call our "logic module" tutorial_string. All user-defined tutorial modules must begin with the "tutorial_" prefix, followed by a user-defined word. In our case, we are going to create a tutorial to teach the user how to use strings, so "string" sounds like a good candidate for the user-defined word).

    -module(tutorial_string).

    -behaviour(tutorial).

    -export([list/0, check_result/3]).
  

The list/0 function

Let's implement the first of the two required callback functions. The list/0 function must return a list of the steps for our tutorial. Each item must be an Erlang atom.

    list() ->
    [
    len,
    tokens,
    to_upper
    ].
  

The check_result/3 function

The check_result/3 function is a bit more complicated, since it contains the logic specific to the steps of the tutorial. It takes three arguments (the parsed data from the Erlang parser, the result from the Erlang evaluator and an integer representing the current step in the tutorial). The function must return {ok, Result} in case of success or {error, Result} in case of fail. Result is what will be printed in the tryerlang.org shell, in either the successful or failing case.

For our trivial tutorial, we want to do something extremely simple. We just want to check that, for a specific step, the required function is called. The provided check module offers a set of utility functions that can be used to perform all this sort of checks. Have a look to the check module to learn how to write your own checking functions.

    check_result(ParsedData, Result, Step) ->
    case check:funct(ParsedData, string, Step) of
    true ->
    {ok, Result};
    false ->
    {error, Result}
    end.
  

Some XHTML files, now

Well, we're done with the "hard" part. We just need to write a couple of XHTML files now. For each step, we need two different files, named [STEP].html and [STEP]_success.html, where "[STEP]" is the step name. In our case we need to create the following files, then:

• len.html
• len_success.html
• tokens.html
• tokens_success.html
• to_upper.html
• to_upper_success.html

The len.html file could look something like:

      <h1>Length</h1>
      <p>
      Let us count how many chars form a string. Try <code>string:len("pigeon").</code>
      </p>
    

While the len_success.html file could be something like:

      <p>
      Very well done!
      </p>
    

The same is true for all other files.

Please note that you're supposed to use valid XHTML files, not simple HTML files.