The content node tree is a hierarchical organization of the objects. Each leaf in the tree is a node (also known as a location). Each node refers to one object. The usual case is that an object is referenced by only one node. Because of the node-encapsulation of objects, any type of content object can be placed anywhere in the tree. At the minimum, the tree consists of one node, called the root node. The identification number of the root node is 1. The root node is a virtual node, it does not encapsulate an actual object. A node that is directly below the root node is called a top level node (the top level nodes are described in the next section). The depth and width of the tree is virtually unlimited. The following illustration shows a simplified example of how objects are referenced by nodes which together make up the content node tree.

Objects, nodes and the content node tree

The following illustration shows the same node structure seen from the outside world.

Content node tree

Multiple locations

An object may be referenced by several nodes, which means that the same object can appear at different locations within the tree. This feature can for example be used to place a specific news article at two locations: the frontpage and the archive. In the case of multiple nodes/locations, only one node can be considered as the main node of an object. The main node usually represents the object's original location in the tree. The other nodes can be thought of as additional nodes / locations. If an object is referenced by a single node then of course that node would be the main node. Among other things, the main node is used to avoid multiple search hits, infinite recursive loops, smart filtering, etc. The following illustration shows an example of a structure where an object has multiple locations in the tree. It will simply be empty and will have the possibility to contain a different set of sub items.

Objects, node and the content node tree - multiple locations

The following illustration shows the same node structure seen from the outside world.

Content node tree with multiple locations

Pitfall

A very common mistake when planning the structure of a site is thinking of multiple locations as shortcuts/links on a filesystem. Unfortunately, this is not how the node tree works. When a new location is added to an object, eZ publish will not go through and create replica of the node structure below the object's original location. For example, if a folder containing several subfolders with articles, images, etc. is assigned a secondary location, the subfolders with articles, images, etc. will not be automatically available below the new location of the folder.

Additional notes

Only published objects appear in the tree. A newly created object (status set to draft) does not get a node assignment until the object is published for the first time. An object is considered to be deleted (status set to archived) when all nodes referencing that object are removed from the tree. A deleted object will appear in the system trash. It is important to understand that the trash in eZ publish is a flat structure. This is different from what people are used to from the trash implementation in modern operating systems. Objects in the trash can be recovered to their original locations. However, this is only possible if their original parent nodes have not been deleted. Otherwise, the user must specify a new/alternate location for the objects during recovery. Note that specifying an alternate/new location can be done regardless if the system is able to restore a deleted object at its original location or not.

Furthermore, if a folder containing some news articles is deleted, both the folder and the articles will appear on the same level within the trash. Recovering the folder itself will not bring back the articles since the links between the folder and the articles got lost when the nodes were deleted. In this case, the folder needs to be recovered first. After that, each article has to be manually recovered and given a location.