Server-side framework | HCL Digital Experience

JSON menu definition file syntax

For more information about JSON itself, see the JSON home page.

[
   // optional one-line comment 
   {
     JSON object 1 (first menu item)
   },
   /*
     optional multi-line comment
   */
   {
     JSON object 2 (second menu item)
   },
   ...
]

You can add comments in this file by using a portal-specific extension to JSON syntax.

The final object in the array does not have a comma between its curly brace and the ending array closing bracket.

The order of the objects in the array within the menu definition file determines the order of appearance of the items in the menu on the client.

Each object within the array is an individual self-contained menu item definition, or a reference to a theme optimization module that can provide more in-line JSON menu definition file markup. This contributed JSON is included in-line as though it was in the menu file itself.

Each object consists of multiple comma-separated JSON members, each of which has a name and a value that are separated by a colon. The member name is always a string in quotation marks. The values can be strings, Booleans, nested objects, or arrays, depending on the member name. Some member names can have only certain values, as defined in the following list.

The following menu item names and values are acceptable values for the type entry.

"type" : "Header"

Defines a label for subsequent entries in the menu. Typically displayed on the client UI as highlighted and outdented, although this menu item is controlled by the style that is applied to the menu items. A header in the menu is typically not clickable.

More title object entries, within the titles value, for other languages can be added.

An itemClass member can be added for controlling the appearance of the header.

{
"type" : "Header",
"titles" : [{"lang":"en","value":"<English text>"}, {"lang":"de", "value" : "German text"},...]
}

"type" : "Separator"

Defines a separator between menu items. A separator might show as a space, a line, or other appearance, depending on the style that is applied to the menu.

A separator does not typically need any other members, although an itemClass can be added for appearance control.

{
"type" : "Separator",
}

"type" : "DynamicMenuitem"

Potentially clickable and having an action the DynamicMenuitem item has an id member whose value is a plug-in name. The menu feed provider uses this ID to retrieve an instance of the named operation, which is then queried for sufficient information to build the menu feed content for this menuitem. Several plug-ins are supplied ready-to-use by HCL Portal for use in the default menu definitions, and these can be reused by custom-written menus and themes.

This plug-in provides its own indicator of whether it is active, including access control permission for the current user, and provides its own localized title and optionally a description, and an actionHttpMethod value, for the menu feed provider to use when you build the menu for this item. The OperationURI for this operation plug-in becomes the actionUrl in the corresponding menu entry. Other object members are allowed as well, including actionFn, actionHttpMethod, visibilityFn, itemClass, and metadata. A markupID member can be added to create an ID on the html tag for the resulting menu item.

If the isActive() method returns false when called by the menu feed provider code, the menu item is present in the menu feed, but has a "visibility" : false boolean member added to the feed. This boolean member indicates to the client-side code to not present this operation to the user, and the client-side code does not include this item in the final rendered menu.

Optionally, a moduleArgs member might also be specified. This member is a string of query parameter-format names and values that are separated by ampersands (&). If present, these arguments are passed to the plug-in when the feed provider accesses the plug-in to build the current menu entry.

{
"type" : "DynamicMenuitem",
"id" : "operations.framework.plugin.name"
}

"type" : "StaticMenuitem"

Potentially clickable and having an action. This item is typically used to insert a menu item that has a client-side implementation, rather than a server-side implementation.

Allows the menu feed definition file author to completely specify an arbitrary menu item entry. All necessary information must be provided by the menu definition file, because there is no corresponding operation for a StaticMenuitem. The id parameter is optional and is ignored by the menu feed provider code for a StaticMenuitem, although it is not flagged as a syntax error if it is present.

Other optional members might be added as needed.

{
"type" : "StaticMenuitem",
 "titles" : [{"lang" : "en", "value" : "My English menu item text"},
        {"lang" : "de", "value" : "Mein menu item text auf Deutsch"},
         ...
        ],
"descriptions" : [{"lang" : "en", "value" : "My English menu item longer description flowing beautiful prose"},
             {"lang" : "de", "value" : "Mein menu item longer description flowing beautiful prose auf Deutsch"},
             ...
             ],
"actionUrl" : "http://www.cntserv_exmp.com/wps/myportal/some_useful_url",
"actionHttpMethod" : "POST",
"actionFn" : "client_method_to_override_actionUrl",
"metadata" : {
        "navID" : "${navID}",
        "some_name" : "some_value",
        "some_other_name" : "${SubVar_From_Request_Query_Parms}"
        }
"markupId" : "my.item.markupId"
}

"type" : "ModuleRef"

A menu definition file has an id member whose value is the name of a plug-in. This plug-in must have a contribution of the menu type, and a subcontribution of the JSON type. The menu feed provider uses the value of the id member in this JSON object to retrieve a reference to the JSON subcontribution within the menu contribution for that module. This JSON subcontribution must be valid stand-alone JSON menu definition markup, including the surrounding array opening and closing brackets. The menu feed provider strips the array opening and closing brackets and inserts this contributed markup in-line into the menu feed response as though it is included in the main definition file.

Points by name at a plug-in that provides more JSON format and menu definition file syntax markup, which the feed provider places inline in the menu feed and that replaces the ModuleRef entry.

Optionally, a moduleArgs member can be added. If present, the value of the moduleArgs member is passed as arguments to retrieve the JSON menu definition file markup from the plug-in.

{
"type" : "ModuleRef",
"id" : "Theme Optimization Framework module name"
}

"type" : "Submenu"

Defines a placeholder in the current menu where a new sublevel menu is attached. This item allows for multiple tiered menus. There is no enforced limit to the nesting level. The submenu is retrieved by an independent additional menu request to the JSON menu feed provider when the submenu entry in the displayed menu is hovered over.

The menu is appended to the one side as screen position dictates. A submenu is fetched in a separate subsequent request by the client.

A submenu names the source of its menu content with either an id or a moduleId member, and must have a titles member to provide the text for the placeholder menu item, and might optionally have a descriptions member.

The only difference between these two members is how the next request is processed, when the submenu is expanded and the client code retrieves the expansion menu feed in a new HTTP request:

• For an id, the next request is treated as naming a menu definition file where the id value is the file name and the extension is .json.
• For a moduleId, the next request is treated as naming a plug-in that provides the necessary JSON markup. This request is accessed as though a menu definition file specified it.

  {
  "type" : "ModuleRef",
  "id" : "moduleId_value"
  }

A moduleArgs member might also be added. If present with a moduleRef member within a SubMenu entry, the value of the moduleArgs member is appended to the URL that is built as the ID of the menu item. This value is used as the menu reference from the client for retrieving the menu markup for the cascaded submenu.

    {
    "type" : "SubMenu",
    "id" : "name_of_submenu_definition_JSON_file",
     "titles" : [{"lang" : "en", "value" : "My English sub-menu item text"},
          {"lang" : "de", "value" : "Mein sub-menu item text auf Deutsch"},
          ...
          ],
    "descriptions" : [{"lang" : "en", "value" : "My English sub-menu item longer description flowing beautiful prose"},
          {"lang" : "de", "value" : "Mein sub-menu item longer description flowing beautiful prose auf Deutsch"},
          ...
          ]
     }
    or
     {
    "type" : "SubMenu",
    "moduleId" : "name_of_theme_opt_framework_module_which_contributes_submenu_definition_JSON_",
    ...
    }  

Valid members in a JSON menu definition file

[
  {
    ....
    "metadata" : {
           "a" : "something",
           "b" : true,
           "c" : 123,
           "thisIsNestedMetadata" : {
                 "a" : "something nested",
                 "d" : "This is a substitution:  ${subVar}"
           }
      }
      ...
  }
]

foo=bar&foo2=bar2&... 

Writing a menu definition file for a modularized theme

You can write a new menu definition file for a new theme by using the server-side feed provider and client-side JavaScript™. If the ready-to-use sample theme is copied and altered into a new customized theme, the same JSON menu files can be used, or can be altered as necessary. If any new client-side functions are referenced from menu items, then these new JavaScript™ features must be created and referenced.

The JSON menu feed provider looks for the JSON menu definition files in a menuDefinitions directory in the theme root in WebDAV.

Use the existing menu definitions files as samples, and use tools such as jsonlint to prevalidate the JSON syntax.

The JSON syntax is restrictive for menu definition files except that comments are allowed.

When you are debugging, use the trace string com.ibm.wps.jsonmenu.*=all on the server.

Dynamically extended and dynamically constructed menus

Starting with HCL Portal 8.0.0.1, it is possible to have menu items added dynamically to a menu definition file. This feature can be used to extend an existing "static" menu definition file, such as the files that exist in the sample theme within the menuDefinitions folder in WebDAV. It can also be used to dynamically construct a menu without a static menu file that exists at all.

Recall that in the request URI for a menu, the query parameter starts with "?uri=menu:menu name". This menu name is treated as a file name by the menu framework, and we search for the file in the "base location" for resources for that theme as given by the theme metadata property com.ibm.portal.theme.template.ref. Within the menu definition, an entry of "type":"ModuleRef" can reference a theme optimization module, which contains a menu contribution, and within that a JSON subcontribution. This JSON subcontribution has a URL, which points to the actual JSON code. The JSON retrieved from that subcontribution URL is substituted into the menu feed in place of the "type":"ModuleRef" entry from the file.

Starting with HCL Portal 8.0.0.1, this JSON subcontribution can also be tagged with a ref-id qualifier. The value of this qualifier is a String. At the end of processing the menu definition file, the menu framework adds one more step. It searches through all the JSON subcontributions that are found in theme modules from the profile for the current page, where the page is given by the navID parameter on the menu request. If any of the ref-id tags from those subcontributions match the requested menu name that is being processed, then the JSON code for those subcontributions is dynamically added to the end of the menu feed, exactly as though there were an entry "type":"ModuleRef" that specifically pointed to that module.

This menu framework allows for dynamic extension of the menu contents with new menu items by creating new theme modules, or at least new subcontributions, and updating the profile, rather than having to update the menu definitions files.

For more information about constructing theme optimization modules that include the JSON subcontribution, see Adding a menu item with a module.

Controlling the cache lifetime of a JSON menu feed

In HCL Portal version 8.0.0.1 and later, the JSON menu framework accepts one or more WP ConfigService properties of the form "jsonmenu.cache.time.<menu name>" where the value is the cache time in seconds. This value must be greater than or equal to 0. A value of 0 indicates that the menu is not cached.

The <menu name> values from these WP ConfigService settings are matched against the value from the "?uri=menu:<menu name>" query parameter on the incoming request for a menu. The comparison of the menu names from the WP ConfigService to the received request for a menu is case-sensitive.