Developer guide

Developer Guide

Developer guide

Introduction

This is the Zotonic Developer Guide. It takes you through all aspects of Zotonic so you can start building your own sites as quickly as possible.

Developer guide

Getting Started

You have three options for running Zotonic: to get started quickly, start our Zotonic container. You can also use Nix or manually install the dependencies.

Developer guide

Docker

We offer the Docker image zotonic/zotonic-dev which contains build tools and Erlang.

Developer guide

Directory structure

Zotonic is a set of regular OTP applications. These can be found in the repository’s apps/ directory:

Developer guide

Sites

Zotonic has the capability of serving more than one site at a time. You can have multiple sites enabled, each with its own set of templates, database and…

Developer guide

The Status site

The Zotonic “status” site is the first thing you see once you have installed Zotonic, or if you do not have any sites configured yet.

The Status site

Developer guide

Controllers

Controllers are the Erlang modules which decide what happens when a browser requests a page. Zotonic looks at the dispatch rules that match the requested URL

Developer guide

Dispatch rules

Dispatch rules route incoming requests to controllers.

Developer guide

Resources

Resources are Zotonic’s main data unit. You may want to familiarise yourself with the Zotonic data model in the User Guide.

Developer guide

Templates

Templates are text files marked up using the Zotonic template language. Zotonic interprets that mark-up to dynamically generate HTML pages. Zotonic’s template…

Developer guide

CSS classes used in templates

If you are building a website then you might want to use the standard dialogs, overlays, authentication and other parts of Zotonic. To make those look like…

Developer guide

Media

Resources can have media resources attached to them. Resources and their media (images, video and audio) are connected through ‘depiction’ edges. Additionally

Developer guide

Icons

Including Zotonic icons CSS Add the CSS file to your template:

Developer guide

Forms and validation

You should validate all input data entered in forms. In Zotonic you create forms by writing plain HTML. You can attach one or more validators to each input…

Developer guide

Search

Using the query search API you can retrieve lists of resources in various ways. In your templates, you do so through the search model:

Developer guide

Translation

Many sites need to support content and templates in multiple languages. Luckily, Zotonic is completely multilingual, out of the box. mod_translation does all…

Developer guide

Wires

Wires are the older way to code actions and client/server interaction. It is now advised to use MQTT topics with mod_mqtt instead.

Developer guide

Access control

Access control is about defining who is allowed to access certain resources. It takes two steps:

Developer guide

Modules

Modules are the building blocks of Zotonic. They add functionality to your Zotonic website such as:

Developer guide

Notifications

At different moments in the lifecycle of the web request, Zotonic sends notifications. By observing these notifications you can override Zotonic’s behaviour.

Developer guide

Browser/server interaction

There are multiple ways to set up interaction between server-side Zotonic code and client-side JavaScript.

Developer guide

E-mail handling

Any Zotonic system is capable of sending and receiving e-mail messages over SMTP.

Developer guide

Command-line shell

The Zotonic shell gives you access to a running Zotonic instance with its code and data.

Developer guide

Logging

Zotonic uses Logger for logging. Logger metadata is automatically set by Zotonic in the controller functions.

Developer guide

Testing sites

It is possible to create end-to-end integration tests for Zotonic websites. Tests like these are called sitetests . They run within the Zotonic shell

Developer guide

Deployment

So you have built your Zotonic site, and now you want to show it to the world. This page tells you how to configure your zotonic environment so that it is…

Developer guide

Troubleshooting

Installation Zotonic won’t start and shows errors when running zotonic debug Check your site’s database configuration.

Developer guide

Contributing to Zotonic

We encourage contributions to Zotonic from the community! This chapter describes how you can help improve Zotonic.

Documentation

Release Notes

Every time a Zotonic release is made, we create a document which lists the most important changes. This page contains links to the release notes for each…

Developer guide

Upgrade notes

These notes list the most important changes between Zotonic versions. Please read these notes carefully when upgrading to a new major Zotonic version.