doc: Add documentation about controllers.

doc/glossary.rst

@@ -44,10 +44,10 @@ Glossary
       A validator is used to check input fields in a HTML form. A validator has two parts: the client side javascript and a server side check. You add validators to a form with the {% validate %} template tag. A validated query argument can be accessed on the server using z_context:get_q_validated/2.
 
    Dispatch rule
-      A dispatch rule maps URL patterns to controllers. Dispatch rules are defined in files in the .dispatch. folder of a Zotonic module. The dispatch rule definitions are also used to generate the urls for resources and other pages.
+      A dispatch rule maps URL patterns to controllers. Dispatch rules are defined in files in the .dispatch. folder of a Zotonic module. The dispatch rule definitions are also used to generate the urls for resources and other pages. See :ref:`manual-dispatch`.
 
    Controller
-      A controller is the main entry point where a request is handled. Controllers are referenced from a dispatch rule. Commonly used controller is controller_template, which serves a template on the URL for which the controller configured. 
+      A controller is the main entry point where a request is handled. Controllers are referenced from a dispatch rule. Commonly used controller is controller_template, which serves a template on the URL for which the controller configured. See :ref:`manual-controllers`.
 
    Context
       The context is the current request context. It contains all the request data, the current site, the handle to the database and the results (scripts or templates) you will be sending back. The context is commonly passed along in Zotonic as the last argument of a function.

doc/manuals/controllers.rst

@@ -3,7 +3,76 @@
 URL Controllers
 ===============
 
-Used to be known as (webmachine) resources.
+:term:`Controllers <Controller>` are the Erlang modules which decide
+what happens when a browser requests a page. Zotonic looks at the
+:term:`dispatch rules <Dispatch rule>` that match the requested URL,
+and if a dispatch rule matches, the controller that is named in the
+dispatch rule is used to handle the request.
 
-Lorem ipsum...
+Internally, Zotonic uses a fork of `Webmachine
+<http://wiki.basho.com/Webmachine.html>`_ for handling the
+requests. What Zotonic calls a `controller`, Webmachine calls a
+`resource`. See also :ref:`manual-controllers-webzmachine`.
 
+
+Anatomy of a controller
+-----------------------
+
+Say we have the following dispatch rule, handling ``http://localhost/example``::
+
+  {example_url, ["example"], controller_example, []},
+
+When hitting ``/example``, the `controller_example` controller will be
+initialized and various callback functions on the controller will be
+called, according to the HTTP protocol flow.
+
+Controllers are pretty self-documenting, thanks to the names of the
+webmachine callback functions. For instance, when you define a
+function ``resource_exists/2``, it will be called to decide whether or
+not the page should return a 404 page.
+
+The simplest controller uses Zotonic's ``html_controller.hrl`` include to serve HTML:
+
+.. code-block:: erlang  
+
+   -module(controller_example).
+
+   -include_lib("html_controller.hrl").
+
+   html(Context) ->
+       {<<"<h1>Hello</h1>">>, Context}.
+
+If you need more examples, :ref:`mod_base` contains many controllers,
+implementing basic HTTP interaction but also redirects, websockets, et
+cetera. The :ref:`controllers` page lists all available controllers in
+the Zotonic core. 
+
+The `Webmachine documentation
+<http://wiki.basho.com/Webmachine-Demo.html>`_ itself is also very
+helpful for understanding controllers.
+
+
+
+.. _manual-controllers-webzmachine:
+
+Differences between Zotonic's and Basho's Webmachine
+----------------------------------------------------
+
+Zotonic's fork has been named ``webzmachine`` and lives in its
+separate repository at https://github.com/zotonic/webzmachine).
+
+The main differences with Basho's Webmachine are:
+
+* Pluggable dispatch handler
+* Support for the HTTP ``Upgrade:`` header
+* Optional caching of controller callbacks results
+* Dispatch handler can redirect requests
+* Use of process dictionary has been removed
+* ``webmachine_request`` is now a normal (not parametrized) module
+* Extra logging
+
+Alltogether, this gave a significant speed boost to Webmachine.
+
+In the specific case of Zotonic the difference was 5 milliseconds (or
+more) per request (on a 2GHz Core 2 Duo). Without these optimizations
+we were not able to use Webmachine.

doc/ref/controllers/index.rst

@@ -3,6 +3,10 @@
 Controllers
 ===========
 
+This is the full list of :term:`controllers <controller>` that are
+available in Zotonic. For more general information about controllers,
+see the :ref:`manual-controllers` manual.
+
 .. toctree::
    :maxdepth: 1
    :glob: