The content node tree

The content tree is the hierarchy of all nodes of an installation. It gives a site its structure (sections of the site are subtrees), its menus and its addresses, and it is the main way templates and code find content: "the children of this folder", "every article below News".

The shape of the tree

The tree has one root, node 1, which is not a page of its own. Below it are the top level nodes: Content (node 2), Users (node 5), Media (node 43), Setup (node 48) and Design (node 58). A public siteaccess normally shows the subtree of node 2: its front page is site.ini [SiteSettings] IndexPage (/content/view/full/2/ by default), and templates start their menus at content.ini [NodeSettings] RootNode=2.

1 (root)
├── 2  Content           the site: folders, articles, pages
│   ├── News
│   │   └── My article
│   └── About us
├── 5  Users             user groups and user accounts
├── 43 Media             images and files shared by the site
├── 48 Setup             setup objects
└── 58 Design            design objects

Every node stores its path from the root as node IDs (path_string, for example /1/2/58/72/) and its depth. That is why "everything below node 58" is a single, fast query on every database, however deep the tree is.

Reading the tree in templates

The fetch functions of the content module read the tree. list returns the children of a node, tree the whole subtree; both take the same filters:

{* the ten newest articles anywhere below the node *}
{def $articles = fetch( 'content', 'tree', hash( 'parent_node_id', $node.node_id,
                                                 'class_filter_type', 'include',
                                                 'class_filter_array', array( 'article' ),
                                                 'sort_by', array( 'published', false() ),
                                                 'limit', 10 ) )}

{* the children, sorted as the folder says, and how many there are *}
{def $children = fetch( 'content', 'list', hash( 'parent_node_id', $node.node_id,
                                                 'sort_by', $node.sort_array ) )
     $count    = fetch( 'content', 'list_count', hash( 'parent_node_id', $node.node_id ) )}

Other parameters limit the depth (depth, depth_operator), filter by attribute values (attribute_filter), include hidden nodes (ignore_visibility) or skip the permission check. The results only contain nodes the current user may read: the permission system is applied to every fetch.

Sorting

Each node says how its own children are sorted (its sort field and order). A folder sorted by priority lets editors set the order by hand with the priority numbers in its sub-items list; a news folder is usually sorted by published date, newest first. A new node takes the default sorting of its class.

Working with the tree in the administration

The Content structure tab shows the subtree of node 2 with a tree menu on the left and the sub-items list of the current node. Media library and User accounts show nodes 43 and 5 the same way. Moving, copying, hiding and removing a node act on its whole subtree; large operations can run as background jobs.