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 explorer as shown here.
OpenCms stores all resources in a database. The entries make up a virtual file system (VFS). It can be considered as a real file system, i.e., a folder structure with files in different folders. But it provides some more features. All resources in the VFS, folders and files, carry extra information. Moreover, there exist two versions of the VFS: "Offline" and "Online" and even the history of files is stored. To understand OpenCms, it is not necessary to fully understand all details of the VFS and the database structure, but some points are useful to know for understanding how OpenCms works.
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
- Resources 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 also have, potentially, 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 sees what is in the online version of the VFS, or more precisely 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 to guests on your page.
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/, exposes 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 separate site:
- When you call a page on a web site build with OpenCms, the URL will not have the folders,
/sites/default/, or similar, 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 of pages when you are logged in:
You can only view web pages when you are not working in the root site. You have to switch to the respective web site's site. Otherwise, calling a web page or editing an already opened one will not work properly.
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 company's portfolio, in both of the sites. To have easy 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.
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 there. When they are not set somewhere, they will simply not be found. Whether 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 on 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 a kind of link. i.e., the same content is reachable from two different places in the VFS. If you set a property as a shared property, it will be set on all siblings. Individual properties are only set on the one sibling and not on the others. If a property is set as an 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 metadata 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 a one-to-one relationship and it does not make a difference where the properties are attached.
Simplified, projects are just special views of the versions of the VFS. Their focus is to make groups of users "responsible" for a special set of resources. Thus, a project may exist for 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 the permissions of users, they are only helpful in structuring 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 your own projects for the online version. Setting up additional projects that provide a special view of resources in the offline version of the VFS can help you to structure tasks and to narrow down their view of 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:
Self-defined projects are only different views of the offline version of the VFS. They do not make separate copies of their resources. Hence, if a file belongs to two projects and it is changed in one project, it has also changed in the other project.
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. You can also mount the VFS to the real file system, but you may lose some of the "special features". See here for details.