Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

doc: Add section about dispatch rule naming

  • Loading branch information...
commit 159bb21cdc8c698a0e934e9f1af79a5b50b93f8f 1 parent a026d27
@arjan arjan authored
Showing with 40 additions and 1 deletion.
  1. +40 −1 doc/manuals/dispatch.rst
View
41 doc/manuals/dispatch.rst
@@ -3,7 +3,8 @@
The URL dispatch system
=======================
-Dispatch rules map URLs to controllers, and vice versa.
+Dispatch rules map URLs to :term:`Controllers <Controller>`, and the
+other way around.
A dispatch rule contains a pattern that is matched against the `path`
of an incoming request URL. They are also used for the reverse action
@@ -64,6 +65,44 @@ Where the elements are:
3. the name of the controller
4. a property list with optional arguments to the resource module
+Dispatch rule naming
+....................
+
+Zotonic extends Basho's Webmachine by allowing (or actually,
+`requiring`) dispatch rules to be named. The name is the first element
+of the dispatch rule tuple, and consists of a simple atom. The
+``z_dispatcher:url_for`` function takes a name and creates the URL for
+it. This allows the developer to not hardcode the URLs everywhere, but
+use these symbolic names instead.
+
+Dispatch rule names do not have to be unique: if multiple rules with
+the same name exist, it will look at the first rule that matches the
+given name and the optional extra arguments that were given.
+
+Say I have these rules::
+
+ {rulename, ["foo", "bar"], controller_template, [{template, "foo.tpl"}]},
+ {rulename, ["foo", var], controller_template, [{template, "foo.tpl"}]},
+
+Then when I create a URL like this::
+
+ {% url rulename %}
+
+It will match the first rule (rendering the url ``/foo/bar``) because
+no arguments were given. However when I add an argument::
+
+ {% url rulename var=1 %}
+
+It will render the URL ``/foo/1``, matching the second dispatch rule
+and adding the argument in the creation of the URL.
+
+Note that any `extra` arguments that are given, are added as query-string parameters::
+
+ {% url rulename var=1 x="hello" %}
+
+Will result in the URL ``/foo/1?x=hello``.
+
+
URL match pattern
.................
Please sign in to comment.
Something went wrong with that request. Please try again.