Fork me on GitHub


An article by Gaspard Bucher

Relations let you create links between your objects.

You can define new relations that your objects can have. Then use these relations to create links.

For example, if you are creating a network of people, you might want to create relations such as “friend”, “best friend”, “hero”, “mother”, “husband”, and so on.

You define these relations using the admin link “manage relations” which you access by clicking on your name when logged in (only if you have admin rights).

relations in zenadmin

Example of the relations defined for

When setting up a relation, you define whether it is a “many-to-many”, “many-to-one”, “one-to-many” or “one-to-one” relationship. In the image above, the “one” is shown as a target, “many” as a list of files.

Build-in drive popup

You can create and edit links (relation instances) in the “drive” popup () under relations.

links definition example

Example of links defined for a node.

using relations

Once you have some people with links between them, you can use these relations in your zafu templates.

List all the friends of a person:

<r:friends do='each' join=', ' do='link'/>

List your best-friend’s favorites:

<r:best_friend>My best friend's favorites : <r:favorites do='each' join=', ' do='link'/></r:best_friend>.

Look at zafu context for more details on how to use zafu with relations.

Creating and deleting links in zafu templates

Links can be created with forms by saving the target IDs (e.g. “10,44”) to a pseudo _ids attribute named as the relation (e.g. “friend_ids”).

When a node context is loaded through a relation query, the “link_id” is part of the context. A <r:unlink/> can be used to render a button to delete the link.

relation group

In order to ease relation management and automatic inspection/display, you can set a “group” field on the relation. See VirtualClass for an example.

link status, comment and date

You can set/read some additional fields of a link: “status” (an integer) and “comment” (a string limited to 60 characters). To set these values, you can use the drive popup or use the _status and _comment pseudo attributes in forms (e.g. for a link called “wife”: “wife_status” and “wife_comment”).

To read the link values, load (enter the context of) the linked node(s) and use the l_ syntax:

<ul do='tasks where l_status < 10'>
  <li do='each'>
    <h3 do='[name]'/>
    <p>status: <r:show attr='l_status'/> <i do='[l_comment]'/></p>

And there is also the link’s date: l_date


  1. leave a comment