Fork me on GitHub

User's Guide

An article by Gaspard Bucher

The common way to interact with zena content.

If logged in with enough permissions, you will see edit icons next to the title of the webpages:

zazen_fr

An editable page in zena (pdf in french)

Trying out zena is very simple. Just request a wiki account.
A little help, for example, by fixing typos, adding screenshots, rearranging, etc. in this documentation is always welcome.

When adding content, please mark the parts you are unsure about and that need to be checked with three question marks (”???”).

This manual should answer questions such as:

You will be introduced to the zena fundamentals and the day to day ways to interact with zena content.

What to Expect

After reading this, you should find your way into zena and understand how to:

  • Create pages
  • Organize the information on your site.
  • Include shared content into a page.
  • Include dynamically generated and editable content into pages.
  • Create additional users and assign permissions.

What not to expect

This document assumes that you can log into a zena website. For example, into our Wiki. It does not explain how to install zena on a local machine or webserver. If you don’t have a login already, simply request one, or refer to the Getting Started guide for install instructions.

Webmasters who want to alter and extend the information handling, system administrators who want to maintain the servers to run smoothly, webdesigners who want to create templates for a site, and programmers who want to modify or create functionality, will all find what they need in The Guide to Zena.

Basics

The concepts used.

Term Meaning
site A (web)site is identified by its domain name address and can be configured with different options (password restricted access, etc). A single zena installation can host multiple sites.
(In the past, the group that contains all the users that are “logged-in” to a site (i.e. everyone except anonymous users) was called the “site” group as well.)
node In the zena Data Model, all content (pages, documents, images, etc.) is a sub-class of the main class ‘Node’. Nodes are the units in which information is organized. The following diagram shows the inheritance diagram for the base classes derived from the Node class: classes In addition to this class inheritence, the nodes:
  • Are organized in a parent/child hierarchy. The content (information) of a site consists of an index node with child nodes of different classes.
  • Can be linked through html links (from within their content).
  • Can be linked by user defined relations.
relation Relations can be defined to organize nodes by linking them as having the specified relation. Each ralation link has an additional status and comment field.
rendering The node content (its properties) gets rendered (e.g. to html) according to the skin and template assigned with the site, node inheritance, and node class of the requested node.
page Visitors experience your site primarily via nodes of the “Page” class.
  • Pages below the home node become part of the menu (in the default template),
  • can be made accesible though a title based url (base_url),
  • should have short names or “slug” feature for menu and url.
  • Page subclasses litter common Page class selection.
  • sections and projects Pages that define a new context for its child nodes (section/project ID). Both behave the same without any hierarchy. For example, use section for large parts on a site (intranet, public) and project as finer categories. However, you may always use the one that is available given that the context of the other needs to be kept. Section and Project are really independent but very powerful beasts. See Data Model.
    skin A special section that contains template document nodes (with attached assets like stylesheets and graphics) which define the design and layout for pages.
    note A basic chunk of content (node) that may be included from other nodes.
    post An note with a relation to time (has a date property), suitable for articles in weblogs or news pages.
    comment A unit of content created by users in response to some other node.
    documents Text or binary (image) files.
    template html with added zafu that defines the basic layout of pages
    template part includable part of a template (e.g. div ID or name= attribute)
    users and groups Default groups: public(read), site(logged in, write), editor(publish), admin(manage site)
    zafu The templating language. Unlike allowing cms-users to edit embedded ruby (erb) templates (code that could modify the whole site or even server), zafu doesn’t risk the security of the website. Besides, it provides amazing features to create dynamic and interactive websites with just simple templating code in a straight forward way (i.e. simple definition use of objects (include the “virtual” classes that that can be defined in the zena admin interface) without requiring database schema changes or migrations.) and the ease and power or ruby—less and SQLiss.
    zazen The markup language used for content formatting (based on “textile”). Easier to edit and safer then letting users specify HTML directly, superior for separating content and central formatting, and more precise then the “markdown” language.

    Daily Tasks

    Logging in

    After you logging in, different type of edit buttons will become available on the pages (depending on your access rights). They may only be visible when you move the mouse cursor to where the buttons are placed (usually before or after titles or list items).

    Editing content

    The templates used to render a page determine the areas of the page that are editable. Clicking on the editor icon that appears next to editable content (on hovering over it with the mouse) opens an editor window, and the webpage is turned into an immediate preview of updates made in the editor.

    The editor allows to enter text with additional zazen markup (extended textile) and to upload additional documents to the edited node. The zazen markup allows adding special formatting like headers and lists, and placing images or links.

    (For more details see: writing text)

    Adding new content

    To add new pages, notes, posts, etc. navigate to the section or page to which you want to add an item, and click on the add button (a plus sign by default) next to the type of things of which you want to add one. Then complete the appearing form.

    To add a new page, for example, there is usually an add button next to the menu or in the sitemap.

    Adding images and files to pages

    There are two steps to adding an image or a file to a page. First you need to upload the image or file. Then you can reference or place the image from within your text.

    Uploading files

    Click on the “add document” button (available on the page or from within the editor window), to attach a file to a node . After the upload completed, the ID number of the new document node will be shown. To upload multiple files at once, throw them all in a .zip file and use the “import” tab to upload the archive.

    To upload a new version of an existing file, open the edit window of the attachment’s html page, and use the “image” or “document” tab to submit a new file version. As with any nodes in zena, you can also have different versions of files visible publicly, depending on languages, to editors etc.

    Placing images

    Enter an image tag using the !<Image-ID>! notation and the preview in the browser will display the image as it will appear on the page. To have zena search for the Image-ID you can also use zip shortcuts in zazen.

    (For more details see: zazen)

    Placing a link to a document

    Enter a link using the "text":<target> notation.

    (For more details see: zazen)

    Reverting changes

    Mistakes happen. Sometimes you make a change, and you don’t like how it looks, or you just want to go back to last week’s version.

    To see what older versions looked like, open the “drive” properties window and click on a (“replaced”) status icon in the list of versions. (Recommended Tip: Open the version in a new tab in your browser, by Ctrl-Click on PC, or Command-Clicking on Mac. This will let you compare several versions side by side.)

    To roll a page back to an earlier version, click on the publish button of the desired version.

    Deleting content

    If all versions of a node are deleted, the node itself gets deleted with the last remaining version.

    Deleting a node will delete all its decendant nodes (notes, posts, comments, attached documents, sub-pages,...) and links ???

    Hiding pages from the menu

    If a page should never be shown as a subpage or in a menu (that lists pages), you can simply change its class from “Page” to “Note”.

    Note that even if notes do not appear in menus that list only child pages, publicly readable notes will still be accessible to the public through their URLs. You may thus link to them from anywhere.

    A simple way to have a page show up in the menu conditionally, is to adjust its read permissions. A non-public page will not be listed in the public menu.

    Reordering Nodes

    When nodes are created, they are added as a new child to their parent node. Child nodes can be reordered in the “drive” tab of the “drive” window (accessible through the wrench icon) by dragging and dropping. To move an item in the list of childs, click-hold the mouse on it, and drag it where you want it to be. To move a node into another section change the parent ID that can be set in the same tab.

    Organizational Tasks

    Setting up password restrictions

    Basic access is controlled by user groups and node permissions. By default, each node inherits its access permissions from its parents. Additionally, access control lists (ACLs) can be used to grant more specific access rights.

    (For more details see: secure (who can do what))

    Creating a group

    The first step is to set up the “member” group that should be allowed to see a page or section. An administrator can manage the groups in its his origin’s settings (click on your login name). Select ‘Groups’ from the left menu and add for example a group “member”.

    Adding users

    The next step is to add users to the “member” group. In the User-Administration (click on your login name) select Groups, ...

    Adjust the access permissions of a (new) section

    The last step is to adjust the permissions. Visit or create the node that you want to have restricted permissions and open its “drive” window (wrench icon next to the title). Then select the “drive” tab and set the readers permission to the “members” groups you created in the first step.

    Setting up an author-editor publishing workflow

    When the number of contributors grows, it may be necessary to restrict who has rights to publish new content and versions. One option is to allow multiple authors to contribute and edit content, but require one or more `editors’ for review or censorship in order to publish the content. There are several aspects involved to make such work flow nicely:

    • Rights – Allow writing/publishing.
      • Create an “author” group and give it write permissions to the content.
      • Add users (or move users from the “editor” group) into the “author” group.
      • Disable the auto_publish option for the site.
    • Tasking – Assign nodes to users.???
    • Notification – Let users know that they have new content to review.???

    Tasks???

    All of the open tasks that are assigned to a user will appear on that user’s page.???
    Users can click on the name of the page to review it, and either complete the task, or assign it to someone else.???

    Adding dynamic content to a page

    Zafu Template Parts

    For many sites, a good amount of the content will find its way onto the pages by editing (zazen) text and including and linking uploaded documents in it.

    However, zafu templates allow to render dynamic content on your pages, that is automatically updated whenever the presented data changes. Zafu template parts can also be used to render content generated by zena extension bricks, other apps ???
    , and from other websites.???

    Zafu template parts can even render forms, drag and drop interfaces, and editable tables (grids) that allow the creation and modification of content, nodes, links, and properties.

    Basic examples for creating dynamic content with zafu can be found in the default templates. The index page for example shows the content of the latest posts that have been made (child nodes of type “post”) in descending order.

    The following is an example that renders all related nodes of the current context, by reusing the part named “related” from the default “Node” template, but without the part that renders the (sub)pages.

    <r:include template='Node' part='related'>
      <!-- but replace its "pages" part with an empty part: -->
      <r:with part='pages'/>
    </r:include>
    

    For more examples look at the default template and Library of Zafu Template Parts.

    Including dynamic content into (zazen) page content

    The content of a grid attribute, for example, can be rendered inside a zazen text by writing [grid]<attribute with the json data for the grid>[/grid].
    Are there other ways to include zafu/rubyless code parts from within the content???
    Or is it required to edit the zafu template???

    Now, to get the real feeling for zena, have a look at the Tutorials, if you don’t know them already, and check out the rest of The Guide to Zena.