The virtual file system

You will not find the OpenCms file system on your server's file system. OpenCms stores all resources, such as folders and files, as well as all user specific data in a database. Files and folders stored in there make up a virtual file system. You can view it in the traditional workplace's explorer as shown in Figure [workplace_explorer].

The virtual file system provides the usual features of a "normal" file system:

• Files and folders can be moved, copied and deleted
• Permissions can be set
• Resources are locked if someone edits them
• Resouces have a creation and a "last modified" date

But the VFS comes also with some extra features:

• Resources are typed (finer than just distinguishing file and folder)
• Resources have, potentially also user-defined, properties attached
• Resources in the system can be related (i.e., a dependency between them is established)
• The history of resources (state when publishing a resource) can be saved and restored
• When resources are moved, links are automatically adjusted (if the link-relationship-engine is used)

Moreover, the traditional workplace's explorer allows you to publish resources. But more on this in the next section.

The VFS exists twice. There is an "offline" and an "online" version. In the traditional workplace you can switch the version via the "Project" selector in the upper left corner. The version will not always be identical.

The offline version is the version you work in. Here you can change, move, add or delete resources or edit properties. The offline version is only accessible for users that are logged in. Guest users will never see the offline version. Your changes will thus never be visible directly in the web.

The online version is the version visible for guest users. You cannot change anything online. When someone opens a page of your OpenCms-made website, he see's what is in the online version of the VFS, or more precise what is built from the resources in the online version. All resources used to build up the page are taken from the online version of the VFS. This version cannot be edited directly. If you switch to the project "Online" in the traditional workplace's explorer, you can view the resources and explore their properties and histories. But you cannot change anything. If you view a page in the online project, no page editor is shown, even if you are logged in as admin.

Publishing resources copies them from the offline version to the online version of the VFS. The only way to change the online version of the VFS is to publish resources from the offline version. Then they are copied to the online version and overwrite possibly existing older versions of the online version of a resource. Hence, after publishing, changes are visible for guests on your page.

Simplified, projects are just special views on the versions of the VFS. There focus is to make groups of users "responsible" for a special set of resources. Thus, a project may exist of example, if you have to rework something on your web site. You can assign managers to a project, that can publish changes on the project resources and delete the project, if the task is fulfilled. There are also some other options. Projects have no influence on permissions of users, they are only helpful to structure tasks. There are two special, predefined projects: the "Offline" project, that provides access to the complete offline version of the VFS, and the "Online" project, that provides access to the complete online version of the VFS.

You can define own projects that contain resources of the offline version of the VFS, but you cannot create own projects for the online version. Setting up additional projects that provide a special view on resources in the offline version of the VFS can help you to structure tasks and to narrow down their view on the VFS according to the task. You can also publish all resources in a project in one run. For the online version of the VFS no additional projects can be defined. There is no need for it. The online version can only be viewed and you cannot alter something anyway - so no task can be performed on it.

What is important to know:

In the traditional workplace you find a "Site"-selector in the upper menu bar. Here you can choose between different sites. By default, three sites are available:

• The root site (/)
• The default site (/sites/default/)
• The shared folder (/shared/)

Sites provide access to subtrees of the VFS. The VFS has a specific structure with basically three main folders:

• /shared/ where content and resources that are used by various websites hosted in the OpenCms installation are stored
• /sites/ where each website hosted by the OpenCms installation has its own subfolder that contains the website's pages and typically the contents used on the website and some config files.
• /system/ where all OpenCms resources are found, that are not part of a website's structure, configuration or content. These are, for example, templates, content type definitions and formatters (shipped in modules), but also resources of the workplace etc.

The root site exposes the whole VFS, but it is not the perfect view for all OpenCms users. From the root site you can navigate to each folder in the VFS. Hence, also to each resource that may be expose by other sites. You can see, and probably edit, templates, formatters, content type defintions and all the other stuff. Administrators or template developers may work in the root site. But it is definitely not the place for content editors.

A site for a web site, such as /sites/default/, expose the structure of a web site, i.e., only the folders below the web site's root folder, such as all folders below /sites/default/. When you view a web site generated by OpenCms, its structure closely corresponds to the folder structure of the VFS that is exposed in the web site's "site". Which "web site"-sites are available and under which URL  the corresponding web sites can be reached can be configured. There are advantages in regarding the VFS with the web site's root folder as root as a separte site:

• When you call a page on a web site build with OpenCms, the URL will not have the folders, /sites/default/, or something alike, included. It starts at the root folder configured for this web site.
• Depending on your role in OpenCms you should see only resources for one web site. Here the view of the web site's site is perfect. You do not have to care nor know about the stuff in the /system/ folder - or the other web sites in your OpenCms installation.

That URLs are relative to the configured web site's root folder influences the view on pages when you are logged in:

The /shared/ folder provides a way to share content or other resources between various sites. When you have more than one site in OpenCms, for example, you run an intranet and an internet web site on your installation, you may want to use the same content, e.g., an article describing your companies portfolio, in both of the sites. To easily have access to the article in both web sites, in particular if you want content managers to place the article on your web sites, it can be placed in the /shared/ folder.

In the VFS each resource can have properties attached. Properties are simple key-value pairs. For each resource a map with those key-value pairs is stored. The map contains only properties where values are set for.

Properties of resources can be read either such that only values directly set at the resource are read, or also values set at some parent folder (inherited value). Whenever a property is read you can decide if inherited values should be taken into account or not. So inherited or not is not specific for a property, but for a use case.

OpenCms already uses a lot of properties internally. For example. Title and NavPos properties are used very prominently to show information on a resource. But also the template property is used: It determines which template JSP is used by a container page.

You can use properties for whatever you like. Just read them in a JSP or a Java class and act according to your needs. Properties are simply their. When they are not set somewhere, they will simply not be found. If a property is shown in the "Edit properties" dialog, for example, does not depend on some JSP or Java class trying to access the property, or a special "property registration". It simply depends on the fact that the property is set at some VFS resource.

When you open the properties dialog of a file, you may notice three tabs:

The "Basic Properties" tab is a configurable set of properties available to content editors. Our interest is in the last two tabs: "Individual Properties" and "Shared Properties". In both tabs you can set every property you like. Existing ones or newly created ones. So why can everything be done twice?

Files can have siblings. Siblings are kind of links. I.e., the same content is reachable from two different places in the VFS. If you set a property as shared property, it will be set at all siblings. Individual properties are only set at the one sibling and not on the others. If a property is set as individual and shared property, the value set at the individual version of the property overwrites the shared value.

The concept of siblings is implemented as follows in OpenCms. Each resource of the VFS consists of two or three different database entries: A structure entry, a resource entry and, if it is a file, a content entry. The different parts serve these purposes:

• The structure part mainly locates the resource in the VFS.
• The resource part captures meta data of the resource, e.g., its type, state (modified, added, deleted, ...), creation and "last modified" date, creating/modifying user, etc.
• The content part, that is only present for files, simply stores the file content as a blob.

Siblings are resources with different structure parts, but identical resource and content parts. Now, what makes the difference between shared and individual properties? The properties are attached to different parts of the resource:

• Shared properties are attached to the resource part of a resource.
• Individual properties are attached to the structure part.

You get the difference? Ok. Now, you may notice that for folders there is no distinction between shared and individual properties. For folders, siblings are simply not allowed. Thus structure and resource parts for a folder are in one-to-one relationship and it does not make a difference where the properties are attached.

In the traditional workplace's explorer view you can take full advantage of all the extra features. For example, various (XML) files can be edited with the content editor, historic versions of files can be compared, etc. As a drawback of the workplace's explorer view, you cannot stick to your usual development environment, e.g., your favorite editor. To overcome this drawback, you can also mount the VFS to the real file system, but you may loose some of the "special features". See here for details.