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 15 available

    Apr 25, 2023 - OpenCms 15 provides role-based control to restrict who is allowed to update the sitemap configuration, including an editor for modifying selected sitemap attributes by any content manager. The new launchpad app "Person data search" reveals personal user data stored in the VFS. The Mercury template adds more than 1800 optional icons from the Bootstrap collection and numerous further enhancements.

  • OpenCms 15 Release Notes

    Apr 25, 2023 - The OpenCms 15 release notes contain detailed information about the new features and fixes in this version.

  • Alkacon OCEE 15

    Apr 25, 2023 - Alkacon OCEE 15 is the latest OCEE release for OpenCms 15. This version features a new scheduled job for LDAP synchronization and fixes a number of issues that have been detected in Alkacon OCEE 14.

  • OpenCms 14 available

    Oct 11, 2022 - This version features XML schema versioning with automatic content rewrite. Also new is support for two factor authentication (2FA) in the user login. A source code editor widget is available for multi-line text input fields. The Mercury template has been updated to use Bootstrap 5.2.