{"result":{"depiction_url":null,"edges":{"references":{"objects":[{"created":"2020-05-30T05:47:51Z","object_id":{"id":1279,"is_a":["text","documentation"],"name":"doc_glossary","title":"Glossary","uri":"https:\/\/zotonic.com\/id\/1279"},"seq":1000000},{"created":"2020-05-30T05:47:51Z","object_id":{"id":1296,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_base","title":"mod_base","uri":"https:\/\/zotonic.com\/id\/1296"},"seq":1000000},{"created":"2020-05-30T05:47:51Z","object_id":{"id":321,"is_a":["meta","category"],"name":"controller","title":"Controllers","uri":"https:\/\/test.zotonic.com\/id\/321"},"seq":1000000}],"predicate":{"id":332,"is_a":["meta","predicate"],"name":"references","title":{"_type":"trans","tr":{"en":"References"}},"uri":"https:\/\/zotonic.com\/id\/references"}}},"id":1540,"is_a":["text","documentation","developerguide"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1540"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_developerguide_controllers","page_url":{"en":"https:\/\/zotonic.com\/docs\/1540\/controllers","x-default":"https:\/\/zotonic.com\/docs\/1540\/controllers"},"preview_url":null,"resource":{"body":"
\n \n
\n\n

Controllers<\/span><\/a> are the Erlang modules which decide\nwhat happens when a browser requests a page. Zotonic looks at the\ndispatch rules<\/span><\/a> that match the requested URL,\nand if a dispatch rule matches, the controller that is named in the\ndispatch rule is used to handle the request.<\/p>\n

\n

Anatomy of a controller<\/h2>\n

Say we have the following dispatch rule, handling https:\/\/localhost\/example<\/span><\/code>:<\/p>\n

<\/span>{<\/span>example_url<\/span>,<\/span> [<\/span> "example"<\/span> ],<\/span> controller_example<\/span>,<\/span> []},<\/span>\n<\/pre><\/div>\n<\/div>\n
When hitting \/example<\/span><\/code>, the controller_example<\/span><\/code> controller will be\ninitialized and callback functions on the controller will be\ncalled, according to the HTTP protocol flow.<\/p>\n
Controllers are pretty self-documenting, thanks to the names of the\ncowmachine callback functions. For instance, when you define a\nfunction resource_exists\/1<\/span><\/code>, it will be called to decide if\nthe page should return a 404.<\/p>\n
The simplest controller to serve HTML:<\/p>\n
<\/span>-<\/span>module<\/span>(<\/span>controller_example<\/span>).<\/span>\n\n-<\/span>export<\/span>([<\/span> process<\/span>\/<\/span>4<\/span> ]).<\/span>\n\nprocess<\/span>(_<\/span>Method<\/span>,<\/span> _<\/span>AcceptedCT<\/span>,<\/span> _<\/span>ProvidedCT<\/span>,<\/span> Context<\/span>)<\/span> -><\/span>\n    {<\/span><<<\/span>"<h1>Hello<\/h1>"<\/span>>><\/span>,<\/span> Context<\/span>}.<\/span>\n<\/pre><\/div>\n<\/div>\n<\/div>\n
\n<\/a>
Rendering templates<\/h2>\n
To return the rendered output of a template file in the module’s\npriv\/templates<\/span><\/code> directory, use z_template:render_to_iolist\/3<\/span><\/code>:<\/p>\n
<\/span>-<\/span>module<\/span>(<\/span>controller_example<\/span>).<\/span>\n\n-<\/span>export<\/span>([<\/span> process<\/span>\/<\/span>4<\/span> ])<\/span>\n\nprocess<\/span>(_<\/span>Method<\/span>,<\/span> _<\/span>AcceptedCT<\/span>,<\/span> _<\/span>ProvidedCT<\/span>,<\/span> Context<\/span>)<\/span> -><\/span>\n    % foo and bam will be available as template variables in mytemplate.tpl.<\/span>\n    Vars<\/span> =<\/span> [<\/span>\n       {<\/span>foo<\/span>,<\/span> <<<\/span>"bar"<\/span>>><\/span>},<\/span>\n       {<\/span>bam<\/span>,<\/span> 1234<\/span>}<\/span>\n    ],<\/span>\n    z_template<\/span>:<\/span>render_to_iolist<\/span>(<\/span>"mytemplate.tpl"<\/span>,<\/span> Vars<\/span>,<\/span> Context<\/span>).<\/span>\n<\/pre><\/div>\n<\/div>\n
The Cowmachine documentation<\/a> is\nhelpful for understanding controllers.<\/p>\n<\/div>\n
\n<\/a>
Differences between Cowmachine and Basho’s Webmachine<\/h2>\n
Zotonic’s fork of Webmachine has been named cowmachine<\/span><\/code> and lives in its\nseparate repository at https:\/\/github.com\/zotonic\/cowmachine<\/a>).<\/p>\n
The main differences with Basho’s Webmachine are:<\/p>\n
If you need more examples, mod_base<\/span><\/a> contains many controllers,\nimplementing basic HTTP interaction but also redirects, websockets, et\ncetera. The Controllers<\/span><\/a> page lists all available controllers in\nthe Zotonic core.<\/p>\n