Infrastructure côté serveur

Syntaxe du fichier de définition de menu JSON

Pour plus d'informations sur JSON, voir la page d'accueil de JSON.

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

Vous pouvez ajouter des commentaires dans ce fichier en utilisant une extension spécifique au portail de la syntaxe JSON.

Il n'y a pas de virgule dans l'objet final dans le tableau entre l'accolade fermante et le crochet fermant du tableau de fin.

L'ordre des objets dans le tableau dans le fichier de définition de menu détermine l'ordre d'apparition des éléments dans le menu sur le client.

Chaque objet dans le tableau est une définition d'élément de menu autonome individuelle, ou une référence à un module d'optimisation de thème pouvant fournir un marquage de fichier de définition de menu JSON en ligne supplémentaire. Ce JSON ajouté est inclus en ligne comme s'il figurait dans le fichier de menu lui-même.

Chaque objet se compose de plusieurs membres JSON séparés par une virgule, possédant chacun un nom et une valeur séparés par un signe deux-points. Le nom du membre est toujours une chaîne entre guillemets. Les valeurs peuvent être des chaînes, des valeurs booléennes, des objets imbriqués ou des tableaux, selon le nom de membre. Certains noms de membre ne peuvent avoir que certaines valeurs, conformément à la liste ci-après.

Les noms et valeurs d'éléments de menu suivants sont les valeurs acceptables pour le type d'entrée.

"type" : "Header"

Définit un libellé pour les entrées suivantes dans le menu. En général, il est mis en évidence et en retrait dans l'interface utilisateur client, bien que cet élément de menu soit contrôlé par le style appliqué aux éléments de menu. Un en-tête dans le menu n'est généralement pas cliquable.

Vous pouvez ajouter d'autres entrées d'objet de titre dans la valeur titles pour d'autres langues.

Vous pouvez ajouter un membre itemClass pour contrôler l'apparence de l'en-tête.

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

"type" : "Separator"

Définit un séparateur pour les éléments de menu. Un séparateur peut apparaître sous forme de blanc ou prendre l'apparence d'une ligne par exemple, selon le style appliqué au menu.

En général, un séparateur ne requiert pas d'autres membres, bien que vous puissiez ajouter un membre itemClass pour contrôler l'apparence.

{
"type" : "Separator",
}

"type" : "DynamicMenuitem"

Potentiellement cliquable et ayant une action, l'élément DynamicMenuitem a un membre id dont la valeur est un nom de plug-in. Le fournisseur de flux de menu utilise cet ID pour extraire une instance de l'opération nommée, dans laquelle sont ensuite recherchées les informations requises pour générer le contenu du flux de menu pour ce menuitem. Plusieurs plug-ins sont mis à disposition par HCL Portal et prêts à l'emploi dans les définitions de menu par défaut, qui peuvent être réutilisées dans des menus et des thèmes personnalisés.

Ce plug-in détermine lui-même s'il est actif, ainsi que les droits de contrôle d'accès pour l'utilisateur courant, et fournit son propre titre traduit, ainsi qu'une description, en option, et une valeur actionHttpMethod, que le fournisseur de flux de menu utilise lorsque vous générez l'entrée de menu pour cet élément. L'URI OperationURI de ce plug-in d'opérations devient l'adresse URL actionUrl dans l'entrée de menu correspondante. D'autres membres d'objet son admis, notamment actionFn, actionHttpMethod, visibilityFn, itemClass et des métadonnées. Un membre markupID peut être ajouté de sorte à créer un ID sur la balise HTML de l'élément de menu qui en découle.

Si la méthode isActive() renvoie la valeur false lorsqu'elle est appelée par le code du fournisseur de flux de menu, l'élément de menu est présent dans le flux de menu, mais un membre booléen "visibility" : false est ajouté au flux. Ce membre booléen indique au code côté client de ne pas présenter cette opération à l'utilisateur, et le code côté client n'inclut pas cet élément dans le menu final affiché.

En option, vous pouvez aussi spécifier un membre moduleArgs. Ce membre est une chaîne de noms et de valeurs présentés sous forme de paramètres de requête qui sont séparés par une perluète (&). S'ils sont présents, ces arguments sont transmis au plug-in lorsque le fournisseur de flux accède au plug-in pour générer l'entrée de menu courante.

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

"type" : "StaticMenuitem"

Possible de cliquer dessus et associé à une action. En général, il est utilisé pour insérer un élément de menu possédant une implémentation côté client, plutôt qu'une implémentation côté serveur.

Permet à l'auteur du fichier de définition de flux de menu de spécifier entièrement une entrée d'élément de menu arbitraire. Toutes les informations nécessaires doivent être fournies par le fichier de définition de menu, car il n'existe pas d'opération correspondante pour une entrée StaticMenuitem. Le paramètre id est facultatif et est ignoré par le code du fournisseur de flux de menu pour une entrée StaticMenuitem, même s'il ne génère pas d'erreur de syntaxe en cas d'absence.

Vous pouvez ajouter d'autres membres facultatifs, en fonction de vos besoins.

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

Un fichier de définition de menu possède un membre id dont la valeur est le nom d'un plug-in. Ce plug-in doit disposer d'une contribution du type de menu et d'une sous-contribution du type JSON. Le fournisseur de flux de menu utilise la valeur du membre id de ce projet JSON pour extraire une référence à la contribution JSON dans la contribution de menu pour ce module. Cette sous-contribution JSON doit être un marquage de définition de menu JSON autonome valide, incluant les crochets ouvrant et fermant entre lesquels est placé le tableau. Le fournisseur de flux de menu supprime ces crochets et insère le marquage contribué à la réponse de flux de menu comme s'il était inclus dans le fichier de définition principal.

Désigne par son nom un plug-in qui fournit un marquage de syntaxe de fichier de définition de menu et au format JSON supplémentaire, que le fournisseur de flux place en ligne dans le flux de menu et qui remplace l'entrée ModuleRef.

Vous pouvez éventuellement ajouter un membre moduleArgs. Si elle est présente, la valeur du membre moduleArgs est transmise sous forme d'arguments pour extraire le marquage du fichier de définition de menu JSON du plug-in.

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

"type" : "Submenu"

Définit un signet dans le menu en cours dans un nouveau sous-menu est associé. Cet élément permet des menus à plusieurs niveaux. Le niveau d'imbrication est illimité. Le sous-menu est extrait par une demande de menu supplémentaire indépendante au fournisseur de flux de menu JSON lorsque l'entrée de sous-menu est survolée dans le menu affiché.

Le menu est ajouté à un côté, comme l'indique la position de l'écran. Un membre de sous-menu est extrait dans une demande distincte du client.

Un membre de sous-menu nomme la source du contenu de son menu à l'aide d'un membre id ou moduleId, et doit posséder un membre titles pour fournir le texte de l'élément de menu signet ; en option, il peut aussi posséder un membre descriptions.

La seule différence entre ces deux membres concerne la façon dont la demande suivante est traitée, lorsque le sous-menu est développé et que le code du client extrait le flux de menu d'expansion dans une nouvelle demande HTTP :

• Pour un membre id, le système considère que la demande suivante nomme un fichier de définition de menu, où la valeur id et le nom de fichier et l'extension est .json.
• Pour un membre moduleId, le système considère que la demande suivante nomme un plug-in qui fournit le marquage JSON nécessaire. Cette demande est accessible de la façon dont l'a indiqué un fichier de définition de menu.

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

Vous pouvez également ajouter un membre moduleArgs. Si elle est présente avec un membre moduleRef dans une entrée SubMenu, la valeur du membre moduleArgs est ajoutée à l'URL qui est construite comme l'ID de l'élément de menu. Cette valeur est utilisée en tant que référence de menu à partir du client pour l'extraction du menu de marquage pour le sous-menu en cascade.

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

Membres valides dans un fichier de définition de menu JSON

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

foo=bar&foo2=bar2&... 

Ecriture d'un nouveau fichier de définition de menu pour un thème modularisé

Vous pouvez écrire un nouveau fichier de définition de menu pour un nouveau thème à l'aide du fournisseur de flux côté serveur et du code JavaScript™ côté client. Si vous copiez l'exemple de thème prêt à l'emploi et le modifiez pour générer un nouveau thème personnalisé, vous pouvez utiliser les mêmes fichiers de menu JSON ou les modifier, si nécessaire. Si aucune nouvelle fonction côté client n'est référencée à partir d'éléments de menu, ces nouvelles fonctions JavaScript™ doivent être créées et référencées.

Le fournisseur de flux de menu JSON recherche les fichiers de définition de menu JSON dans un répertoire menuDefinitions sous la racine de thème dans WebDAV.

Utilisez comme exemples les fichiers existants de définitions de menu et des outils tels que jsonlint pour prévalider la syntaxe JSON.

La syntaxe JSON est restrictive pour les fichiers de définition de menu, sauf que les commentaires sont autorisées.

Lors du débogage, utilisez la chaîne de trace com.ibm.wps.jsonmenu.*=all sur le serveur.

Menus étendus et construits dynamiquement

Depuis HCL Portal 8.0.0.1, il est possible d'ajouter dynamiquement des éléments de menu à un fichier de définition de menu. Vous pouvez utiliser cette fonction pour étendre un fichier de définition de menu "statique" existant, tel que les fichiers existants dans l'exemple de thème, dans le dossier menuDefinitions de WebDAV. Vous pouvez également l'utiliser pour construire dynamiquement un menu sans fichier de menu statique existant.

Souvenez-vous que dans l'URI de demande d'un menu, le paramètre de requête commence par "?uri=menu:menu name". Ce nom de menu est traité comme un nom de fichier par l'infrastructure de menus, et nous recherchons ce fichier dans "l'emplacement de base" des ressources de ce thème, tel qu'il est fourni par la propriété de métadonnées du thème com.ibm.portal.theme.template.ref. Dans la définition de menu, l'entrée "type":"ModuleRef" peut faire référence à un module d'optimisation de thème qui contient une contribution menu, contenant elle-même une sous-contribution JSON. La sous-contribution JSON comporte une URL pointant vers le code JSON même. Le code JSON, extrait de cette URL de sous-contribution, remplace dans le flux de menu l'entrée "type":"ModuleRef" du fichier.

Depuis HCL Portal 8.0.0.1, cette sous-contribution JSON peut également être étiquetée par un qualificateur ref-id. La valeur de ce qualificateur est une chaîne. A la fin du traitement du fichier de définition de menu, l'infrastructure de menu ajoute une étape. Elle recherche la page en cours dans toutes les sous-contributions JSON trouvées dans les modules de thème du profil, où la page est indiquée par le paramètre navID dans la demande de menu. Si l'une des balises ref-id provenant de ces sous-contributions correspond au nom du menu demandé qui est en cours de traitement, le code JSON de ces sous-contributions est dynamiquement ajouté à la fin du flux de menus, exactement comme s'il existait une entrée "type":"ModuleRef" désignant spécifiquement ce module.

Cette infrastructure de menus permet l'extension dynamique des contenus de menu avec de nouveaux éléments de menu par la création de modules de thème ou de sous-contributions, et par la mise à jour du profil, plutôt que d'avoir à mettre à jour les fichiers de définition de menu.

Pour plus d'informations sur la construction de modules d'optimisation de thème qui incluent la sous-contribution JSON, voir Ajout d'un élément de menu avec un module.

Contrôle de la durée de vie du cache d'un flux de menu JSON

Dans HCL Portal versions 8.0.0.1 et ultérieures, le canevas de menu JSON accepte une ou plusieurs propriétés WP ConfigService au format "jsonmenu.cache.time.<menu name>" où la valeur est la durée en cache, exprimée en secondes. Cette valeur doit être supérieure ou égale à 0. Une valeur 0 indique que le menu n'est pas mis en mémoire cache.

Les valeurs <menu name> provenant de ces paramètres WP ConfigService sont mises en correspondance avec la valeur provenant du paramètre de requête "?uri=menu:<menu name>" sur la demande entrante d'un menu. La comparaison des noms de menu entre WP ConfigService et la demande reçue pour un menu est sensible à la casse.