Writing your own Zotonic module -- part I
This will be a series of articles covering how to write your own custom module for zotonic.
The official documentation for modules is quite brief, and gives no details of how the various parts of a module works or should be implemented. This series goal is to fill those wholes.
In this first part, I'll guide you through the first easy steps to get a module up & running within zotonic. It won't do anything fancy; and nothing noticeable from a front-end perspective.
During this series, we'll be developing a sample module, which I will call mod_gazonk, to avoid as many future name conflicts as possible. In the end, it will provide at least a custom: action, filter, template, model, resource, scomp (screen component), service, validator and dispatch rule.
Source code for mod_gazonk.
Let's get to it!
Step I
First thing is to create a directory where we'll be developing our module. Let's keep it simple and place it in our home directory (any directory will do, but it should begin with `mod_'):
$ mkdir ~/mod_gazonk
I will refer to this directory as the `module directory'.
Step II
Now, we'll need the module source code, which should be placed in a erlang source file with the same name as the module directory (plus the .erl file extension):
$ touch ~/mod_gazonk/mod_gazonk.erl
This file does not need much, to be picked up as a module by zotonic. Actually, to make sure zotonic finds the module, lets keep it real simple and simply put a single line in the file:
%% file: mod_gazonk/mod_gazonk.erl -module(mod_gazonk).
Step III
For zotonic to find our module, we need to put our module directory (or, preferably, a link to it) somewhere where zotonic will spot it. There are a few options.
Zotonic will look for modules in these directories (realtive to zotonic's base directory):
- modules/
- priv/sites/*/modules (per site modules, i.e. the module will only be available to a single site)
- priv/modules/ (from zotonic version 0.7.x and later)
The first is where all zotonic core modules reside, so we better keep out of there. If you're running any version prior to 0.7 (which hasn't been released yet) we're out of options though, unless you can stick with a single site module. To recap, if you're using 0.6 or earlier and want your module available to all sites, you have to place it in the `modules/' directory. If you're on the bleeding edge of 0.7, you can place it in `priv/modules/'. Or, regardless of version, for a module that is only needed by a single site, you may place it in `priv/sites/{your_site}/modules/'.
I'm on 0.7.x, so I'll put it in `priv/modules':
$ ln -s ~/mod_gazonk zotonic/priv/modules/mod_gazonk
Now, either (re)start zotonic, or press `rescan modules' from the `Modules' section of the admin interface (http://yoursite.com/admin/modules).
Your module should now show up in the list of modules with the name `gazonk', and dashes for description and author, and a prio of 500 (which is the default, when not specified in the module).
I'll explain prio later.
Closing remarks
Ok, that was quite a bit of text, with close to no progress, but we've set the foundation to build upon. Also, if you're like me, who'd rather read than type along with this boring tutorials, you can clone the source from my hg repo for this series.
I will tag the final version of the repo after each part in the series, so you see which changes have been applied when looking at the change log. I will give some hints as to how to accomplish that when we get there.
Comments
Alain O'Dea
Posted 1 year, 11 months ago.
Very nice. Thank you Andreas. This is getting me off the ground with some simple modules I am looking to build for integrating Disqus and SyntaxHighlighter into Zotonic.
douglasv
Posted 1 year, 9 months ago.
Thank you for the tutorial.
Great Stuff!