Comment s'abonner à un champ relationnel ? À partir de la version 2023.1.1

Un abonnement à un champ relationnel permet d'être notifié en cas de modification du Smart Element référencé dans celui-ci.

Recommandation

Si vous n’êtes pas familier avec les abonnements et leur fonctionnement, il est fortement recommandé de lire la documentation associée.

Il est également recommandé de se familiariser avec les cycles de vie ainsi que les hooks.

Prérequis

Afin de pouvoir suivre ce guide, il faut préalablement avoir créé une ou plusieurs Smart Structure(s).

Prérequis techniques

Anakeen Platform 4 - 2023.1.1

Définir un nouvel abonnement

Créons une nouvelle Smart Structure CARTE contenant :

un titre : carte_title
la liste des menus disponibles dans notre restaurant : carte_menu
la date de fin de disponibilité de la carte : carte_date_fin

npx @anakeen/anakeen-cli createSmartStructure --sourcePath . --name CARTE

Complétons son fichier de configuration src/vendor/Cogip/Restauratec/SmartStructures/Carte/100-CarteStructure.xml :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="CARTE" label="Carte">
        <smart:icon file="carte.png"/>
        <smart:class>Cogip\Restauratec\SmartStructures\Carte\CarteBehavior</smart:class>
        <smart:fields>
            <smart:field-set name="carte_frame" type="frame" access="ReadWrite" label="Carte">
                <smart:field-text name="carte_title" needed="true" is-title="true" access="ReadWrite" label="Libellé"/>
                <smart:field-date name="carte_date_fin" needed="true" access="ReadWrite" label="Disponible jusqu'au"/>
                <smart:field-set name="carte_composition" type="array" access="ReadWrite" label="Composition de la carte">
                    <smart:field-docid access="ReadWrite" name="carte_menu" label="Menu" relation="MENU"/>
                </smart:field-set>
            </smart:field-set>
        </smart:fields>
        <smart:hooks/>
        <smart:defaults/>
    </smart:structure-configuration>
</smart:config>

Nous souhaitons être prévenus en cas de modification d'un des menus référencés pour procéder à une relecture avant de publier la mise à jour de la carte.

Ajoutons, dans un premier temps, un cycle de vie simple à notre Smart Structure CARTE. Celui-ci contiendra deux étapes :

Validée
À relire

npx @anakeen/anakeen-cli createWorkflow --sourcePath . --smartStructureName WFAM_CARTE --smartElementName WDOC_CARTE --associatedSmartStructure CARTE

Et renseignons nos deux états et les transitions associées dans src/vendor/Cogip/Restauratec/SmartStructures/Carte/CarteWorkflows/WfamCarteWorkflow/WfamCarteGraph.xml:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0" xmlns:workflow="https://platform.anakeen.com/4/schemas/workflow/1.0">

    <workflow:graph ns="GDC" name="WFAM_CARTE" label="Graphe wfam_carte">

        <workflow:steps>
            <workflow:step name="wfam_carte_e1" state-label="À relire" initial="true"/>
            <workflow:step name="wfam_carte_e2" state-label="Validée"/>
        </workflow:steps>

        <workflow:transitions>
            <workflow:transition name="t_wfam_carte_e1_e2" from="wfam_carte_e1" to="wfam_carte_e2" label="Valider"/>
            <workflow:transition name="t_wfam_carte_e2_e1" from="wfam_carte_e2" to="wfam_carte_e1" label="Relire"/>
        </workflow:transitions>

    </workflow:graph>
</smart:config>

Attention

Pensez à déployer vos modifications.

make deploy

La Smart Structure CARTE suit désormais le cycle de vie suivant : À relire ⇄ Validée. À relire est l'étape initiale.

Il ne reste plus qu'à s'abonner au champ relationnel carte_menu pour être prévenu des modifications de chacun des menus sélectionnés et effectuer le changement d'étape vers À relire le cas échéant.

Définissons donc un nouvel abonnement dans src/vendor/Cogip/Restauratec/SmartStructures/Carte/100-CarteStructure.xml :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="CARTE" label="Carte">
        <smart:icon file="carte.png"/>
        <smart:class>Cogip\Restauratec\SmartStructures\Carte\CarteBehavior</smart:class>
        <smart:fields>
            <smart:field-set name="carte_frame" type="frame" access="ReadWrite" label="Carte">
                <smart:field-text name="carte_title" needed="true" is-title="true" access="ReadWrite" label="Libellé"/>
                <smart:field-date name="carte_date_fin" needed="true" access="ReadWrite" label="Disponible jusqu'au"/>
                <smart:field-set name="carte_composition" type="array" access="ReadWrite" label="Composition de la carte">
                    <smart:field-docid access="ReadWrite" name="carte_menu" label="Menu" relation="MENU"/>
                </smart:field-set>
            </smart:field-set>
        </smart:fields>
        <smart:hooks/>
        <smart:defaults/>
        <smart:subscriptions>
            <smart:subscribe relation-field="carte_menu"/>
        </smart:subscriptions>
    </smart:structure-configuration>
</smart:config>

Enregistrons le changement d'étape sur le Smart Hook ONSUBSCRIPTIONEVENT qui sera déclenché dès réception d'une notification de changement(s) concernant un des menus référencés. L'enregistrement de cette méthode se fait dans le fichier de comportement src/vendor/Cogip/Restauratec/SmartStructures/Carte/CarteBehavior.php.

<?php

namespace Anakeen\SmartStructures\Carte;

use SmartStructure\Fields\Carte as CarteFields;
use Anakeen\SmartHooks;

class CarteBehavior extends \Anakeen\SmartElement
{
    public function registerHooks()
    {
        parent::registerHooks();
        $this->getHooks()->addListener(
            SmartHooks::ONSUBSCRIPTIONEVENT,
            function (string $smartField, int $publisherSmartElementId) {
                switch ($smartField) {
                    case "carte_menu":
                        // le menu $publisherSmartElementId référencé dans le champ "carte_menu" a été modifié
                        if ($this->getState() === "wfam_carte_e2") {
                            return $this->setState("wfam_carte_e1");
                        }
                        break;
                }
                return "";
            }
        );
    }
}

Attention

Les notifications sont traitées de manière asynchrone par le module @anakeen/workers. Il est donc possible d'avoir un léger délai de traitement avant de constater le changement d'étape.

Déployons nos modifications :

make deploy

Tester le lien d'abonnement et le comportement suite à une notification

Rendons-nous sur le formulaire de création de Smart Element de la Smart Structure CARTE et créons une nouvelle carte avec deux ou trois menus :

Création d'une CARTE

Notre carte est à l'étape initiale À relire, passons-la à l'étape Validée :

Passage à l'étape 'Validée'

Consultons ensuite un des menus référencés, modifions un champ quelconque et sauvegardons :

Modification d'un menu

Retournons sur notre carte :

Modification d'un menu

Elle est bien revenue à l'étape À relire 🎉 !

Pour aller plus loin

Configurez un envoi de mail automatique pour prévenir les directeurs de ce changement d'étape et de la nécessité d'effectuer une relecture. Le guide est disponible ici.

Et ensuite ?

Comment définir les accès d’un Smart Element ?

# Comment s'abonner à un champ relationnel ? À partir de la version 2023.1.1

# Prérequis

# Prérequis techniques

# Définir un nouvel abonnement