Introduction

Les objets "ActionGroup" ont pour objectif de regrouper les actions par typologie (actions d'administration, actions front office, ....)

Ces objets sont stockés dans les répertoires actiongroups/ des modules.

Les fichiers qui déclarent les ActionGroup sont en minuscules et se nomment "nom.actiongroup.php".

Dans un fichier "nom.actiongroup.php" on trouvera la déclaration de la classe "ActionGroupNom?"

exemple

class ActionGroupNom extends CopixActionGroup {
}

CopixActionGroup est la classe de base des ActionGroup.

Les actions

Le rôle principal des ActionGroup est de répondre à la demande de l'internaute, demande qui arrive sous la forme d'une URL.

Les Actions sont implémentées dans les ActionGroups? par des méthodes préfixées de "process".

class ActionGroupExemple extends CopixActionGroup {
   function processUneAction (){
      //..code d'une action
   }
}

Routage par défaut

Les ActionGroup sont sollicités par un processus de routage qu'il est important de bien comprendre pour la suite.

Pour rappel, les URL Copix (générées et traitées avec CopixUrl) sont composées de 3 éléments :

• Le module (qui va déterminer le "chemin d'exécution")
• Le groupe (qui va déterminer l' ActionGroup à utiliser)
• L'action (qui va déterminer la méthode à appeler dans l'ActionGroup)

Exemple 1

index.php?module=mon_module&group=mon_groupe&action=mon_action

Ici, on va instancier l' ActionGroup ActionGroupMon?_Groupe situé dans le module mon_module (emplacement exact : chemin_du_module/mon_module/actiongroup/mon_groupe.actiongroup.php) et exécuter la méthode processMon_Action ()

Exemple 2

index.php?module=mon_module&group=mon_groupe&action=mon_autre_action

Ici, on va instancier l' ActionGroup ActionGroupMon?_Groupe situé dans le module mon_module (emplacement exact : chemin_du_module/mon_module/actiongroup/mon_groupe.actiongroup.php) et exécuter la méthode processMon_Autre_Action ()

Exemple 3

index.php?module=mon_module&group=mon_autre_groupe&action=mon_action

Ici, on va instancier l' ActionGroup ActionGroupMon?_Autre_Groupe situé dans le module mon_module (emplacement exact : chemin_du_module/mon_module/actiongroup/mon_autre_groupe.actiongroup.php) et exécuter la méthode processMon_Autre_Action ()

Note : La casse des modules, groupes et actions n'a pas d'importance, Copix utilisera systématiquement des minuscules.

Les méthodes spéciales

beforeAction ($actionName)

La méthode beforeAction est systématiquement appelée avant le traitement à proprement parlé de votre méthode "process". Elle reçoit en paramètre le nom de l'action demandée par l'utilisateur.

Cette méthode est donc une bonne opportunité pour réaliser des opérations groupées pour votre ActionGroup.

Par exemple, si vous voulez protéger l'ensemble des pages de votre ActionGroup pour qu'elles soient accessibles aux seuls administrateurs, il suffit de faire :

class ActionGroupProtege extends CopixActionGroup {
   public function beforeAction ($pActionName) {
      CopixAuth::getCurrentUser ()->assertCredential ('basic:registered');
   }
}

Note: Si vous levez une exception dans votre méthode beforeAction, la méthode "process" (de l'action demandée) ne sera pas exécutée. (Si vous implémentez catchActionErrors, cette méthode aura la main)

Si vous décidez de retourner un CopixActionReturn depuis cette action, alors l'action initialement demandée ne sera pas exécutée et Copix prendra directement en compte votre retour.

Exemple :

class ActionGroupDefault extends CopixActionGroup {
   public function beforeAction ($pActionName) {
      if (in_array ($pActionName, array ('action1', 'action2', 'action3'))){
         //Si l'action demandée est 1 2 ou 3, alors on redirige l'utilisateur vers une autre URL
         return _arRedirect (_url ('module|group|action'));
      }
   }
}

NOTE : Si votre méthode beforeAction a retourné un code, alors l'action d'origine n'est pas exécutée. Le processus continue ensuite normalement avec afterAction qui reçoit en paramètre "beforeAction" comme nom d'action et le code retour de beforeAction comme données.

afterAction ($actionName, $toReturn)

La méthode afterAction est appelée systématiquement après l'appel à votre méthode process.

Elle reçoit en paramètre le nom de l'action dont on a demandé l'exécution ($actionName) et le retour apporté par la méthode de l'action (processXXX).

Note: Si une exception est levée dans beforeAction ou dans votre Action, la méthode afterAction ne sera pas exécutée.

Si votre méthode afterAction retourne un CopixActionReturn, alors ce dernier sera préféré à celui émis à l'origine par l'Action.

Exemple

class ActionGroupDefault extends CopixActionGroup {
   public function afterAction ($pActionName, $pActionReturn) {
      //On va transformer la sortie en PDF
      if ($pActionReturn->code == CopixActionReturn::PPO){
         $tpl = new CopixTpl ();

         $tpl->assign ('ppo', $pActionReturn->data);
         $contenu = $tpl->fetch ($pActionReturn->more);
         $contenu = _class ('moduleconversion|pdf')->renderPdf ($contenu);
         
         return _arContent ($contenu, array ('filename'=>'archive.zip'));
      }
   }
}

catchActionExceptions ($e)

Lorsqu'une exception est levée dans beforeAction, afterAction ou votre Action, cette dernière est transmise à la méthode catchActionExceptions.

Cette méthode vous permet de traiter les erreurs spécifiques à votre module et d'y réagir convenablement.

Si votre méthode ne gère pas l'exception en question, il faudra la relancer avec "throw $e".

exemple

function catchActionExceptions ($e){
   if ($e instanceof ExceptionQueJeGere){
      //traitement
   }else{
      throw $e;//exception non gérée ici
   }
}

otherAction ($actionName)

Lorsque l'internaute demande une action à votre ActionGroup alors que celui-ci ne sait pas la gérer, c'est cette méthode qui intercepte la demande. La méthode otherAction reçoit le nom de l'action qui avait été demandée par l'utilisateur.

Par défaut, si vous n'implémentez pas cette méthode dans votre ActionGroup, Copix retournera un 404.

Demander l'exécution d'une Action via la méthode process

Il vous est possible de demander à Copix d'exécuter une action via la méthode statique CopixActionGroup::process ('nomAction', $parametresAction);

Vous ne devriez réserver cette possibilité qu'à des fins exceptionnelles, lorsque vous avez besoin de faire appel directement à une action tierce. Un bon exemple d'utilisation est le module generictools avec par exemple son message de confirmation.

La description de l'action à utiliser sera de la forme : nomModule|nomGroupe::nomAction

Exemple d'utilisation

//... des conditions nous amènent à demander confirmation d'un message
   return CopixActionGroup::process ('generictools|Messages::getConfirm',
                                    array ('message'=>'Êtes vous sûr de cela ?',
                                           'confirm'=>_url ('module|actionOui'),
                                           'cancel'=>_url ('module|actionNon')));

Voir aussi

• Le tutorial Hello You !
• les Principes de base