4.7 Manipulation des menus

4.7.1 Déclaration

Le définition du menu du document est indiqué dans la classe de configuration de rendu.

Elle est fournie par la méthode IRenderConfig::getMenu().

/**
 * @param \Doc $document Document object instance
 * @return BarMenu Menu configuration
 */
public function getMenu(\Doc $document);

Cette méthode retourne un objet Dcp\Ui\Barmenu qui contient la définition de chacun des éléments constituant le menu.

4.7.2 Éléments de menu

4.7.2.1 Élément de menu simple

Un élément de menu est défini par un objet de la classe Dcp\Ui\ItemMenu.

4.7.2.1.1 Construction

Dcp\Ui\ItemMenu __construct(string $identifier, 
                            string $label = '', 
                            string $url = '')

Arguments :

id

Identifiant du menu : Il doit être unique dans la barre de menu.

label (optionnel)

Texte brut affiché sur le menu

url (optionnel)

Url cible du menu

Exemple :

public function getMenu(\Doc $document) {
    $myMenu = new \Dcp\ui\BarMenu();
 
    $myItem = new \Dcp\Ui\ItemMenu(
        "myTest5",
        ___("My label", "my")
    );
 
    $myItem->setUrl("http://www.example.net");
 
    $myMenu->appendElement($myItem);
 
    return $myMenu;
}

4.7.2.1.2 Définition de l'url

4.7.2.1.2.1 Indiquer une Url statique

L'url est indiquée sur le constructeur ou par la méthode setUrl().

Dcp\Ui\ItemMenu setUrl(string $url)

Cette url peut être relative ou absolue.

L'url est un template Mustache, et accepte les variables suivantes :

Exemple :

$myItem->setUrl("http://www.example.net/?id={{document.properties.id}}");

4.7.2.1.2.2 Indiquer la cible du menu

Par défaut, la cible du menu est _self. Elle peut être modifiée par la méthode setTarget().

Dcp\Ui\ItemMenu setTarget(string $target, 
        Dcp\Ui\MenuTargetOptions $dialogOptions=null)

Arguments :

$target

la cible du menu

Si $target vaut _dialog, le résultat de la requête sera affiché dans une fenêtre de dialogue interne.

$dialogOptions

Lorsque la cible est _dialog, la fenêtre de dialogue peut être paramétrée au moyen d'un objet \Dcp\Ui\MenuTargetOptions.

Cet objet a les propriétés suivantes :

title

Titre de la fenêtre de dialogue

windowHeight

Hauteur de la fenêtre de dialogue. Les unités doivent être absolue ("px", "em")

windowWidth

Largeur de la fenêtre de dialogue. Les unités doivent être absolue ("px", "em")

Cette option n'est pas applicable si l'url est celle d'un événement.

Si la cible est _self, les options windowHeight et windowWidth peuvent être utilisée. Par contre l'unité doit obligatoirement être un nombre (exprimé en "px"). Dans ce cas, la fenêtre ouverte ne possède ni menus ni barre d'adresse.

Exemple :

$item = new \Dcp\Ui\ItemMenu(
    "myMessage",
    ___("My message", "My")
);
 
$targetOption = new \Dcp\Ui\MenuTargetOptions();
$targetOption->title = ___("This is my message", "My");
$targetOption->windowHeight = "300px";
$targetOption->windowWidth = "400px";
 
$item->setTarget("_dialog", $targetOption);

4.7.2.1.2.3 Émettre un événement

L'url peut aussi être définie pour être capturée par le client avec du code javascript.

Si l'url est de la forme #action/<eventType>:<option1>:<option2>:..., l'événement peut être capturé par l'écoute de actionClick.

Exemple :

class MyRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getJsReferences() {
        $js=parent::getJsReferences();
        $js["myContact"]="MY/Layout/myCustom.js";
        return $js;
    }
 
    public function getMenu(\Doc $document) {
        $menu = parent::getMenu($document);
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myAlert",
            ___("My alert", "my")
        );
 
        $myItem->setUrl("#action/my:myOptions");
 
        $menu->appendElement($myItem);
 
        return $menu;
    }
}

Fichier MY/Layout/myCustom.js :

window.dcp.document.documentController(
    "addEventListener",
    "actionClick",
    {
        "name": "my.alert",
        "documentCheck": function (documentObject) {
            return (documentObject.family.name === "MY_FAMILY");
        }
    },
    function(event, documentObject, data) {
        if (data.eventId === "my") {
            if (data.options.length > 0 && data.options[0] === "myOptions" ) {
                alert("I catched my event");
            }
        }
    }
);

4.7.2.1.3 Contenu du menu

Le contenu du menu est la partie affichée.

4.7.2.1.3.1 Libellé du menu

Le libellé du menu est indiqué sur le constructeur ou par l'une des méthodes suivantes :

setTextLabel()

La méthode setTextLabel() indique un libellé texte brut. Les caractères spéciaux seront échappées en entités HTML.

Dcp\Ui\ItemMenu setTextLabel(string $label)

setHtmlLabel()

La méthode setHtmlLabel() indique un fragment html qui sera affiché.

Dcp\Ui\ItemMenu setHtmlLabel(string $label)

Dans le cas où les 2 méthodes sont utilisées, le label brut est précédé du label HTML.

4.7.2.1.3.2 Préfixe de menu

Il est possible d'ajouter un préfixe de menu (ce préfixe sera aligné verticalement sur le menu) au moyen des méthodes suivantes :

setBeforeContent

La méthode setBeforeContent() permet d'ajout un fragment HTML avant le texte (par exemple, un caractère font-awesome).

Dcp\Ui\ItemMenu setBeforeContent(string $htmtText)

setIcon

La méthode setIcon() permet d'ajouter une icône avant le texte.

Dcp\Ui\ItemMenu setIcon(string $imagePath, int $imageWidth = 12)

4.7.2.1.4 Tooltip de menu

Dcp\Ui\ItemMenu setTooltipLabel(string $tooltipLabel, bool $html=true)

La méthode setTooltipLabel() permet d'ajouter un texte (brut ou html) comme tooltip qui sera affiché au survol de l'élément.

4.7.2.1.5 Attributs personnalisés sur le menu

Dcp\Ui\ItemMenu setHtmlAttribute(string $attrid, string $value)

La méthode setHtmlAttribute() permet d'ajouter des attributs html quelconque comme par exemple une classe ou des données spécifiques.

Exemple :

public function getMenu_(\Doc $document) {
        $myMenu=new \Dcp\ui\BarMenu();
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myFirstMenu",
            ___("My label", "my")
        );
        $myItem->setUrl("http://www.example.net/?a={{document.properties.id}}");
 
        // Utilisation de caractère fontawesome
        $myItem->setBeforeContent('<div class="fa fa-cog" />');
 
        $myMenu->appendElement($myItem);
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myHelpMenu"
        );
        $myItem->setUrl("?app=MY&action=HELP");
 
        // Utilisation d'un label gras et rouge
        $myItem->setHtmlLabel('<strong style="color:red">HELP</strong> : ');
 
        // Utilisation d'une icône
        $myItem->setIcon("MY/Images/myHelp.png");
 
        // ajout d'une classe personnalisée
        $myItem->setHtmlAttribute("class","my--menu-help");
 
        $myMenu->appendElement($myItem);
 
        return $myMenu;
    }

4.7.2.1.6 Confirmation d'un menu

Un élément de menu peut demander une confirmation avant d'être envoyé. La confirmation est indiquée par la méthode useConfirm().

Dcp\Ui\ItemMenu useConfirm(string $question,
        Dcp\Ui\MenuConfirmOptions $dialogOptions=null)

Une fenêtre de dialogue modale est affichée avec la question et deux boutons : un bouton de confirmation et un bouton d'annulation.

Arguments :

$question

Un fragment HTML qui contient la question de confirmation.

$dialogOptions

un objet Dcp\Ui\MenuConfirmOptions.

Cet objet a les propriétés de configuration suivantes :

title

Fragment HTML pour le titre de la fenêtre de dialogue (texte variable) Les variables utilisables sont les propriétés du document.

windowWidth

Largeur de la fenêtre (il est nécessaire d'indiquer l'unité)

windowHeight

Hauteur de la fenêtre (il est nécessaire d'indiquer l'unité)

confirmButton

Texte brut du bouton de confirmation ("Confirmer" par défaut) (texte variable) Les variables utilisables sont les propriétés du document.

cancelButton

Texte brut du bouton d'annulation ("Annuler" par défaut) (texte variable) Les variables utilisables sont les propriétés du document.

Exemple extrait de menu de suppression de document :

$item = new ItemMenu("delete", ___("Delete", "UiMenu") , "#action/document:delete");
$item->setTooltipLabel(___("Put document to the trash", "UiMenu"));
 
$confirmOption = new MenuConfirmOptions();
$confirmOption->title = ___("Confirm deletion of {{{document.properties.title}}}");
$confirmOption->confirmButton = ___("Confirm deletion", "UiMenu");
$confirmOption->windowWidth = "350px";
$confirmOption->windowHeight = "150px";
 
$item->useConfirm(sprintf(___("Sure delete %s ?", "UiMenu") , $document->getHtmlTitle()) , $confirmOption);
$item->setBeforeContent('<div class="fa fa-trash-o" />');
$menu->appendElement($item);

4.7.2.2 Liste d'éléments de menu

Un menu peut contenir des éléments simples ou des listes d'éléments (sous-menus).

Une liste d'éléments de menu est définie par un objet de la classe Dcp\Ui\ListMenu.

4.7.2.2.1 Construction

Dcp\Ui\ListMenu __construct(string $identifier,
                            string $label = '')

Arguments :

identifier

Identifiant du menu : Il doit être unique dans la barre de menu.

label

(optionnel): Texte brut affiché sur la liste de menu

4.7.2.3 Liste dynamique d'éléments de menu

La liste dynamique est une liste d'éléments qui est constituée sur le serveur à chaque ouverture de la liste.

Une liste dynamique d'éléments de menu est définie par un objet de la classe Dcp\Ui\DynamicMenu.

4.7.2.3.1 Construction

Dcp\Ui\DynamicMenu __construct(string $identifier,
                               string $label = '')

Arguments :

identifier

Identifiant du menu : Il doit être unique dans la barre de menu.

label

(optionnel): Texte brut affiché sur la liste de menu.

4.7.2.3.2 Génération de la liste

La méthode setContent() permet d'indiquer la méthode qui sera appelée à chaque ouverture de la liste.

Dcp\Ui\DynamicMenu setContent(\Closure $definition)

L'argument $definition est une méthode qui a comme argument l'objet Dcp\Ui\ListMenu en cours. Les éléments de la liste dynamique doivent être ajoutés dans cette liste.

Exemple : Affichage des 10 dernières notes modifiées.

class AllRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getMenu(\Doc $document) {
        $menu = parent::getMenu($document);
        $lastNoteList = new \Dcp\Ui\DynamicMenu("lastNotes", "Dernières notes");
        $lastNoteList->setContent(function (\Dcp\Ui\ListMenu & $menu) use ($document)
        {
            $s=new \SearchDoc("", "MY_NOTES");
            $s->setSlice(10);
            $s->setOrder("revdate desc");
            $s->setObjectReturn(true);
            $dl=$s->search()->getDocumentList();
            foreach ($dl as $doc) {
                $myNote = new \Dcp\Ui\ItemMenu("doc".$doc->id, $doc->getHtmlTitle());
                $myNote->setUrl(sprintf("#action/document:load:%d",$doc->initid));
                $myNote->setIcon($doc->getIcon());
                $menu->appendElement($myNote);
            }
        });
        $menu->appendElement($lastNoteList);
        return $menu;
    }
}

4.7.2.4 Séparateur

Un élément texte peut être ajouté pour séparer les autres éléments d'une liste ou de la barre de menu.

Un séparateur est défini par un objet de la classe Dcp\Ui\SeparatorMenu.

4.7.2.4.1 Construction

Dcp\Ui\SeparatorMenu __construct(string $identifier, 
                                 string $label = '')

Arguments :

identifier

Identifiant du menu : Il doit être unique dans la barre de menu.

label

(optionnel): Texte brut affiché sur le séparateur.

Les méthodes applicables sont les mêmes que celle du formatage d'un élément simple.

Exemple :

$myItem = new \Dcp\Ui\SeparatorMenu(
    "mySeparator",
    ___("Séparateur", "my")
);
$myItem->setBeforeContent('<div class="fa fa-cog" />');
$menu->appendElement($myItem);

4.7.3 Intégration d'éléments dans un menu

Les classes Dcp\Ui\Barmenu et Dcp\Ui\ListMenu sont des listes d'éléments. À ce titre, elles permettent de gérer les éléments les composant.

4.7.3.1 Ajout d'un élément en fin de liste

L'ajout d'un élément en fin de liste est réalisé par la méthode appendElement().

Dcp\Ui\Barmenu|ListMenu|DynamicMenu appendElement(Dcp\Ui\ElementMenu $elMenu)

Cette méthode ajoute un élément simple ou une autre liste afin de créer des sous-listes.

4.7.3.2 Ajout d'un élément à une position donnée

La méthode insertBefore() insère le nouvel élément avant l'élément indiqué.

Dcp\Ui\Barmenu|ListMenu|DynamicMenu insertBefore(string $menuId, Dcp\Ui\ElementMenu $elMenu)

L'argument $menuId est l'identifiant de l'élément avant lequel le nouvel élément sera est inséré.

La méthode insertAfter() insère le nouvel élément après l'élément indiqué.

Dcp\Ui\Barmenu|ListMenu|DynamicMenu insertAfter(string $menuId, Dcp\Ui\ElementMenu $elMenu)

L'argument $menuId est l'identifiant de l'élément après lequel le nouvel élément sera est inséré.

Exemple :

Trois menus affichés dans une liste affichée en dernier dans la barre de menu.

public function getMenu(\Doc $document) {
    $menu = parent::getMenu($document);
 
    $myList = new \Dcp\Ui\ListMenu("myCustomList", ___("Custom Menu", "my"));
    $myList->setIcon("Images/app_switcher.png");
 
    $myItem = new \Dcp\Ui\ItemMenu("myTest", ___("My label", "my"));
    $myItem->setUrl("?app=TEST&ction=X&id={{document.properties.id}}");
    $myList->appendElement($myItem);
 
    $myItem = new \Dcp\Ui\ItemMenu("myAlert", ___("My alert", "my"));
    $myItem->setUrl("#action/my:myOptions");
    $myList->appendElement($myItem);
 
    $myItem = new \Dcp\Ui\ItemMenu("myHelp", ___("My help", "my"));
    $myItem->setUrl("#action/my:myHelp");
    $myList->insertBefore("myAlert", $myItem);
 
    $menu->appendElement($myList);
    return $menu;
}

4.7.3.3 Suppression d'un élément

La méthode removeElement()` retire un élément de la liste.

Dcp\Ui\BarMenu|ListMenu removeElement(string $menuId)

L'argument $menuId est l'identifiant de l'élément à retirer.

4.7.4 Surcharge d'un élément de menu

Les éléments de menu contenus dans un objet Dcp\UiBarMenu ou Dcp\Ui\ListMenu sont accessibles au moyen de la méthode getElements(), qui retourne un tableau d'éléments.

Array getElements()

Pour accéder à un élément de menu par son id, on peut utiliser la méthode getElement(). L'élément est alors recherché récursivement à partir de la liste depuis laquelle la méthode est appelée.

Dcp\Ui\BarMenu|ListMenu getElement(string $menuId)

Exemple :

Modifier le menu standard de consultation :

• Déplacer le menu "Modifier" à droite et le renommer "Affichage du formulaire.
• Supprimer le menu "Historique" du menu
• Mettre le fond du menu "Supprimer" en rouge

public function getMenu(\Doc $document) {
    $myMenu=parent::getMenu($document);
 
    $modifyItem=$myMenu->getElement("modify");
    if ($modifyItem) {
        $myMenu->removeElement("modify");
        $modifyItem->setTextLabel("Afficher le formulaire");
        $myMenu->appendElement($modifyItem);
    }
 
    $myMenu->removeElement("historic");
 
    $deleteItem=$myMenu->getElement("delete");
    if ($deletItem) {
        $deleteItem->setHtmlAttribute("style","background-color:red");
    }
 
    return $myMenu;
}

4.7.5 Visibilité des éléments de menu

Les menus déclarés sont affichés et actifs par défaut. Leur visibilités et leur activation peuvent être modifiées.

Ces états de menu peuvent être ensuite manipulés par le client afin d'inhiber ou désinhiber les menus en fonction des actions sur l'interface.

Dcp\Ui\ElementMenu setVisibility(string $visibility)

Les visibilités possibles sont :

• Dcp\Ui\ElementMenu::VisibilityVisible : Visible et actif (par défaut)
• Dcp\Ui\ElementMenu::VisibilityHidden : Non visible
• Dcp\Ui\ElementMenu::VisibilityDisabled : Visible mais non actif

La visibilité est applicable aux éléments simples ou aux listes.

Exemple : Inhibition de la liste myCustomList si l'attribut my_level du document vaut 44.

public function getMenu(\Doc $document) {
    $menu = parent::getMenu($document);
 
    $myList = new \Dcp\Ui\ListMenu("myCustomList", ___("Custom Menu", "my"));
    if ($document->getValue("my_level") === "44") {
        $myList->setVisibility(\Dcp\Ui\ListMenu::VisibilityDisabled);
    }
    $menu->appendElement($myList);
    return $menu;
}

4.7.6 Menus prédéfinis

4.7.6.1 Rendu de consultation

La classe Dcp\Ui\DefaultView retourne un menu avec les éléments suivants :

4.7.6.2 Rendu de modification

La classe Dcp\Ui\DefaultEdit retourne un menu avec les éléments suivants :

4.7.6.3 Événements prédéfinis

Les événements suivants sont écoutés par défaut pour les menus