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 10.5 Beta available

    Sep 26, 2016 - OpenCms 10.5 Beta provides a feature complete look at OpenCms 10.5. This will be the only pre-release version before OpenCms 10.5.0 is published, which is expected by the end of November. Only minor GUI updates, as well as improvements to the demo template, will be made for the final release.

  • OpenCms 10.5 Beta Release Notes

    Sep 26, 2016 - The OpenCms 10.5 Beta release notes contain detailed information about the new features and fixes in this beta version.

  • OpenCms 10.0.1 available

    Jun 14, 2016 - Being the greatest OpenCms update for years, version 10 brings a vastly improved user experience that combines the intuitive "Direct Edit" approach of OpenCms with a new, well integrated Lauchpad app center. OpenCms 10.0.1 is a maintenance update for 10.0.0 installations. It fixes several issues that persisted in previous releases. This version focuses on performance and stability.

  • OpenCms 10.0.1 Release Notes

    Jun 14, 2016 - The OpenCms 10.0.1 release notes contain detailed information about the updates and fixes in this version.