Zotonic Release 0.32.0 Sep 04, 2017 Contents 1 User Guide 3 1.1 User Guide..............................................3 2 Developer Guide 7 2.1 Developer Guide...........................................7 3 Cookbook 197 3.1 Cookbooks.............................................. 197 4 Best practices 269 4.1 Best Practices............................................. 269 5 Reference 271 5.1 Reference............................................... 271 6 Indices and tables 501 6.1 Glossary............................................... 501 i ii Zotonic, Release 0.32.0 Welcome to the Zotonic documentation! This describes Zotonic 0.32, last updated Sep 04, 2017. The latest docs are also available in a PDF version. Contents 1 Zotonic, Release 0.32.0 2 Contents CHAPTER 1 User Guide An non-technical introduction to the Zotonic CMS for end users. User Guide Welcome to the Zotonic User Guide. This guide is a non-technical introduction to Zotonic. Table of contents CMS Zotonic is a Content Management System (CMS). Todo extend CMS introduction The Zotonic data model Zotonic’s data model can be seen as a pragmatic implementation of the Semantic Web: a mixture between a traditional database and a triple store. The data model has two main concepts: the resource and the edge. Resources, which are often called pages in the admin, are the main data unit: they have properties like title, summary, body text; and importantly, they belong to a certain category. Edges are nothing more than connections between two resources. Each edge is labeled, with a so-called predicate. This manual describes the data model and its related database table in depth. 3 Zotonic, Release 0.32.0 The data model by example Take the example data on the right. It shows resources, connected to each other by edges. The rectangular blocks denote the resources, the arrow between them denote the edges. It shows the domain model of a basic blog-like structure: article resources which are written by persons and articles being tagged with keywords. The edge between Alice and cooking for dummies is labelled author: indicating that Alice wrote that article. Note that these edges have a direction. When reasoning about edges, it is the easiest to think of them in terms of grammar: Subject - verb - object. In the case of Alice: • Cooking for dummies is authored by Alice; • Cooking for dummies has the keyword Cooking; or more general: • subject predicate object. In Zotonic, the terms subject and object (shortened as s and o) are used in the templates, allowing you to traverse the edges between resources: {{ m.rsc[id].o.author[1].title }} 4 Chapter 1. User Guide Zotonic, Release 0.32.0 Returns the name of the first author of the article with the given id, by traversing to the first author object edge of the given id. See the m_rsc (page 426) model for more details on this. Pages Pages are the main building block of Zotonic’s data model (page 3). For simplicity of communication, a resource is often referred to as a page. Every resource usually has its own page on the web site. By default, each page has the following properties. id Unique number that identifies the resource and can be used for referring to the resource title Main title of the page summary Short, plain-text, summary short title Short version of the title that is used in navigation and other places where an abbreviated title is shown published Only published pages are visible to the general public publication Date at which the page will be published and start publication Data at which the page will be unpublished end name Alternative for id: used to uniquely identify the resource page path The page’s URL on the site. Defaults to page/{id}/{title} See also: resources (page 16) in the Developer Guide Categories Each page belongs to one category. The category a page is in determines how it is displayed. Edges An edge is a labeled connection between two resources. The edge table defines these relations between resources. It does this by adding a directed edge from one rsc record (subject) to another (object). It also adds a reference to the predicate: the label of the edge. In the admin, edges are represented in the “Page connections” sidebar panel, of the edit page of the subject: the resource where the edges originate. By convention, edges are said to belong to their subject. This is to simplify the access control: if you are allowed to edit the resource, you’re also allowed to edit its outgoing edges (“Page connections” in the admin), creating connections to other resources. See also: m_edge (page 417) Predicates Edges have a label: like in The data model by example (page 4), author is a predicate of an edge which denotes that a certain article was written by a certain person Just like categories, these predicates are themselves also resources: allowing you to specify metadata, give them a meaningful title, et cetera. Each predicate has a list of valid subject categories and valid object categories (stored in the predicate_category table). This is used to filter the list of predicates in the admin edit page, and also to filter the list of found potential objects when making a connection. On their edit page in the admin interface, you can edit the list of valid subject and object categories for a predicate. See also: 1.1. User Guide 5 Zotonic, Release 0.32.0 m_predicate (page 424) Further reading • Zotonic’s defaults resources and categories: the domain model (page 6). Domain model By default, Zotonic comes with a set of categories and predicates that makes sense for typical websites. You can extend the built-in domain model by adding your own categories and predicates. Todo document categories, predicates and resources User management Create new users In the admin, under ‘Auth’ > ‘Users’ you can find a list of all users. Use the ‘Make a new user’ button to create a new user with a username/password identity. Note: This requires mod_admin_identity (page 281) to be enabled. Issues and features If you encounter any issues in using Zotonic, or have ideas for new features, please let us know at the Zotonic issue tracker. You need to have a free GitHub account to do so. Before submitting a new issue, please search the issues list to see if the issue bug has already been reported. Every first Monday of the month a new version of Zotonic is released (page 76). Todo Add more chapters to have a complete run-through of all user-facing aspects of Zotonic. See http://zotonic.com/support for getting help and support. See also: if you’re a developer who’s already familiar with Zotonic, you may want to read the Developer Guide (page 7) instead. 6 Chapter 1. User Guide CHAPTER 2 Developer Guide The handbook for all Zotonic developers. It guides you through all aspects of the framework. 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. If you are an end user rather than developer, you may want to read the User Guide instead. An overview of Zotonic Zotonic is a complete stack for building advanced websites quickly. It consists of: 1. a content management system (CMS) 2. a web framework 3. a web server. You can rapidly develop CMS-based sites on top of Zotonic. If you need more flexibility, you can customise all aspects of Zotonic. The included web server means can start working with Zotonic right away, without the need for installing Apache or Nginx separately. Zotonic is structured into modules. Each module offers a specific piece of functionality; the CMS is itself a module. There are modules for access control, social media integration, TLS, video embeds and much more. Central to Zotonic is its uniquely flexible data model. Installation To get Zotonic running, you first need to install it. This chapter describes how to install Zotonic manually. Alter- natively, you can run Zotonic from one of the Docker images (page 9). 7 Zotonic, Release 0.32.0 Preparation First prepare your system for running Zotonic. Zotonic needs: • Erlang 18 or higher • PostgreSQL 8.4 or higher • ImageMagick 6.5 or higher for image resizing • Git for pulling in external dependencies See also: a more extensive discussion of all requirements (page 488) On Linux For instance on Debian you can install the dependencies by running: $ sudo apt-get install build-essential git erlang imagemagick postgresql On OS X Install Homebrew, then run: $ brew install erlang git imagemagick postgresql On Windows Currently, Zotonic is not officially supported on the Windows platform. However, the main dependencies Erlang, PostgreSQL and ImageMagick do work on Windows, so, if you’re adventurous, it should be possible to get it running. We have included user-contributed start.cmd and build.cmd batch-scripts which used to work on Windows, but have not been kept up-to-date with recent changes. Expect some major tweaking to get this back on track. Getting Zotonic 1. Download the latest Zotonic release ZIP file from the GitHub releases page. For instance: $ wget https://github.com/zotonic/zotonic/archive/0.32.0.zip Then unzip the file and rename the directory: $ unzip 0.32.0.zip $ mv zotonic-0.32.0 zotonic Alternatively, clone the latest development version using Git: $ git clone https://github.com/zotonic/zotonic.git 2. You then need to compile the Zotonic sources: $ cd zotonic $ make 3. Then start Zotonic in debug mode: 8 Chapter 2. Developer Guide Zotonic, Release 0.32.0 $ bin/zotonic debug 4. Now point your browser to: http://localhost:8000/.