Creating navigations with XML content

Navigation structures in OpenCms are currently based on properties set on files and folders. This concept is not ergonomic and easy to handle for OpenCms users with little experience of the OpenCms VFS mechanisms.

A new approach is to create navigations using XML content files located in folders of the OpenCms VFS. It is required that the legacy property mechanism is still working as fallback.

XML content structure for navigation elements

The XML content structure representing a single navigation entry of a folder has the following fields to set:

  • Path to the resource / URL (CmsVarLink)
  • Navigation Text (CmsString)
  • Optional configuration (Nested - optional)
    • Default file (OpenCmsBoolean - optional)
    • NavInfo (OpenCmsString - optional)
    • NavImage (OpenCmsString - optional)

Necessary API changes to make XML contents work

Changes in the OpenCms core have to be made to the classes org.opencms.jsp.CmsJspNavBuilder and eventually to org.opencms.jsp.CmsJspNavElement. A new object representing a navigation entry definition in the XML content has to be added to the org.opencms.jsp package named CmsJspNavXmlConfigElement.

For further enhancements like linking to files in other folders more API changes have to be performed.

Proof of concept

For the proof of concept, a schema was developed together with a new resource type "navigation" derived from XML content. The file name of the configuration file has to be "_navigation.xml". The CmsJspNavBuilder has been enhanced and a new object has been developed. In addition, the new resource type definition has been added to the opencms-vfs.xml and the opencms-workplace.xml.

  • Database export containing XSD and file type icon
  • Patch for Eclipse containing class changes
  • Necessary changes in OpenCms configuration files

Enhancements of the POC

  • Consider the "Default file" setting which is not used yet
  • Enhance API to make links to other folders possible

Open issues when using XML contents for navigation structures:

  • Performance may be bad when using a lot of XML contents, should be investigated if the FlexCache is sufficient. Otherwise, implement a caching mechanism for navigation structures (must be user based).
  • Navigation behaviour with links to objects which are not located in the same folder as the XML content file defining the navigation items requires the differentiation between "Request URI" and "Navigation URI", for this the core API has to be enhanced.
  • Setting the default file currently requires writing the "default-file" property value to the parent folder, could be done using a specific XML content handler, but requires the folder to be locked. Better is a core modification.
  • "Direct Edit" should be available for the navigation XML content files to be able to adjust the navigation when previewing the website.
  • The XML content for the navigation structure should use a custom widget to make the creation of navigations more easy and user friendly.
  • Navigation behaviour when creating a new sub area for a navigation item representing a file is unclear. In the old scenario, a folder was created and the file moved into that folder as default file. In the new scenario, the file should be left where it is, a subfolder should be created in the background which contains the new navigation items. Somehow the folder must be linked to the file (relation?), the navigation builder has to check for these relations to create the navigation structure.

Latest News

  • OpenCms 12 available

    Oct 12, 2021 - OpenCms 12 features a headless JSON API for REST content access, together with several JavaScript demo applications that show how to use it. The default "Mercury" template has been greatly improved. Template variants allow to completely switch the generated HTML of a website simply by configuration. The updated WebDAV implementation enables mounting the OpenCms virtual file system from any WebDAV client.

  • OpenCms 12 Release Notes

    Oct 12, 2021 - The OpenCms 12 release notes contain detailed information about the new features and fixes in this version.

  • Alkacon OCEE 12.0

    Oct 12, 2021 - Alkacon OCEE 12.0 is the latest OCEE release for OpenCms 12. It adds new functions for managing log files in an OpenCms cluster, as well as improvements for the accelerator and the user synchronization.

  • OpenCms Docker image

    Oct 12, 2021 - Test OpenCms using the official image from the Docker hub registry - the fastest way to evaluate and test OpenCms. The image is well suited for evaluation and test purposes of the latest OpenCms release. We provide a docker-compose file to get OpenCms and the database running with just one command.