A traditional Cadre entry consists of a single row in the entries table. This row has a number of properties, including the obvious title, subtitle, and body fields, but the correct interpretation of some of the other fields may be less obvious. The purpose of this article is to clarify their meaning and usage.
- $_id: The unique entry identification number of the article, automatically generated at creation by an automatically-incrementing counter. The first article is 1.
- $_parent: The entry ID of the page which is this article's parent. This article will appear in response to children() and index() queries targeted at the parent article. This may be 0, to indicate that the entry should have no parent. An article's permissions may explicitly define what the owner of the parent entry is allowed to do to it.
- $_group: The group ID of the users who have special access to this entry. This may be 0, to indicate that the group section of the permissions field should not apply to any users. Under normal circumstances, a user may only add an article to a group to which he or she belongs.
- $_author: The user ID of the entry's owner. Authors also receive a special set of permissions. This can be 0, indicating that no user is so privileged.
- $_template: The entry ID of the page that will be used to format this article for display. If 0, a built-in template will be used instead.
- $_date: The timestamp when the entry was last modified. Overwritten when an article edits itself.
- $_executable: A number from 0 to 4 describing the behaviour of Octavia script tags within the article:
- 0: Normal. The page is not executable at all.
- 1: As owner. Replace the page's view mode with script execution, ignoring the template's description of the view mode. The page can modify other pages with its author's permission level, and will create new pages with its author's ownership by default.
- 2: As viewer. As #1, but with the viewer's permission level. This is commonly used for administrative pages.
- 3: Template. Viewing the page under any mode will function normally (template authors may wish to write their code using an appropriate environment, such as a text-only template) but the page can also be used by users with activate/append privileges as the template for their own articles.
- 4: Function. The page can be called, by title, as a function from other pages. See the section on defining functions.
- $_permissions: A string of 20 characters, consisting of the word 'cadre' repeated four times, or hyphens, in each place. It is structured as follows:
cadrecadrecadrecadre
- The first five letters represent the permissions of the author.
- The second five represent the permissions of the parent article's author.
- The third represent the permissions of the group.
- The final quintet represents the permissions of all other users.
This is comparable to Unix filesystem permissions, but more granular, particularly in that a page can refuse to allow a parent to modify it.
The quintet elements are defined as follows:
- "c" means the page can be commented on. Child pages may be created.
- "a" means that the page can be activated (if it is a script), used (if it is a template) or appended to (if it is text-only).
- "d" means that the page can be directed. It may be deleted or have any properties changed other than its $_body.
- "r" means that the page can be read.
- "e" means that the page's $_body can be edited.
Different combinations of these 20 permission flags effectively allow any standard structure to be created; for example, a private message between two individuals may have the permissions "cadrec--r-----------", and reside in the recipient's inbox; an announcement on a blog may have the permissions "cadrec--r-c--r----r-" and be publicly legible, but only commentable by other members of the administrator group, and so forth.
There are two peculiar rules about how these permissions are interpreted that must be understood: (a) the middle two registers are additive and (b) the anonymous user only gets 'r' and 'a' permissions from the fourth register.
The first exception means that if you are both the owner of an entry's parent and belong to its group, you'll get all the benefits of both; the two do not fight each other. The intended usage case is that child nodes could be deleted by their parents and edited by anyone in the group, e.g. in a joint comment made on a forum. Author permissions always override group and parent permissions, so it's possible to have no permissions at all on an entry even if you're the parent and in the group.
The second exception makes it easier to control anonymous commenting. Anonymous users are counted as user 0, so if you want it to be possible for an unregistered person to comment on a news article, you can simply create a group that has the 'c' permission enabled and add Anonymous to it. This has some limitations, since editing permissions can't be then be given to a restricted group of authors, but that can be controlled through a carefully-written template.
