Yariv’s Blog

If you’ve been reading this blog for a while and you’ve been connecting the dots, you probably know where this is going… :) I you haven’t, that’s ok — my old postings aren’t going anywhere. There’s a lot of Erlang goodness in them for you to soak up at your leisure as you’re getting up to speed on this great language.

Without further ado, I present to you the culmination of all of my exciting adventures thus far in the land of open source Erlang:

ErlyWeb: The Erlang Twist on Web Frameworks.

Don’t worry, I’m not going to blab for a long time now about why I think ErlyWeb + Yaws is the best web development toolkit available (not that I’m biased or anything :) ). Instead, I decided I’ll just take you on a quick tour of how to use ErlyWeb, and let you use your own knowledge about Erlang to fill in the gaps :)

- Get the latest ErlyWeb archive from erlyweb.org, unzip it, and put the zip file’s contents in your Erlang code path. (The Erlang code path is the root directory within which the Erlang VM searches for compiled modules. In OS X, it’s “/usr/local/lib/erlang/lib”. For more information, visit http://www.erlang.org/doc/doc-5.5.4/lib/kernel-2.11.4/doc/html/code.html).

- Download and install Yaws if you don’t already have it.

- Start Yaws in interactive mode (”yaws -i”) and type in the Yaws shell


erlyweb:create_app("music", "/apps").


(I’m assuming that “/apps” is the parent directory of your Yaws apps.)

This will create an ErlyWeb directory structure as well as a few files. (Note: this initial procedure will probably be shorter when ErlyWeb matures.) This is what you should see:


/apps/music
/apps/music/ebin
/apps/music/src/music_app_controller.erl
/apps/music/src/music_app_view.et
/apps/music/src/components
/apps/music/www
/apps/music/www/index.html
/apps/music/www/style.css


- Edit your yaws.conf file by adding a server configuration with the following docroot, appmod, and opaque directives, then type “yaws:restart().”


docroot = /apps/music/www
appmods = <"/music", erlyweb>
<opaque>
  appname = music
</opaque>


- Open your browser and point it at http://localhost:8000/music (note: your host/port may be different, depending on your Yaws configuration). You should see the following page, (breathtaking in its design and overflowing with aesthetic genius, if I may add):

- Create a MySQL database called ‘music’ with the following code (thanks, Wikipedia :) ):


CREATE TABLE musician (
  id integer primary key auto_increment,
  name varchar(20),
  birth_date date,
  instrument enum("guitar", "piano",
    "drums", "vocals"),
  bio text
) type=INNODB;
 
INSERT INTO musician(name, birth_date,
  instrument, bio) VALUES
   ("John Lennon", "1940/10/9", "vocals",
   "An iconic English 20th century
    rock and roll songwriter and singer..."),
   ("Paul McCartney", "1942/6/18", "piano",
     "Sir James Paul McCartney
       is a popular Grammy Award-winning
       English artist..."),
   ("George Harrison", "1943/2/24", "guitar",
     "George Harrison was a popular English
     musician best known as a member of The Beatles..."),
   ("Ringo Star", "1940/7/7", "drums",
    "Richard Starkey, known by his stage name
     Ringo Starr, is an English popular musician,
     singer, and actor, best known as the
    drummer for The Beatles...");
 


- Back in Yaws, type


erlyweb:create_component("musician", "/apps/music").


This will create the following files:

/apps/music/components/musician.erl

-module(musician).


/apps/music/components/musician_controller.erl

-module(musician_controller).
-erlyweb_magic(on).


/apps/music/components/musician_view.erl

-module(musician_view).
-erlyweb_magic(on).


Back in Yaws, type


erlydb:start(mysql, [{hostname, "localhost"}, {username, "username"},
  {password, "password"}, {database, "music"}]).
erlyweb:compile("/apps/music", [{erlydb_driver, mysql}]).


(The erlydb_driver option tells ErlyWeb which database driver to use for generating ErlyDB code for the models. Note: this may change in a future version.)

Now go to http://localhost:8000/music/musician, click around, and you’ll see the following screens:

“Aha!” you may be thinking now, “I bet he’s using some Smerl trickery to call functions that contain mountains of horrible code only comprehensible to Swedish Field Medal winners!”

Well.. um, not exactly. In fact, this is the code for erlyweb_controller.erl


%% @title erlyweb_controller
%% @author Yariv Sadan (yarivsblog@gmail.com, http://yarivsblog.com)
%%
%% @doc This file contains basic CRUD controller logic. It's intended
%%  for demonstration purposes, but not for production use.
%%
%% @license For license information see LICENSE.txt
 
-module(erlyweb_controller).
-author("Yariv Sadan (yarivsblog@gmail.com, http://yarivsblog.com)").
 
-export([
   index/2,
   list/2,
   list/3,
   new/2,
   edit/3,
   delete/3
  ]).
  
-define(RECORDS_PER_PAGE, 10).
 
index(_A, Model) ->
    {ewr, Model, list, [1]}.
 
list(A, Model) ->
    list(A, Model, 1).
 
list(A, Model, Page) when is_list(Page) ->
    list(A, Model, list_to_integer(Page));
 
list(A, Model, Page) when is_integer(Page) ->    
    Records = Model:find_range((Page - 1) * ?RECORDS_PER_PAGE,
             ?RECORDS_PER_PAGE),
 
    %% this function makes the 'edit' links in the record ids
    ToIoListFun =
  fun(Val, Field) ->
    case erlydb_field:name(Field) of
        id ->
      Id = Model:field_to_iolist(Val),
      erlyweb_html:a(
        [erlyweb_util:get_app_root(A),
         atom_to_list(Model),
         <<"edit">>, Id], Id);
        _ ->
      default
    end
  end,
    {data, {erlyweb_util:get_appname(A),
      atom_to_list(Model),
      Model:db_field_names_bin(),
      Model:to_iolist(Records, ToIoListFun)}}.
 
new(A, Model) ->
    Rec = Model:new(),
    new_or_edit(A, Model, Rec).
 
edit(A, Model, Id) ->
    Rec = Model:find_id(Id),
    new_or_edit(A, Model, Rec).
 
new_or_edit(A, Model, Record) ->
    Fields = tl(Model:db_fields()),
    Vals = tl(Model:to_iolist(Record)),
    Combined = lists:zip(Fields, Vals),
    IdStr = case Model:id(Record) of
    undefined -> [];
    Id -> integer_to_list(Id)
      end,
    case yaws_arg:method(A) of
  'GET' ->
      FieldData = [{erlydb_field:name_bin(Field),
        erlydb_field:html_input_type(Field),
        erlydb_field:modifier(Field),
        Val} || {Field, Val} <- Combined],
      {data, {erlyweb_util:get_app_root(A),
        atom_to_list(Model),
        IdStr,
        yaws_arg:server_path(A),
        FieldData}};
  'POST' ->
      NewVals = yaws_api:parse_post(A),
      Record1 = Model:set_fields_from_strs(Record, NewVals),
      Model:save(Record1),
      {ewr, Model, list}
    end.
 
delete(A, Model, Id) ->
    case yaws_arg:method(A) of
  'GET' ->
      Record = Model:find_id(Id),
      Fields = [erlydb_field:name_bin(Field) ||
       Field <- Model:db_fields()],
      Vals = Model:to_iolist(Record),
      Combined =
    lists:zipwith(
      fun(Field, Val) -> [Field, Val] end,
      Fields, Vals),
      
      {data, {erlyweb_util:get_app_root(A),
        atom_to_list(Model), Id,
        Combined}};
  'POST' ->
      Model:delete_id(Id),
      {ewr, Model, list}
    end.


And this is the code for erlyweb_view.et

<%~
%% @title erlyweb_view.et
%% @doc This is a generic view template for making simple CRUD
%%   pages with ErlyWeb. It's intended for demonstration purposes,
%%   but not for production use.
%%
%% @license for license information see LICENSE.txt
 
-author("Yariv Sadan (yarivsblog@gmail.com, http://yarivsblog.com)").
-import(erlyweb_html, [a/2, table/1, table/2, form/3]).
 
%% You can add component-specific headers and footers around the Data
%% element below.
%>
<% Data %>
 
<%@ list({AppRoot, Model, Fields, Records}) %>
<% a(["", AppRoot, Model, <<"new">>], <<"create new">>) %><br><br>
Records of '<% Model %>'<br/>
<% table(Records, Fields) %>
 
<%@ new({_AppRoot, Model, _Id, Action, FieldData}) %>
Create a new <% Model %>:<br/>
<% form(Action, <<"new">>, FieldData) %>
 
<%@ edit({AppRoot, Model, Id, Action, FieldData}) %>
<a href="<% AppRoot %>/<% Model %>/delete/<% Id %>">delete</a>
<br/><br/>
<% form(Action, <<"edit">>, FieldData) %>
 
<%@ delete({AppRoot, Model, Id, Combined}) %>
Are you sure you want to delete this <% Model %>?
<% table(Combined) %>
<form action="<% AppRoot %>/<% Model %>/delete/
<% Id %>"
  method="post">
<input type="submit" value="yes">
<input type="button"
  onclick="location.href='<% AppRoot %>/<% Model%>'"
  value="no">
</form>


Not exactly the stuff that would win anyone the Field Medal, if I dare say so.

If ErlyDB hasn’t convinced you that Erlang is a very flexible language, I hope that ErlyWeb does. In fact, I don’t know of any other language that has Erlang’s combination of flexibility, elegance and power. (If such a language existed, I wouldn’t be using Erlang :) ).

The flexibility of components

The notion of component reusability is central to ErlyWeb’s design. In ErlyWeb, each component is made of a view and a controller, whose files are placed in ’src/components’. All controller functions must accept as their first parameter the Yaws Arg for the HTTP request, and they may return any value that Yaws accepts (yes, even ehtml, but ehtml can’t be nested in other components). In addition, they can return a few special values:


{data, Data}  
{ewr, FuncName}
{ewr, Component, FuncName}
{ewr, Component, FuncName, Params}
{ewc, A}
{ewc, Component, Params}
{ewc, Component, FuncName, Params}


So what do all those funny tuples do?

{data, Data} is simple: it tells ErlyWeb to call the corresponding view function by passing it the Data variable as a parameter, and then send result to the browser.

‘ewr’ stands for ‘ErlyWeb redirect.’ The various ‘ewr’ tuples simplify sending Yaws a ‘redirect_local’ tuple that has the URL for a component/function/parameters combination in the same app:

- {ewr, FuncName} tells ErlyWeb to return to Yaws a redirect_local to a different function in the same component.
- {ewr, Component, FuncName} tells ErlyWeb to return to Yaws a redirect_local to a function from a different component.
- {ewr, Component, FuncName, Params} tells ErlyWeb to return to Yaws a redirect_local to a component function with the given URL parameters.

For example,

{ewr, musician, list, [4]}

will result in a redirect to

http://localhost:8000/music/musician/list/4

‘ewc’ stands for ‘ErlyWeb component.’ By returning an ‘ewc’ tuple, you are effectively telling ErlyWeb, “render the component described by this tuple, and then send the result to the view function for additional rendering.” Returning a single ‘ewc’ tuple is similar to ‘ewr’, with a few differences:

- ‘ewc’ doesn’t trigger a browser redirect
- the result of the rendering is sent to the view function
- {ewc, Arg} lets you rewrite the arg prior to invoking other controller functions.

(If this sounds complex, don’t worry — it really isn’t. Just try it yourself and see how it works.)

Now to the cool stuff: not only can your controller functions return a single ‘ewc’ tuple, they can also return a (nested) list of ‘ewc’ tuples. When this happens, ErlyWeb renders all the components in a depth-first order and the sends the final result to the view function. This lets you very easily create components that are composed of other sub-components.

For example, let’s say you wanted to make blog sidebar component with several sub-components. You could implement it as follows:

sidebar_controller.erl

index(A) ->
  [{ewc, about, [A]},
   {ewc, projects, [A]},
   {ewc, categories, [A]},
   {ewc, tags, [A]}].


’sidebar_view.et’

<%@ index(Data) %>
<div id="sidebar">
<h3>What a sidebar!</h3>
<% Data %>
</div>


Pretty cool, huh?

If you don’t want your users to be able to access your sub-components directly by navigating to their corresponding URLs, you can implement the following function in your controllers:


private() -> true.


This will tell ErlyWeb to reject requests for private components that come from a web client directly.

Each application has one special controller that isn’t part of the component framwork. This controller is always named ‘[AppName]\_app\_controller.erl’ and it’s placed in the ’src’ directory. The app controller has a single function called ‘hook/1′, whose default implementation is


hook(A) -> {ewc, A}.


The app controller hook may return any of the values that normal controller functions return. It is useful for intercepting all requests prior to their processing, letting your rewrite the Arg or explicitly invoke other components (such as a login page).

Well, that’s about it for now :) I’ll appreciate any feedback, bug reports, useful code contributions, etc.

Final words

After reading all this, some of you may be thinking, “This is weird… I thought Erlang is some scary telcom thing, but what I’m actually seeing here is that Erlang is very simple… Heck, this stuff is even simpler than Rails. What’s going on here?”

If that’s what you’re thinking, then you are right. Erlang *is* simpler than Ruby, and that’s why ErlyWeb is naturally simpler than Rails. In fact, Erlang’s simplicity is one of its most underrated aspects. Erlang’s creators knew very well what they were doing when they insisted on keeping Erlang simple: complexity leads to bugs; bugs lead to downtime; and if there’s one thing Erlangers hate the most, it’s downtime.