Permalink
Browse files

doc: Work on the modules manual

  • Loading branch information...
1 parent 05d9d0d commit ec5ef9c421bfa9d3bde568c11bd5c4d0c02b2335 @arjan arjan committed Sep 30, 2012
@@ -15,4 +15,13 @@ div.note {
div.body h1, div.body h2, div.body h3,
div.body h4, div.body h5, div.body h6 {
background: inherit;
+}
+
+pre {
+ font-size: 13px;
+ line-height: 140%;
+}
+
+tt {
+ font-size: 13px;
}
View
@@ -80,6 +80,8 @@
# output. They are ignored by default.
#show_authors = False
+highlight_language = 'erlang'
+
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
View
@@ -13,7 +13,7 @@ In-depth manuals
.. toctree::
dispatch
- module-system
+ modules/index
services
auth
notification
@@ -1,69 +0,0 @@
-.. _manual-modules:
-
-The module system
-=================
-
-.. seealso:: listing of all :ref:`modules`.
-
-Modules are the building blocks of Zotonic.
-
-Examples of modules are the `/admin` site, `Atom feeds`, the `sitemap.xml`, video embed code handling and SEO optimization. Modules also augment the functionality of other modules by adding extra :ref:`templates` and accompanying logic or adding handlers for internal Zotonic events. Good examples are the modules extending the :ref:`mod_admin`.
-
-A module is a gen_server with accompanying templates, Webmachine resources (called :ref:`controllers`), :ref:`dispatch` and more, all contained in a single module directory tree.
-
-The page :ref:`manual-module` has more information about the internals of a module.
-
-**Looking for more modules?**
-
-Check out the `Zotonic Module Index`_, an index with user-contributed modules which are not part of the core Zotonic distribution.
-
-.. _Zotonic Module Index: http://modules.zotonic.com
-
-
-Metadata
---------
-
-Lorelay...
-
-
-Module versioning
------------------
-
-Modules export a ``-module_schema()`` attribute which contains an
-integer number, denoting the current module's version. On module
-initialization, ``Module:manage_schema/2`` is called which handles
-installation and upgrade of data.
-
-Minimal example::
-
- -module(mod_twitter).
- -mod_title("Twitter module").
- -mod_schema(3). %% we are currently at revision 3
-
- -export([manage_schema/2]).
- .... more code here...
-
- manage_schema(install, Context) ->
- % .. code to install your stuff here, for instance:
- #datamodel{categories=
- [
- {tweet,
- text,
- [{title, <<"Tweet">>}]}
- ]};
-
- manage_schema({upgrade, 2}, Context) ->
- %% code to upgrade from 1 to 2
- ok;
-
- manage_schema({upgrade, 3}, Context) ->
- %% code to upgrade from 2 to 3
- ok.
-
-Note that the install function should always be kept up-to-date
-according to the latest schema version. When you install a module for
-the first time, no upgrade functions are called, but only the
-``install`` clause.
-
-
-
@@ -0,0 +1,41 @@
+-module(mod_example).
+-author("Nomen Nescio <nomen@example.com>").
+
+-behaviour(gen_server).
+
+-mod_title("Your module title").
+-mod_description("Description what this module does.").
+-mod_prio(500).
+
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2, code_change/3]).
+-export([start_link/1]).
+
+-include_lib("zotonic.hrl").
+-record(state, {context}).
+
+
+%% Module API
+
+start_link(Args) when is_list(Args) ->
+ gen_server:start_link(?MODULE, Args, []).
+
+%% gen_server callbacks
+
+init(Args) ->
+ {context, Context} = proplists:lookup(context, Args),
+ {ok, #state{context=z_context:new(Context)}}.
+
+handle_call(Message, _From, State) ->
+ {stop, {unknown_call, Message}, State}.
+
+handle_cast(Message, State) ->
+ {stop, {unknown_cast, Message}, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(_OldVsn, State, _Extra) ->
+ {ok, State}.
@@ -0,0 +1,39 @@
+.. _manual-modules-gen_server:
+
+gen_server based modules
+========================
+
+When you need a running process, e.g., a module that does something in
+the background, then it is possible to implement your module as a
+gen_server. A gen_server is a standard way to implement a reliable
+Erlang worker process.
+
+In that case you will need to add the behaviour and
+gen_server functions. You also need to change the ``init/1`` function to
+accept an property list, which contains the site definition and a
+``{context, Context}` property.
+
+This server module will be started for every site in a Zotonic system
+where the module is enabled, so it can’t be a named server.
+
+
+.. seealso:: `Erlang gen_server principles <http://www.erlang.org/doc/design_principles/gen_server_concepts.html>`_
+
+A minimal example
+---------------------------------
+
+.. literalinclude:: ex_module_gen_server.erl
+
+As you can see, this code is almost identical to the standard Erlang
+``gen_server`` boilerplate, with the exception of the metadata on top.
+
+You also see that the ``start_link/1`` function is already
+implemented. Note that in this function the gen_server is started
+without registering the server under a name: this is done because the
+module can be started multiple times; once for each site that needs
+it.
+
+The ``init/1`` function contains some more boilerplate for getting the
+``context{}`` argument from the arguments, and storing this context
+into the server's state. This way, you'll always have access to the
+current context of the site in the rest of the gen_server's functions.
@@ -0,0 +1,40 @@
+.. _manual-modules:
+
+The module system
+=================
+
+Modules are the building blocks of Zotonic.
+
+Examples of modules are the `/admin` site, `Atom feeds`, the
+`sitemap.xml`, video embed code handling and SEO optimization.
+Modules also augment the functionality of other modules by adding
+extra :ref:`templates` and accompanying logic or adding handlers for
+internal Zotonic events. Good examples are the modules extending the
+:ref:`mod_admin`.
+
+A module is a gen_server with accompanying templates,
+:ref:`controllers`, :ref:`dispatch` and more, all contained in a
+single module directory tree.
+
+.. toctree::
+ :maxdepth: 2
+
+ structure
+ gen_server
+ versioning
+
+.. seealso:: listing of all :ref:`ref-modules`.
+
+
+**Looking for more modules?**
+
+Check out the `Zotonic Module Index`_, an index with user-contributed modules which are not part of the core Zotonic distribution.
+
+.. _Zotonic Module Index: http://modules.zotonic.com
+
+
+Metadata
+--------
+
+Lorelay...
+
Oops, something went wrong.

0 comments on commit ec5ef9c

Please sign in to comment.