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

  • Introducing OpenCms 10.5

    Nov 30, 2016 - OpenCms 10.5 focuses on site localization, adding tools for assisted translation of pages and sitemaps. Many usability improvements have been made for the Page Editor and the Explorer. OpenCms 10.5 also ships a much improved version of the Apollo Template. Based on Bootstrap, the Apollo Template is fully customizable without coding.

  • OpenCms 10.5 Release Notes

    Nov 30, 2016 - The OpenCms 10.5 release notes contain detailed information about the new features and fixes in this version.

  • OpenCms Docker image

    Nov 30, 2016 - Test OpenCms 10.5 using the official image from the Docker hub registry - the fastest way to evaluate and test OpenCms.

  • OpenCms documentation and demo sites

    Nov 30, 2016 - We have launched a new OpenCms documentation site and updated the demo site for OpenCms 10.5. The new OpenCms Documentation Central connects all relevant sources of information about OpenCms.