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

    Apr 13, 2022 - OpenCms 13 features a new plugin system as a more flexible replacement of the "headincludes" functionality. Geo search functionality has been added to find contents by geo coordinates. Extensions to the template variant mechanism allow setting overrides and renaming of formatter keys. There are also refinements for the "Mercury" default template as well as security improvements.

  • OpenCms 13 Release Notes

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

  • Alkacon OCEE 13

    Apr 13, 2022 - Alkacon OCEE 13 is the latest OCEE release for OpenCms 13. This version fixes a number of issues that have been detected in Alkacon OCEE 12 and improves the licensing mechanism.

  • 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.