Zotonic: the Erlang Content Management System

You already have seen the show_media filter above, and many other filters exist to transform data for output. Other than filters, front-end development in Zotonic is aided by tags and scomps.

In the example above, I used the block tag to replace the content area in the template that I'm extending. Other tags that I use often are if, for and lib:

{% if id == 1 %}
    <p>The ID is 1</p>
{% endif %}
    
{% for color in ["bleu", "blanc", "rouge"] %}
    <p>{{ color }}</p>
{% endfor %}

The lib tag can be used to import an aggregate of stylesheets or scripts to reduce the number of requests to the server:

{% lib 
        "css/zp-menu.css"
        "css/zp-project.css"
    
%}

Scomps, or screen components, are used when tags are not powerful enough and more logic is needed. The scomps that I use most frequently are menu and validate.

Menu is used to insert the standard Zotonic menu into your site:

{% menu id=id %}

Validate is used to validate a form field at both the front end and the back end:

<input 
    type="password" 
    id="password" 
    name="password" value="" />
<input 
    type="password" 
    id="password2" 
    name="password2" value="" />
{% validate id="password" 
    type={confirmation match="password2"} %}

If you are willing to write some Erlang code, Zotonic can become much more than just a content management system. You can extend Zotonic with modules. The modules can be stored in the modules subdirectory of your site.

To make a module, create a modules directory within your site if it does not already exist:

mdkir priv/sites/default/modules

Let's create a simple module that implements a Web site guestbook. Users will be able to see the existing guestbook posts and add a new post.

Create a directory called mod_guestbook within the modules directory:

mkdir priv/sites/default/modules/mod_guestbook

Using your favorite text editor, create a file in this directory called mod_guestbook.erl, and in this file, put the following code:

%% @author Michael Connors
%% @doc A guestbook module. 
-module(mod_guestbook).
-author("Michael Connors <michael@bring42.net>").
-mod_title("Guestbook").
-mod_description("A simple guestbook module.").
-mod_prio(500).
    
%% interface functions
-export([
    init/1,
    datamodel/0
]).
    
-include_lib("zotonic.hrl").
    
%% @doc Initiates the server.
init(Context) ->
    %% Manage our data model
    z_datamodel:manage(?MODULE, 
                       datamodel(), 
                       Context).
datamodel() ->
    [{categories,
      [
       {gp,
        text,
        [{title, <<"Guestbook Post">>}]}
      ]
     }
    ].

Stop Zotonic and run make again. This will build your new module. Now, restart Zotonic, and log in to the admin. Go to the modules page, and observe that there now is a new module called Guestbook.

You can see here the values defined in the code for author, mod_title, mod_description and mod_prio. The Prio value indicates the importance of the module—the highest being 1 and the default being 500. Modules with a higher priority are checked first for templates and scomps.

A percentage symbol in Erlang indicates a comment, so any of the lines in this code preceded by percentage symbols are ignored by the compiler. The first two lines, although comments, also contain special notation, which is used to document the program.

Here, I exported init/1. This is because it must be called by external modules; init has an arity of 1, meaning it takes 1 argument:

-export([
    init/1
]).

If I had a function that took two arguments, I would export it like this:

-export([
    itsname/2
]).

You do not need to export datamodel, because it is used only by the init function in this module.

Init will be called whenever your module is loaded, and the first time it is called, it will create a new category in Zotonic called guestbook_post. This will be a subcategory of “text” and will have the display name Guestbook Post.

For each guestbook post, you should have a title and summary—luckily, all pages in Zotonic already have a title and summary, so without doing anything else, you can add posts to your guestbook by creating pages of the category Guestbook Post. Create a few Guestbook Posts now, ensuring that you fill in the titles and summaries. Also, don't forget to tick Published; otherwise, they won't be visible to users who are not logged in. You can use these to test your guestbook's display, which I discuss next.