服务器端框架

JSON 菜单定义文件语法

有关 JSON 自身的更多信息，请参阅 JSON 主页。

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

您可以通过使用特定于门户网站的扩展名对此文件中的 JSON 语法添加注释。

数组中的最后一个对象在其花括号与数组右括号之间没有逗号。

在菜单定义文件中，数组中对象的顺序确定了各个项在客户机菜单中的外观顺序。

数组中的每个对象都是一个独立的自包含菜单项定义，或者是对可提供更多直接插入 JSON 菜单定义文件标记的主题优化模块的引用。添加的这个 JSON 以直接插入形式包括，就好像是在菜单文件中一样。

每个对象由多个逗号分隔的 JSON 成员组成，每个成员都具有以冒号分隔的名称和值。成员名总是括在引号内的字符串。值可以是字符串、布尔值、嵌套对象或数组，具体取决于成员名。某些成员名只能具有特定的值，下表对此进行了定义。

下列菜单项名称和值是 type 条目可接受的值。

"type" : "Header"

为菜单中的后续条目定义标签。在客户机 UI 中，通常以突出显示或缩进方式显示，尽管此菜单项由应用于菜单项的样式控制。菜单中的 header 通常不可单击。

可以通过 titles 值为其他语言添加更多标题对象条目。

可以添加一个 itemClass 成员以控制 header 的外观。

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

"type" : "Separator"

定义菜单项之间的分隔符。分隔符可以显示为空白、线条或其他外观，具体取决于应用于菜单的样式。

通常，分隔符不需要任何其他成员，尽管可以添加 itemClass 用于控制外观。

{
"type" : "Separator",
}

"type" : "DynamicMenuitem"

可能可单击并具有操作，DynamicMenuitem 项目具有一个值为插件名称的 id 成员。菜单订阅源提供程序使用此标识来检索所指定操作的实例，然后查询该实例以获取为此 menuitem 构建菜单订阅源内容的充分信息。WebSphere Portal 提供了一些即时可用的插件以用于缺省菜单定义，并且这些插件可由定制编写的菜单和主题复用。

此插件提供指示其是否活动的指示符（包括当前用户的访问控制许可权），还提供其自己的本地化标题和描述（可选）以及 actionHttpMethod 值，以供菜单订阅源提供程序为此项构建菜单时使用。此操作插件的 OperationURI 将成为相应菜单条目中的 actionUrl。另外，还允许出现其他对象成员，包括 actionFn、actionHttpMethod、visibilityFn、itemClass 和元数据。可以添加 markupID 成员为产生的菜单项创建 html 标记的标识。

如果 isActive() 方法由菜单订阅源提供程序代码调用时返回 false，那么菜单项将显示在菜单订阅源中，但对订阅源添加了 "visibility" : false 布尔成员。此布尔成员向客户机端代码指出，不应对用户显示此操作，并且客户机端代码在最终呈示的菜单中不包括此项。

（可选）还可以指定 moduleArgs 成员。此成员是名称和值由“&”符分隔的查询参数格式字符串。 如果指定此项，那么这些参数将在订阅源提供程序访问插件时传递到此插件，以构建当前菜单条目。

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

"type" : "StaticMenuitem"

可能可单击，并具有操作。通常，此项用于插入一个具有客户机端实现（而不是服务器端实现）的菜单项。

允许菜单订阅源定义文件作者完全指定任意菜单项条目。由于不存在 StaticMenuitem 的相应操作，因此所有必要的信息都必须由菜单定义文件提供。id 参数是可选的，并且将被 StaticMenuitem 的菜单订阅源提供程序代码忽略，尽管未将其标记为语法错误（如果存在）。

可以根据需要添加其他可选成员。

{
"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.yourco.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"

菜单定义文件具有一个 id 成员，其值是插件的名称。此插件必须具有 menu 类型的添加项和 JSON 类型的子添加项。 菜单订阅源提供程序使用此 JSON 对象中 id 成员的值来检索此模块菜单添加项中对 JSON 子添加项的引用。这个 JSON 子添加项必须是有效的独立 JSON 菜单定义标记，包括两旁的数组左括号和右括号。菜单订阅源提供程序将除去数组左括号和右括号，并将这个添加的标记直接插入到菜单订阅源响应中，就像它包括在主定义文件中一样。

按名称指向提供了更多 JSON 格式和菜单定义文件语法标记的插件，订阅源提供程序将该标记直接插入菜单订阅源以替换 ModuleRef 条目。

（可选）可以添加 moduleArgs 成员。 如果指定此项，moduleArgs 成员的值将作为参数进行传递，以便从插件中检索 JSON 菜单定义文件标记。

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

"type" : "Submenu"

在当前菜单中定义一个占位符（在此位置附加新的子级菜单）。此项目可以支持多级菜单。对嵌套级别没有强行限制。鼠标悬停在显示的菜单中的子菜单条目上时，将通过向 JSON 菜单订阅源提供程序发送另一个独立的菜单请求对子菜单进行检索。

按照屏幕位置的指示将菜单追加到一侧。submenu 由客户机在另一个后续请求中访存。

Submenu 通过 id 或 moduleId 成员来命名其菜单内容源，且必须具有 titles 成员来提供占位符菜单项的文本，并且可具有 descriptions 成员（可选）。

这两个成员之间的唯一区别在于处理下一个请求的方式，在展开子菜单并且客户机代码在新的 HTTP 请求中检索扩展菜单订阅源时：

• 对于 id，下一个请求被视为命名菜单定义文件，其中 id 值是文件名并且扩展名是 .json。
• 对于 moduleId，下一个请求被视为命名提供了必要 JSON 标记的插件。将访问此请求（就好像菜单定义文件已指定它）

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

还可以添加 moduleArgs 成员。如果与 moduleRef 成员一起出现在 SubMenu 条目中，那么 moduleArgs 成员的值将追加到作为菜单项的标识构建的 URL 中。该值用作客户机中的菜单引用，用于检索级联子菜单的菜单标记。

    {
    "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_",
    ...
    }  

JSON 菜单定义文件中的有效成员

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

foo=bar&foo2=bar2&... 

为模块化的主题编写菜单定义文件

您可以使用服务器端订阅源提供程序和客户机端 JavaScript 为新主题编写新的菜单定义文件。如果复制随时可用的样本主题并将其更改为新的定制主题，那么可以根据需要使用或更改相同的 JSON 菜单文件。如果从菜单项中引用了任何新的客户机端函数，那么必须创建并引用这些新的 JavaScript 功能。

JSON 菜单订阅源提供程序在 WebDAV 中主题根下的 menuDefinitions 目录中查找 JSON 菜单定义文件。

使用现有菜单定义文件作为样本，并使用 jsonlint 之类的工具来预先验证 JSON 语法。

JSON 语法在用于菜单定义文件时受限（除此之外允许进行注释）。

进行调试时，请在服务器上使用跟踪字符串 com.ibm.wps.jsonmenu.*=all。

动态扩展和动态构造的菜单

从 WebSphere Portal 8.0.0.1 开始，可以将菜单项动态添加到菜单定义文件。可以使用此功能来扩展现有“静态”菜单定义文件，例如在 WebDAV 的 menuDefinitions 文件夹中样本主题中存在的文件。还可以使用此功能来动态构造不具有静态菜单文件的菜单。

如前文所述，在菜单的请求 URI 中，查询参数以 "?uri=menu:menu name" 开头。此菜单名称被菜单框架视为文件名，我们在资源的“基本位置”中搜索该文件，针对这些资源，主题元数据属性 com.ibm.portal.theme.template.ref 指定了主题。在菜单定义中，"type":"ModuleRef" 条目可在 JSON 子添加项引用主题优化模块，此模块包含 menu 添加项。此 JSON 子添加项具有指向实际 JSON 代码的 URL。从该子添加项 URL 检索到的 JSON 会替换文件的菜单订阅源中 "type":"ModuleRef" 条目。

从 WebSphere Portal 8.0.0.1 开始，此 JSON 子添加项还使用 ref-id 限定符进行了标记。该限定符的值为字符串。菜单定义文件处理结束时，菜单框架会再添加一个步骤。它会在当前页面的概要文件的主题模块中发现的所有 JSON 子添加项中搜索，在菜单请求上为此页面指定了 navID 参数。如果这些子添加项的任一 ref-id 标记与正处理的请求菜单名称匹配，那么会动态将这些子添加项的 JSON 代码添加到菜单订阅源的末尾，好像具有专门指向该模块的 "type":"ModuleRef" 条目一样。

此菜单框架通过创建新主题模块（或至少创建新子添加项），以及更新概要文件（而不必更新菜单定义文件）以允许使用新菜单项动态扩展菜单内容。

有关构造包含 JSON 子添加项的主题优化模块的更多信息，请参阅“使用模块添加菜单项”。

控制 JSON 菜单订阅源的高速缓存生存期

在 WebSphere Portal V8.0.0.1 及更高版本中，JSON 菜单框架接受一个或多个 "jsonmenu.cache.time.<menu name>" 形式的 WP ConfigService 属性，其中值是以秒为单位的高速缓存时间。此值必须大于或等于 0。值为 0 表示不对菜单进行高速缓存。

这些 WP ConfigService 设置中的 <menu name> 值将与传入菜单请求中的 "?uri=menu:<menu name>" 查询参数的值进行匹配。WP ConfigService 中的菜单名称与接收到的菜单请求的比较区分大小写。