Developer guide
Browse by topic
Discover Developer guide
Explore related documentation through its most useful keyword groups.
166 items
Grouped by Domain
Development and debugging
54 itemsBuilding inspecting testing and diagnosing Zotonic applications and modules.
Explore this clusterSite management
34 itemsCreating configuring updating starting and stopping Zotonic sites.
- addsite: Create a site application from a skeleton
- Application startup and per-site module activation
- A site does not start
Configuration
26 itemsDefining site module runtime and service settings.
- A site does not start
- Change a runtime setting deliberately
- config: Display configuration resolved from files
Module management
6 itemsInstalling activating configuring upgrading and removing Zotonic modules.
- A module is discovered but not active
- A module is missing from the admin
- Application startup and per-site module activation
Logging and monitoring
6 itemsRecording and observing events errors state health and performance.
Explore this clusterRouting and redirects
6 itemsMapping incoming URLs to controllers resources or redirect destinations.
- Add your first dynamic page
- A URL reaches the wrong page
- dispatch: Inspect dispatch rules or trace a URL
Media management
5 itemsManaging files and media resources throughout their lifecycle.
- An uploaded image does not display
- Display images with mediaclasses
- Display images with mediaclasses
Content modeling
4 itemsDefining content types properties relationships and constraints.
- Create your first site
- Install initial content with a datamodel
- Model content with categories and predicates
Backup and restore
4 itemsPreserving and recovering site data media and configuration.
- Back up and restore site data
- backup: List, create, or restore backups
- decrypt: Decrypt a local encrypted backup file
Other
43 itemsDocumentation not covered by the other keyword groups in this split.
- Add a database query when models are not enough
- Add a filter or rendering component
- Add an HTTP controller
All Developer guide
Add a database query when models are not enough
Prefer Zotonic models for resources and edges. Use z_db for application tables or queries that the model APIs do not cover.
Add a filter or rendering component
Use a filter for a small transformation of an input value. Keep missing and unexpected values predictable, and escape output at the point where it becomes HTML.
Add an HTTP controller
Use controller_template when a dispatch rule only needs to render a template. Write a custom controller when the endpoint needs additional request processing…
addsite: Create a site application from a skeleton
Create a site application from a skeleton.
Add your first dynamic page
Use an existing controller and a template for a simple dynamic page.
A model returns an error or no value
Check the requested path and compare its binary segments with the model callback patterns. Confirm that the callback returns the unused path in the required…
A module is discovered but not active
Open module management for the correct site. Check whether the module is disabled, waiting for a dependency, or failing during startup.
A module is missing from the admin
Check that the module is an Erlang application in a discovered project directory. Confirm the application name, .app.src, main mod_... module, and successful…
Anatomy of a reusable module
A reusable module normally lives in apps_user/zotonic_mod_garden and contains:
Anatomy of a site application
A typical site contains the following directories. Create only the extension directories you actually need.
An uploaded image does not display
Check whether the resource has an original file and whether its media information describes that file correctly. Then inspect the preview request in the…
A page is slow
Measure one representative request and identify whether time is spent in the browser, network, or server. Compare an initial request with a repeated request to…
Application and module names
Use distinct, consistent names so code and assets can be found without ambiguity.
Application startup and per-site module activation
OTP application startup concerns the application and its processes. Zotonic module activation concerns the feature within an individual site.
A saved change does not appear
Check each stage in order: the edited file, build output, loaded application, active module, selected template, and browser response.
A site does not start
Run bin/zotonic status to distinguish an unavailable node from a stopped or failing site. Inspect the relevant startup log before repeatedly restarting it.
A site does not start
Run bin/zotonic status to distinguish an unavailable node from a stopped or failing site. Inspect the relevant startup log before repeatedly restarting it.
A URL reaches the wrong page
Confirm the hostname, site, and path from the actual request. Use the dispatch trace to see the selected rule and any rewritten path.
Automatic recompilation and file watching
Zotonic's file handler watches source changes when a supported watcher is available. Erlang, templates, dispatch files, and assets have different handlers.
Back up and restore site data
For a site with backup support enabled:
backup: List, create, or restore backups
List, create, or restore backups.
Build and serve frontend assets
Keep source files such as SCSS in priv/lib-src and compiled assets in priv/lib. Use an app-level Makefile that delegates asset work to the source directory's…
Build and serve frontend assets
Keep source files such as SCSS in priv/lib-src and compiled assets in priv/lib. Use an app-level Makefile that delegates asset work to the source directory's…
Build and start Zotonic
Compile Zotonic, start it, check the status page, and continue to your first site.
Cache a template fragment
First measure the work performed by the fragment. Cache a fragment only when you know which inputs and data changes affect its output.
Cache selected public assets with Varnish
Start with a narrow VCL 4 policy and preserve authenticated responses.
Change a runtime setting deliberately
Use bin/zotonic setconfig only for a global setting that supports a runtime change. The command changes the running configuration and does not save the value…
Change a template and see the result
Make a small visible change before building a larger feature.
Check a rendered template
Render the changed page with realistic content. Include missing optional fields, a long title, several list items, and a second language when applicable.
Check template references
Open Cross-reference check of templates in the Development page and run the check. Read each reported reference with the active module set in mind.
Choose a development tool
Start with the symptom and use the smallest tool that explains it.
Choose a model, controller, observer, or component
Choose a model, controller, observer, or component.
Choose checks for a change
Choose checks for a change.
Choose checks for a change
Choose checks for a change.
chrome: Open a site in Chrome
Open a site in Chrome.
chromium: Open a site in Chromium
Open a site in Chromium.
Compile changed code and load modules
Use make for the normal project build. On a running development node, the CLI also provides focused operations:
compilefile: Recompile one Erlang source file
Recompile one Erlang source file.
compile: Request recompilation on the running node
Request recompilation on the running node.
config: Display configuration resolved from files
Display configuration resolved from files.
configfiles: List selected global configuration files
List selected global configuration files.
configtest: Check whether global configuration files can be read
Check whether global configuration files can be read.
Configure hostnames and HTTPS
Align DNS, site selection, and certificate termination.
Configure outbound email and verify delivery
Set a relay at the correct scope and test a real site message.
Configure persistent file storage
Identify where the site's archive files, generated previews, backups, and security files are stored. These have different retention and recovery needs.
connectdb: Test the configured PostgreSQL connection
Test the configured PostgreSQL connection.
Connect resources and preserve order
An edge connects a subject resource to an object resource through a predicate. Use model#edge to inspect and manage these connections.
Connect to the running Erlang shell
From the checkout root:
Contribute a Zotonic change
Build the checkout, verify the change, and send a focused pull request.
Create a page layout
Use an existing site base template as your starting point. Put shared document structure in the base and page-specific markup in blocks.
Create a page layout
Use an existing site base template as your starting point. Put shared document structure in the base and page-specific markup in blocks.
Create a reusable module
Create apps_user/zotonic_mod_garden with the following files. This example adds a discoverable module without starting an extra process.
createdb: Prepare a site database and schema
Prepare a site database and schema.
Create your first site
Create the garden blog, open it in your browser, and sign in to its admin.
Create your first site
Create the garden blog, open it in your browser, and sign in to its admin.
Create your first site
Create the garden blog, open it in your browser, and sign in to its admin.
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…
debug: Start Zotonic in the foreground with an Erlang shell
Start Zotonic in the foreground with an Erlang shell.
decrypt: Decrypt a local encrypted backup file
Decrypt a local encrypted backup file.
Dependencies, capabilities, and module priority
The main site or module can declare:
Deploy a repeatable release
Record the code revision, build steps, configuration changes, and schema changes for the release. Build and test the same revision in an acceptance environment…
Developer guide
Build, inspect, and maintain Zotonic sites and modules.
Diagnose a failed browser interaction
Reproduce one action with the browser console and network panel open. Check for a JavaScript error before the request, a failed request, or a successful…
dispatch: Inspect dispatch rules or trace a URL
Inspect dispatch rules or trace a URL.
Display images with mediaclasses
Define reusable image sizes in priv/templates/mediaclass.config and use them in image tags. For example, a local mediaclass can constrain an image's width:
Display images with mediaclasses
Define reusable image sizes in priv/templates/mediaclass.config and use them in image tags. For example, a local mediaclass can constrain an image's width:
Distinguish stale cache data from stale code
First check which file is selected and whether the changed code compiled. Then repeat the request with the relevant cache disabled or flushed.
Enable the Development module
Sign in to the local site's admin as an administrator. Open the module management page, find Development (mod_development), and activate it if necessary.
Erlang applications, Zotonic modules, and sites
These terms describe different parts of the system.
etop: Inspect active Erlang processes
Inspect active Erlang processes.
Expose an operation through an API
Start from the site's existing model API or controller patterns. Specify the method, input fields, response shape, and errors before connecting a browser or…
Expose data through a model
Create src/models/m_garden.erl in the Garden module. This complete example exposes a public greeting:
Find registered observers
Open Show an overview of all observers from the Development page. Find the notification and inspect the registered callbacks and their order.
Find the configuration layer to change
Distinguish global Zotonic configuration, Erlang runtime configuration, site configuration files, and module settings stored for a site. Similar setting names…
Find the status site and your site's admin
The status site manages the running Zotonic installation. A site's /admin manages that site's content and enabled modules. They have different scopes and can…
Find the template used by a page
Enable module#mod_development and open its template tools in the admin. Search for the template name and inspect the selected file and alternatives.
flush: Flush site caches
Flush site caches.
Follow a request to its template
Start with the URL that gives an unexpected result. Check its hostname: Zotonic uses it to select a site before matching the site's dispatch rules.
Follow a request to its template
Start with the URL that gives an unexpected result. Check its hostname: Zotonic uses it to select a site before matching the site's dispatch rules.
Get Zotonic
Choose a release or a development checkout and follow the installation guide.
Handle a browser event with a wire
Use scomp#wire to connect a browser event to an action or a server postback. Give the target element a stable ID within the rendered page.
Handle a browser event with a wire
Use scomp#wire to connect a browser event to an action or a server postback. Give the target element a stable ID within the rendered page.
How Zotonic finds templates, dispatch rules, and assets
Zotonic indexes resources from the site's active modules. A file existing on disk is not enough: its application must be discoverable, and its module must…
Inspect global and site configuration
Use the command suited to the question:
Inspect logs and running processes
Use bin/zotonic logtail for the configured console log, or select error or crash when those files are available. The command prints the last 500 lines and…
Inspect template dependencies
Open Dependency graph of all available templates from the Development page. Use the graph to understand inheritance and include relationships before changing a…
Installation and deployment
Prepare an environment and deploy a release with a recovery plan.
Install initial content with a datamodel
Use a datamodel for application-owned categories, predicates, resources, and relationships that must exist when a module is installed.
Install on macOS or Linux
Install the native tools, prepare PostgreSQL, and build a local checkout.
Install with Docker or Podman
Build and run Zotonic with its development containers, then create a site.
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.
Keep development and production settings distinct
Keep development and production settings distinct.
Keep development and production settings distinct
Keep development and production settings distinct.
Keep permission checks at the boundary
Use the request context when checking access to data and actions. A hidden button is not an authorization check: callers can invoke a model or endpoint…
Link to resources and dispatch routes
Use a resource's page URL when linking to content. This lets Zotonic account for its path and language.
load: Load changed BEAM files
Load changed BEAM files.
logtail: Print recent lines from a configured log file
Print recent lines from a configured log file.
Model content with categories and predicates
Use a category to describe what a resource is, such as an article or event. Use a predicate to describe a relationship between two resources, such as an author…
Move content between sites
Export structured resource data and record how source resources map to destination resources. Match stable names or URIs deliberately; do not assume that…
open: Open the site URL in a browser
Open the site URL in a browser.