Fonctionnement de l’interpreteur des actions Epicraft

Edit me

Fonctionnement général

L’interpreteur est basé sur une déclinaison du ScriptPlayer de Voozanoo4. Comme celui-ci se base sur une gestion de XML, toutes les actions vont d’abord être transformées en XML pour ainsi être traité par la suite. La transformation se fait dans la fonction getXMLScriptPlayerFromJson du PublicationManager.

C’est également lors de cette transformation que va être déterminé le script (action au sens ScriptPlayer) qui va être utilisé. Toutes les actions envoyées par epicraft possèdent les attributs operator et type. Ces deux éléments vont être concaténés pour déterminer le bon script à utiliser.

Valeurs possibles d’operator:

  • add
  • update (alter depuis epicraft, mais renommé à la volée dans l’interpreteur)
  • delete (remove depuis epicraft, mais renommé à la volée dans l’interpreteur)
  • archive

Valeurs possibles du type:

  • component
  • comment
  • custom
  • datasource
  • dico
  • meta
  • relation
  • resource

transformation action epicraft

Tous les scripts sont stockés dans le dossier src/library/Resource/XML/ScriptPlayer/Action/Editor

La manière dont fonctionne les scripts est (en général):

  • travail sur les paramètres de l’action.
  • recherche de l’identifiant dans les formulaires existants de la base de donnée du projet.
  • si un travail doit être effectué “en dehors” de la balise, ce sera fait ici.
  • instanciation d’un “widget” qui sera celui qui effectuera les modifications sur la balise associée à l’identifiant epicraft.
  • sauvegarde en cache du XML résultant de toutes ces manipulations.

Les “widgets”

src/library/Resource/XML/Layout/Widget

Chaque classe de “widget” est associé à un type de balise. Cela s’étend à plus d’éléments que ceux dans la partie <layout>, on retrouve également un widget pour la gestion des <dataquery>, un pour la <config>, et même un qui est dédié aux traitements des actions sur la page (au sens epicraft).

Trois fonctions clés:

  • create, appelé par le script AddComponent.
  • update, appelé par le script UpdateComponent.
  • setTemplate, l’étape qui va terminer la génération du XML pour la balise.

Le cycle de transformation est celui-ci:

  • lecture du XML de la balise dans le formulaire pour retrouver les paramètres epicraft qui ont servi à sa construction.
  • fusion de ces paramètres avec les nouveaux passés dans l’action.
  • reconstruction du XML de la balise.

Pour faciliter le fonctionnement global, on passe par ces fonctions:

  • _mapAttributes, transforme les paramètres de l’action pour:
    • ne garder que ceux qui concernent notre composant
    • utilise le tableau $this->_aPossiblesAttributes pour opérer des transformations sur ceux-ci
  • getVoo4OptionsFromParameters, utilisé par _mapAttributes, cette fonction permet de gérer les transformations epicraft->voo4
  • getEpicraftPropertiesFromVoo4Node, fonction qui permet de faire l’inverse de getVoo4OptionsFromParameters, elle utilise le contenu du XML Voo4 pour reconstruire les paramètres epicraft

Configuration

Pour la suite, on va prendre en exemple une action (simplifiée) comme celle-ci:

{
  "operator": "alter",
  "id": "ggzcybpvmf1619440122135",
  "type": "component",
  "parameters": {
    "attributes": {
      "label": "mon label"
    }
  }
}

Simple recopie

$this->_aPossiblesAttributes = array(
  'label'
);

Avec cette configuration, l’attribut label récupéré dans l’action d’epicraft sera directement recopié sans modification dans la balise XML.

<ma_balise label="mon label" />

Changement de clé

$this->_aPossiblesAttributes = array(
  'label' => 'title'
);
// une autre solution, si besoin
$this->_aPossiblesAttributes = array(
  'label' => array(
    'key' => 'title'
  )
);

Avec ces configurations, l’attribut label sera renommé title dans le XML.

<ma_balise title="mon label" />

Recodage de la valeur

Epicraft vers Voo4
$this->_aPossiblesAttributes = array(
  'label' => array(
    'key' => 'title',
    'getVoo4ValueFromEpicraft' => function( $sValue, $aParams, $oNode ) {
      return strtoupper( $sValue );
    }
  )
);

Avec cette configuration:

  • l’atribut label de l’action d’epicraft est renommé en title pour le XML.
  • la valeur de l’attribut label est transformé avant son stockage dans le XML (dans cet exemple on met en majuscule).
<ma_balise title="MON LABEL" />
Voo4 vers Epicraft
$this->_aPossiblesAttributes = array(
  'label' => array(
    'key' => 'title',
    'getVoo4ValueFromEpicraft' => function( $sValue, $aParams, $oNode ) {
      return strtoupper( $sValue );
    },
    'getEpicraftValueFromVoo4' => function( $sValue ) {
      return strtolower( $sValue );
    }
  )
);

Le but de la fonction getEpicraftValueFromVoo4 est de pouvoir retrouver la valeur epicraft.

Dans le cycle de vie du widget, lors d’une mise à jour d’un composant existant, on va:

  • lire le XML pour retrouver les paramètres epicraft.
  • fusionner ces anciens paramètres avec les nouveaux de l’action en cours.
  • transformer ces paramètres pour le XML Voo4.

C’est pour faciliter la fusion que getEpicraftValueFromVoo4 existe.

Valeur par défaut

$this->_aPossiblesAttributes = array(
  'label',
  'mandatory' => array(
    'defaultValue' => 'false'
  )
);

Permet d’avoir une valeur par défaut pour un attribut lorsque celui-ci n’est pas définit dans l’action.

<ma_balise label="mon label" mandatory="false" />

Nettoyage

$this->_aPossiblesAttributes = array(
  'label' => array(
    'getVoo4ValueFromEpicraft' => function( $sValue, $aParams, $oNode ) {
      return $sValue === 'mon label' ? '' : $sValue;
    },
    'removeIfNull' => true
  ),
);

Permet de retirer l’attribut XML si la valeur à stocker est considéré vide (empty( $mValue ) && $mValue !== '0'). Dans cet exemple, on recode la valeur pour forcer son nettoyage.

<ma_balise />