# `getMenu`

# Déclaration

La définition du menu d’un Smart Element est indiquée dans la classe de configuration de rendu. Elle est fournie par la méthode IRenderConfig::getMenu().

/**
 * @param Anakeen\Core\Internal\SmartElement $document Smart Element object instance
 * @return BarMenu Menu configuration
 */
public function getMenu(Anakeen\Core\Internal\SmartElement $document) : BarMenu;

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

# Élément de menu simple

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

# Construction

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

# Arguments

id (string)

Identifiant du menu; il doit être unique dans la barre de menu.

label (string) optionnel

Texte brut affiché sur le menu.

url (string) optionnel

URL cible du menu.

# Exemple

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;

class MyRender extends \Anakeen\Ui\DefaultView
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
  {
    $menu = parent::getMenu($document);

    $item = new ItemMenu("testConfig", ___("Test", "myContext"));
    $item->setUrl(sprintf("/my/example/%s", $document->name ?: $document->id));

    $menu->appendElement($item);
    return $menu;
  }
}

# Définition de l’URL

# Indiquer une URL statique

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

/**
* @param string $url
* @return $this
*/
Anakeen\Ui\ItemMenu setUrl(string $url)

Cette URL peut être relative ou absolue.
L’URL est un template Mustache, et accepte les variables suivantes:

Variable	Description
document.properties.id	Identifiant du Smart Element
document.properties.initid	Identifiant de la lignée de Smart Elements
document.properties.icon	URL de l’icône du Smart Element
document.properties.revision	Numéro de révision
document.properties.title	Titre du Smart Element
document.properties.renderMode	Mode de rendu: `view`, `edit`
document.properties.viewId	Identifiant de la vue de rendu
document.properties.family.id	Identifiant de la Smart Structure
document.properties.family.title	Titre de la Smart Structure
document.properties.family.name	Nom logique de la Smart Structure
document.properties.family.icon	URL de l’icône de la Smart Structure

Exemple

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

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

/**
* Set url target : default is _self
* @param string $target window target
* @param MenuTargetOptions $dialogOptions
* @return $this
*/
Anakeen\Ui\ItemMenu setTarget(string $target, Anakeen\Ui\MenuTargetOptions $dialogOptions = null)

Arguments

target (string)

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 (MenuTargetOptions)

Lorsque la cible est _dialog, la fenêtre de dialogue peut être paramétrée au moyen d’un objet Anakeen\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").

Attention

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ées. Dans ce cas, la fenêtre ouverte ne possède ni menu, ni barre d’adresse.

Exemple

use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\MenuTargetOptions;

$item = new ItemMenu("myMessage", ___("My message", "myContext"));
$targetOption = new MenuTargetOptions();
$targetOption->title = ___("This is my message", "myContext");
$targetOption->windowHeight = "34rem";
$targetOption->windowWidth = "50rem";
$item->setTarget("_dialog", $targetOption);

# É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

<?php
use Anakeen\Core\Internal\SmartElement;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\BarMenu;
class MyRender extends \Anakeen\Ui\DefaultView
{
  public function getJsReferences(SmartElement $document = null)
  {
    $js = parent::getJsReferences($document);
    $js["searchUIEventView"] = "My/Layout/SearchUIEventView.js";

    return $js;
  }

  public function getMenu(SmartElement $document): BarMenu
  {
    $myMenu = parent::getMenu($document);
    $myItem = new ItemMenu("searchview");
    $myItem->setTextLabel(___("consult", "searchUi"));

    $myMenu->removeElement("se_open");
    $myItem->setUrl("#action/previewConsult");
    $myMenu->appendElement($myItem);

    return $myMenu;
  }
}

Fichier SearchUIEventView.js

window.dcp.document.documentController(
        "addEventListener",
        "actionClick",
        {
          name: "previewConsult.viewEvent",
          documentCheck: function isDSearch(document) {
            return documentObject.type === "search" && document.renderMode === "view";
          }
        },
        function eventButtonView(event, documentIbject, data) {
          if (data.eventId === "previewConsult") {
            print("I catched my event");
          }
        }
);

Le contenu du menu est la partie affichée.

Libellé du menu

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

setTextLabel()

Cette méthode indique un libellé texte brut. Les caractères spéciaux seront échappés en entités HTML.

/**
 * set raw text to the menu
 * @param string $label
 * @return $this
 */
Anakeen\Ui\ItemMenu setTextLabel(string $label)

setHtmlLabel()

Cette méthode indique un fragment HTML qui sera affiché.

/**
 * set html fragment to the menu
 * @param string $label
 * @return $this
 */
Anakeen\Ui\ItemMenu setHtmlLabel(string $label)

N.B.

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

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

Cette méthode permet d’ajouter d’un fragment HTML avant le texte (par exemple, un caractère font-awesome).

/**
 * Add a html tag before label
 * Only use if no icon is set
 * @param $htmtText
 * @return $this
 */
Anakeen\Ui\ItemMenu setBeforeContent(string $htmtText)

setIcon

Cette méthode permet d’ajouter une icône avant le texte.

/**
 * @param string $imagePath  local server relative path to image
 * @param int    $imageWidth image width in pixel
 * @return $this
 */
Anakeen\Ui\Item setIcon(string $imagePath, int $imageWidth = 12)

Tooltip de menu

/**
 * Set tooltip on a tab
 * @param string $label tooltip text
 * @param bool $html set to true if it is a html fragment
 *
 * @return $this
 */
Anakeen\Ui\ItemMenu setTooltipLabel(string $label, bool $html=false)

Cette méthode permet d’ajouter un texte (brut ou HTML) comme tooltip qui sera affiché au survol de l’élément.

Attributs personnalisés sur le menu

/**
 * Set a custom html attribute to element menu
 * @param string $attrid Html attribute name
 * @param string $value  attribute value
 * @return $this
 */
Anakeen\Ui\ItemMenu setHtmlAttribute($attrid, $value)

Cette méthode permet d’ajouter des attributs HTML quelconque (par exemple, une classe ou des données spécifiques).

Exemple:

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;

class MyRender extends \Anakeen\Ui\DefaultView
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
  {
    $menu = new BarMenu();

    $myItem = new ItemMenu("myItem", "my item");
    $myItem->setHtmlAttribute("class", "menu--my--item menu--left");
    $myItem->setBeforeContent(sprintf('<div style="color:%s" class="fa fa-square"></div>', "#157EFB"));

    $menu->appendElement($myItem);
    return $menu;
  }
}

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().

/**
 * If text is not null, ask a confirmation before send request
 * @param string|null $question confirmation text
 * @param \Anakeen\Ui\MenuConfirmOptions $options additionnal options (confirmTitle, confirmOkMessage, confirmCancelMEssage, windowWidth, windowHeight)
 * @return $this
 */
Anakeen\Ui\ItemMenu useConfirm(string $question, MenuConfirmOptions $options = 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 (string)

Un fragment HTML qui contient la question de confirmation

options (MenuConfirmOptions)

Un objet Anakeen\Ui\MenuConfirmOptions ayant les propriétés suivantes:

title: Un fragment HTML pour le titre de la fenêtre de dialogue (texte variable). Les variables utilisables sont les propriétés du Smart Element.

windowWidth: Largeur de la fenêtre de dialogue (il est nécessaire d’indiquer l’unité).

windowHeight: Hauteur de la fenêtre de dialogue (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 Smart Element.

cancelButton: Texte brut du bouton d’annulation ("Annuler" par défaut) (texte variable). Les variables utilisables sont les propriétés du Smart Element.

Exemple

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;

class MyRender extends \Anakeen\Ui\DefaultView
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
  {
    $menu = parent::getMenu($document);
    if ($document->canExecuteRoute()) {
      $item = new ItemMenu("executeNow", ___("Execute now", "smart exec"));
      $item->setUrl("#action/task:executeNow");
      $item->useConfirm(sprintf(___("Execute now the task %s", "smart exec"), $document->getTitle()));
      $item->setBeforeContent('<div class="fa fa-cog"></div>');
      $menu->appendElement($item);
    }
    return $menu;
  }
}

# Liste d’éléments de menu

Un menu peut contenir des éléments simples ou des liste d’éléments (sous-menus).
Une liste d’éléments de menu est définie par un objet de la classe Anakeen\Ui\ListMenu.

# Construction

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

# Arguments

identifier (string)

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

label (string) optionnel

Texte brut affiché sur la liste de menu.

# Méthode

La méthode ListMenu::appendElement() permet d’ajouter des éléments de menu dans la liste. Ces éléments peuvent aussi être des listes ce qui affichera des sous-menus.

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\DefaultView;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\ListMenu;
class MyRender extends DefaultView
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
  {
    $menu = parent::getMenu($document);
    $item1 = new ItemMenu("Item1", "Item 1");
    $item2 = new ItemMenu("Item2", "Item 2");
    $list = new ListMenu("List1", "List 1");
    $list->appendElement($item1)->appendElement($item2);
    $menu->appendElement($list);

    return $menu;
  }
}

# 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 Anakeen\Ui\DynamicMenu.

# Construction

Anakeen\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.

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

/**
 * Record definition function
 * @param \Closure $definition
 */
Anakeen\Ui\DynamicMenu setContent(\Closure $definition)

L’argument $définition est une méthode qui a comme argument l’objet Anakeen\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 (MYNOTE) modifiées.

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ListMenu;
use Anakeen\Ui\DynamicMenu;
use Anakeen\Search\SearchElements;
use Anakeen\Ui\ItemMenu;

class MyRender extends \Anakeen\Ui\DefaultConfigViewRender
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
  {
    $menu = parent::getMenu($document);
    $lastNoteList = new DynamicMenu("lastNotes", "Dernières notes");
    $lastNoteList->setContent(function (ListMenu &$menu) use ($document) {
      $s = new SearchElements("MYNOTE");
      $s->setSlice(10);
      $dl = $s->search()->getResults();
      foreach ($dl as $doc) {
        $myNote = new 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;
  }
}

# Fonction associée à un menu

Cette classe d’élement permet d’indiquer la fonction serveur (PHP) appelée lors de la sélection du menu.

La fonction d’éléments de menu est définie par un objet de la classe Anakeen\Ui\CallableMenu.

# Construction

Anakeen\Ui\CallableMenu __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.

La méthode setCallable() permet d’indiquer la méthode qui sera appelée à la sélection du menu.

/**
 * Record definition function
 * @param \Closure $definition
 */
Anakeen\Ui\CallableMenu setCallable(\Closure $callback)

L’argument $callback est la méthode qui sera appelée lors de la sélection du menu.

La fonction appelée doit retourner une réponse avec un objet de la classe Anakeen\Routes\Ui\CallMenuResponse. Cet objet possède les méthodes suivantes :

setMessage(ApiMessage $msg) : message à afficher sur l’interface
getMessage(): ApiMessgae : retourne le message enregistré par setMessage
setReload(bool $doReload) : indique que l’affichage du SmartElement doit être actualisé à la suite de la fonction
needReload():bool : indique si le reload a été demandé
setData(array $data) : autres données à envoyer (pour être traité par un listener js)
getData(): array : retourne les données indiquées par setData

Ce type de menu envoi une requête avec la méthode HTTP PUT pour déclencher le code de la fonction de rappel. La méthode CallableMenu::setMethod() permet de changer cette méthode (GET, POST, ou DELETE).

Par défaut, si la méthode est PUT ou POST, une précondition est effectuée pour s’assurer que l’utilisateur courant possède le droit edit sur le Smart Element courant. Si la méthode est DELETE, le droit delete est contrôlé. Dans tous les cas, le droit view est contrôlé.

La méthode CallableMenu::setUnsafe(true) permet de désactiver les contrôles pour les méthodes PUT, POST (droit "edit") ou DELETE (droit "delete"). Le droit view est toujours contrôlé.

# Exemple

Enregistrement d’un message dans l’historique et affichage d’un message acquittant l’enregistrement.

<?php
use Anakeen\Ui\BarMenu;
use Anakeen\Routes\Core\Lib\ApiMessage;
use Anakeen\Routes\Ui\CallMenuResponse;

class MyRender extends \Anakeen\Ui\DefaultConfigViewRender
{
  public function getMenu(\Anakeen\Core\Internal\SmartElement $smartElement): BarMenu
  {
    $menu = parent::getMenu($smartElement);
    $myMenu = new \Anakeen\Ui\CallableMenu("hello", "Record in history");
    $myMenu->setCallable(function () use ($smartElement): CallMenuResponse {
      $smartElement->addHistoryEntry("Hello");
      $msg = new ApiMessage("A new entry has been recorded into history");
      $response = new CallMenuResponse();
      return $response->setMessage($msg);
    });
    $menu->appendElement($myMenu);
    return $menu;
  }
}

# Menu 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 Anakeen\Ui\SeparatorMenu.

# Construction

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

# Arguments

identifier (string)

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

label (string) optionnel

Texte brut affiché sur le séparateur.

# Exemple

$workflowMenu = new \Anakeen\Ui\SeparatorMenu("workflow", $document->getStepLabel());
$workflowMenu->setBeforeContent(
  sprintf('<div style="color:%s" class="fa fa-square"></div>', $document->getStateColor("transparent"))
);
$workflowMenu->setHtmlAttribute("class", "menu--workflow menu--right");
$menu->appendElement($workflowMenu);

Les classes Anakeen\Ui\BarMenu et Anakeen\Ui\ListMenu sont des listes d’éléments. A ce titre, elles permettent de gérer les éléments des composants.

# 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().

/**
 * Append an new Element at the end of the list
 * @param ElementMenu $elMenu new Element Menu to add
 * @return $this
 */
Anakeen\Ui\BarMenu|ListMenu|DynamicMenu appendElement(Anakeen\Ui\ElementMenu $elMenu)

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

# Ajout d’un élément à une position donnée

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

/**
 * Insert Element before another Element
 * @param string      $index  menu identifier to insert before; if empty insert at first place
 * @param ElementMenu $elMenu new Element Menu to insert
 * @return $this
 * @throws Exception
 */
Anakeen\Ui\BarMenu|ListMenu|DynamicMenu insertBefore($index, ElementMenu $elMenu)

L’argument $index est l’identifiant de l’élément avant lequel le nouvel élément est inséré.

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

/**
 * Insert Element before another Element
 * @param string      $index  menu identifier to insert before
 * @param ElementMenu $elMenu new Element Menu to insert
 * @return $this
 * @throws Exception
 */
Anakeen\Ui\BarMenu|ListMenu|DynamicMenu insertAfter($index, ElementMenu $elMenu)

L’argument $index est l’identifiant de l’élément après lequel le nouvel élément est inséré.

# Exemple

use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;

public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
    $menu = parent::getMenu($document);

    $myList = new ListMenu("myCustomList", ___("Custom Menu", "my"));
    $myList->setIcon("Images/app_switcher.png");

    $myItem = new ItemMenu("myTest", ___("My label", "my"));
    $myItem->setUrl("?app=TEST&ction=X&id={{document.properties.id}}");
    $myList->appendElement($myItem);

    $myItem = new ItemMenu("myAlert", ___("My alert", "my"));
    $myItem->setUrl("#action/my:myOptions");
    $myList->appendElement($myItem);

    $myItem = new ItemMenu("myHelp", ___("My help", "my"));
    $myItem->setUrl("#action/my:myHelp");
    $myList->insertBefore("myAlert", $myItem);

    $menu->appendElement($myList);
    return $menu;
}

# Suppression d’un élément

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

/**
 * Remove en element menu content
 * @param string $index ELement index to remove from list
 * @return $this
 */
Anakeen\Ui\BarMenu|ListMenu|DynamicMenu removeElement(string $index)

L’argument $index est l’identifiant de l’élément à retirer

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

/**
 * Return elements contents in list
 * @return ElementMenu[]
 */
ElementMenu[] 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.

/**
 * Retrieve element content at any recusrion level
 * @param string   $index
 * @param ListMenu $parentElement (ListMenu contains element, null if top level)
 * @return ElementMenu|ItemMenu|ListMenu
 */
ElementMenu|ItemMenu|ListMenu &getElement(string $index, ListMenu &$parentElement = null)

# Exemple

Modifier le menu standard de consultation:

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

use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;

public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
    $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;
}

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

N.B.

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.

/**
 * Define visibility element : visible, hidden or disabled
 * @param string $visibility
 * @return $this
 */
ElementMenu setVisibility(string $visibility)

Les visibilités possibles sont :

Anakeen\Ui\ElementMenu::VisibilityVisible : Visible et actif (par défaut)
Anakeen\Ui\ElementMenu::VisibilityHidden : Non visible
Anakeen\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 le Smart Field my_level du Smart Element vaut 44

use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\ListMenu;

public function getMenu(\Anakeen\Core\Internal\SmartElement $document): BarMenu
    $menu = parent::getMenu($document);

    $myList = new ListMenu("myCustomList", ___("Custom Menu", "my"));
    if ($document->getValue("my_level") === "44") {
        $myList->setVisibility(ListMenu::VisibilityDisabled);
    }
    $menu->appendElement($myList);
    return $menu;
}

# Menus prédéfinis

# Rendu de consultation

Identifiant menu	Description	Note
`modify`	Modifier (Affichage du formulaire
`delete`	Suppression du Smart Element
`restore`	Restauration du Smart Element
`historic`	Affichage de l’historique
`advanced.properties`	Affichage des propriétés
`advanced.security.lock`	Verrouillage du Smart Element	pas implémenté
`advanced.security.unlock`	Déverrouillage du Smart Element	pas implémenté
`workflow`	Liste des transitions possibles

# Rendu de modification

Identifiant menu	Description	Note
`save`	Enregistrement du Smart Element
`save!`	Enregistrement forcé	pas implémenté
`create`	Création et enregistrement
`create!`	Création forcée	pas implémenté
`close`	Fermeture(Affichage en mode consultation)
`workflow`	Nom de l’activité(pas de boutons)

# Événements prédéfinis

URL	Description
`#action/document.close:<viewId>`	Ouverture avec le rendu "viewId" (optionnel: consultation par défaut)
`#action/document.create`	Enregistrement d’un nouveau Smart Element
`#action/document.delete`	Suppression du Smart Element
`#action/document.edit`	Ouverture en mode modification
`#action/document.history`	Affichage de l’historique
`#action/document.load:<elementId>:<viewId>`	Ouverture d’un autre Smart Element "elementId"
`#action/document.propertiers`	Affichage des propriétés
`#action/document.save`	Enregistrement du Smart Element
`#action/document.restore`	Restauration du Smart Element
`#action/document.selectTab:<tabId>`	Sélection d’un onglet de Smart Element

# Menu d’envoi de courriel (mail)

Les demandes d’envoi de courriel peuvent être déclenchées par un menu en utilisant une route dédiée. La Smart Structure MAIL possède une interface pour afficher un formulaire d’envoi.

# Formulaire d’envoi

La route /api/v2/ui/mail/form/{id}.html affiche le formulaire de demande d’envoi. L’argument id est l’identifiant du Smart Element à envoyer. Il peut contenir le nom logique où l’identifiant numérique (lié à la révision voulue).

Objectif

Ce menu permet d’envoyer par courriel un lien vers le document souhaité.

L’envoi d’un courriel est basé sur les modèles de mails. La route du formulaire utilise par défaut le modèle de mail identifié par le paramètre de structure mail_tpl_default (Modèle par défaut) de la Smart Structure MAIL. Sa valeur initiale est MAILTEMPLATE_DEFAULT. Ce modèle par défaut, utilise le mot-clef [V_TITLE] pour construire le lien dans le mail.

La route a 3 paramètres optionnels :

Nom du paramètre	Description
`mailTemplate`	Référence du modèle de mail (nom logique ou référence numérique) (par défaut : paramètre de structure `mail_tpl_default` )
`selink`	Url utilisée pour le lien utilisé dans le mot-clef `[V_TITLE]` (par défaut : paramètre de configuration `CORE_MAILACTION`)
`keys`	(json encoded) Tableau de clefs/valeurs supplémentaires applicables au modèle de mail

Le formulaire d’envoi est généré avec la configuration du modèle de mail. L’utilisateur peut modifier les parties destinataires, sujet et corps du message. Il ne peut pas modifier l’emetteur ni les fichiers joints définis dans le modèle de mail.

Sécurité

Le formulaire d’envoi ne peut utiliser que des modèles de mails que l’utilisateur courant peut accéder (droit view).

L’envoi ne peut être effectué que si le droit send du smart element à envoyer est accordé à l’utilisateur courant.

# Choix des destinataires

Les destinataires disponibles dans l’interface d’envoi de courriel sont les Smart Elements :

Qui appartiennent à une Smart Structure qui possède comme tag MAILRECIPIENT avec une valeur à true.
Dont le comportement de la structure implémente l’interface IMailRecipient.

Par défaut aucune structure n’a de tag MAILRECIPIENT à true. Si vous souhaitez ajouter les utilisateurs (Smart Structure IUSER) en destinataire, vous devez ajouter le tag à la structure. Pour cela, importez à l’installation le fichier suivant :

<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
  <smart:structure-configuration name="IUSER">
    <smart:tag name="MAILRECIPIENT">true</smart:tag>
  </smart:structure-configuration>
</smart:config>

Pour qu’une autre structure soit destinataire de courriels, vous devez également implémenter l’interface IMailRecipient au niveau de sa classe de comportement. Par exemple pour une Smart Structure MAIL_RECEIVER on peut définir la classe de comportement suivante :

<?php

use Anakeen\Core\IMailRecipient;
use SmartStructure\Fields\MailReceiver;

class MailReceiverBehavior extends  \Anakeen\SmartElement implements IMailRecipient
{

    public function getMail()
    {
        return $this->getAttributeValue(MailReceiver::mail_field)
    }

    public function getMailTitle()
    {
        $firstName = $this->getAttributeValue(MailReceiver::firstname_field);
        $lastName = $this->getAttributeValue(MailReceiver::lastname_field);
        $fullName = trim($firstName . ' ' . $lastName);
        return sprintf('"%s" <%s>', $fullName, $this->getMail());
    }

    public static function getMailAttribute()
    {
        return MailReceiver::mail_field;
    }
}

Pour afficher le formulaire d’envoi, un élément de menu est configuré avec l’url de la route du formulaire d’envoi. Le formulaire est affiché dans cet exemple dans une boite de dialogue.

<?php
namespace My\Renders;

use Anakeen\Core\Internal\SmartElement;
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\MenuTargetOptions;

class SendMailMenu extends \Anakeen\Ui\DefaultView
{
  public function getMenu(SmartElement $se): BarMenu
  {
    $menu = parent::getMenu($se);
    if (!$se->control("send")) {
      // ---------------------------------------
      // Mail standard (par défaut)
      $mail = new ItemMenu("my-mail");

      $url = sprintf("/api/v2/ui/mail/form/%d.html", $se->id);
      $mail->setUrl($url);

      $option = new MenuTargetOptions();
      $option->windowHeight = 400;
      $option->windowWidth = 700;
      $mail->setTarget("_dialog", $option);
      $mail->setTextLabel("Envoyer");
      $mail->setBeforeContent('<i class="fa fa-envelope"></i>');
      $menu->appendElement($mail);
    }
    return $menu;
  }
}

Le paramètre d’url selink peut contenir des parties variables entre %. La variable est une propriété du Smart Element (écrite en majuscule).

Encodage

Ce paramètre doit être encodé pour être correctement interprété

<?php

namespace My\Renders;

use Anakeen\Core\Internal\SmartElement;
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\MenuTargetOptions;

class SendMailMenu extends \Anakeen\Ui\DefaultView
{
  public function getMenu(SmartElement $se): BarMenu
  {
    $menu = parent::getMenu($se);
    if (!$se->control("send")) {
      $mail = new ItemMenu("zou-mail-tot");
      // Lien vers https://www.example.net/%ID%.html
      $url = sprintf("/api/v2/ui/mail/form/%d.html?selink=%s", $se->id, urlencode("https://www.example.net/%ID%.html"));
      $mail->setUrl($url);

      $option = new MenuTargetOptions();
      $option->windowHeight = 400;
      $option->windowWidth = 700;
      $mail->setTarget("_dialog", $option);
      $mail->setTextLabel("Lien particulier");
      $mail->setBeforeContent('<i class="fa fa-envelope"></i>');
      $menu->appendElement($mail);
    }
    return $menu;
  }
}

Le mail ci-dessous a 3 variables spécifiques [my_you], [my_name] et [my_now].

<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0"
              xmlns:mail="https://platform.anakeen.com/4/schemas/mailtemplate/1.0">
    <mail:mailtemplate xmlns:mail="https://platform.anakeen.com/4/schemas/mailtemplate/1.0" name="MY_MESSAGE"
                       label="Lien activé" structure="">
        <mail:from>
            <mail:config-parameter ns="Core" label="">SMTP_FROM</mail:config-parameter>
        </mail:from>
        <mail:recipients>
            <mail:recipient dest="cc">
                <mail:address>bigboss@example.net</mail:address>
            </mail:recipient>
        </mail:recipients>
        <mail:subject>Lien de [my_you]</mail:subject>
        <mail:savecopy>false</mail:savecopy>
        <mail:use-html-anchor>true</mail:use-html-anchor>
        <mail:body content-type="html"><![CDATA[

	<p>Bonjour [my_name]</p>

    <p>Aujourd'hui le <b>[my_now]</b>, vous pouvez accéder à [V_TITLE].</p>

]]></mail:body>
    </mail:mailtemplate>
</smart:config>

Le menu ci-dessous affiche le formulaire d’envoi avec le modèle de mail MY_MESSAGE et en précisant les 3 variables spécifiques.

<?php

namespace Anakeen\SmartStructures\UiTest\TstUiAllType\Renders;

use Anakeen\Core\ContextManager;
use Anakeen\Core\Internal\SmartElement;
use Anakeen\Ui\BarMenu;
use Anakeen\Ui\ItemMenu;
use Anakeen\Ui\MenuTargetOptions;

class SendMailMenu extends \Anakeen\Ui\DefaultView
{
  public function getMenu(SmartElement $se): BarMenu
  {
    $menu = parent::getMenu($se);
    if (!$se->control("send")) {
      $mail = new ItemMenu("custom-send");
      $url = sprintf(
        "/api/v2/ui/mail/form/%d.html?mailTemplate=%s&keys=%s",
        $se->id,
        "MY_MESSAGE",
        urlencode(
          json_encode([
            "my_you" => ContextManager::getCurrentUser()->getAccountName(),
            "my_name" => "John",
            "my_now" => strftime("%d %B %Y")
          ])
        )
      );
      $mail->setUrl($url);

      $option = new MenuTargetOptions();
      $option->windowHeight = 500;
      $option->windowWidth = 700;

      $mail->setTarget("_dialog", $option);
      $mail->setTextLabel("Lien personnel");
      $mail->setBeforeContent('<i class="fa fa-envelope"></i>');

      $menu->appendElement($mail);
    }
    return $menu;
  }
}

← getLabel getOptions →

# getMenu

# Déclaration

# Élément de menu simple

# Construction

# Arguments

# Exemple

# Définition de l’URL

# Indiquer une URL statique

# Indiquer la cible du menu

# Émettre un événement

# Contenu du menu

# Liste d’éléments de menu

# Construction

# Arguments

# Méthode

# Liste dynamique d’éléments de menu

# Construction

# Exemple

# Fonction associée à un menu

# Construction

# Exemple

# Menu Séparateur

# Construction

# Arguments

# Exemple

# Intégration d’éléments dans un menu

# Ajout d’un élément en fin de liste

# Ajout d’un élément à une position donnée

# Exemple

# Suppression d’un élément

# Surcharge d’un élément de menu

# Exemple

# Visibilité des éléments de menu

# Exemple

# Menus prédéfinis

# Rendu de consultation

# Rendu de modification

# Événements prédéfinis

# Menu d’envoi de courriel (mail)

# Formulaire d’envoi

# Choix des destinataires

# Menu d’envoi standard

# Menu d’envoi avec un lien personnalisé

# Menu d’envoi avec un modèle de mail spécifique

# `getMenu`