12.2 Écrire une action

Une action est le déroulement d'une fonction PHP.

12.2.1 Principe et spécification

12.2.1.1 Introduction

Toutes les actions sont définies au sein d'une application. La description de l'action se fait dans le fichier MYAPP.app dans la variable $action_desc.

Une action est définie à l'aide d'un fichier PHP et/ou d'un template XML/HTML. Le fichier PHP ou le template est optionnel, mais il faut au moins un des deux. Chaque action peut définir son droit d'accès (ACL). Si l'utilisateur n'a pas le droit défini, l'exécution de l'action est interdite. Si l'action n'a pas d'ACL, l'action est considérée comme libre ainsi tout utilisateur a le droit de l'exécuter.

Le nom du fichier PHP, du template et de la fonction, doivent être définis dans MYAPP.app.

Exemple: Pour la définition de $app_desc se reporter au chapitre applications.

Fichier MYAPP.app:
<?php
$app_desc = array(...);// voir le chapitre sur les applications
 
$action_desc = array(
    array(
      "name" => "MYACTION1",
      "short_name" => N_("action one"),
      "acl" => ...
      "root" => "Y" 
    ),
    array(
      "name" => "MYACTION2",
      "short_name" => N_("action two"),
      "acl" => ..
      "root" => "N",
      "script" => "myaction1.php",
      "function" => "mafonctionpouraction2",
      "layout" => "monlayoutpouraction2.xml"
    )
    );
?>

12.2.1.2 Contenu possible pour $action_desc

name (obligatoire)

Indique le nom de référence de l'action.

L'appel de l'action se fait en utilisant la valeur de ce paramètre.

attention : Il ne doit pas dépasser 30 caractères.

short_name (obligatoire)
Description courte de l'action
long_name (facultatif)

Description longue de l'action.

S'il est omis le long_name est égal au short_name.

script (facultatif)

Nom du fichier PHP qui est inclus lors de l'exécution de l'action.

S'il est omis, le nom du script est le nom (name) de l'action en minuscules, suivi de l'extension .php.

function (facultatif)

Nom de la fonction PHP qui est appelée lors de l'exécution de l'action. Elle doit se trouver dans le fichier défini par script.

S'il est omis, le nom de la fonction est le nom (name) de l'action en minuscules.

layout (facultatif)

Nom du fichier template utilisé lors de l'exécution de l'action.

S'il est omis, le nom du template est le nom (name) de l'action en minuscules suivi de l'extension .xml.

available (facultatif)

Indique si l'action est disponible. Deux valeurs possibles :

  • Y : action disponible (valeur par défaut)
  • N : action non disponible.

Une action indisponible ne peut pas être exécutée. Dans le cas d'une requête HTTP, le status "503 Action unavalaible" est renvoyé.

acl (facultatif)

Nom du droit nécessaire pour exécuter l'action.

Le nom du droit doit être une des valeurs définies par la variable $app_acl. Une absence de valeur indique qu'il n'est pas nécessaire d'avoir un droit particulier pour exécuter l'action. Si un utilisateur tente d'exécuter une action dont il n'a pas le droit alors dans le cas d'une requête HTTP, le status "503 Action forbidden" est renvoyé.

Note : l'utilisateur "admin" peut exécuter toutes les actions sans restriction de droits.

root (facultatif)

Indique que cette action est l'action principale de l'application. Deux valeurs possibles:

  • Y action principale. Dans ce cas l'action est lancée avec l'URL ?app=MYAPP;
  • N action non principale (valeur par défaut).

Une seule action peut être notée "root". Dans le cas où plusieurs actions sont notées "root", aucune erreur n'est levée, mais, le résultat n'est pas garanti : l'action qui est lancée est la première trouvée par la requête sql.

openaccess (facultatif)

(Y ou N) Indique que l'action est exécutable avec un jeton d'authentification.

Par défaut, une action n'est pas accessible en via une authentifiactin par jeton. Pour autoriser, l'action à être exécutée, il faut mettre Y dans ce paramètre.

12.2.1.3 Contenu d'un fichier exemple d'action: myaction1.php

Le fichier myaction1.php contient une fonction du même nom que l'action avec comme paramètre une référence à l'objet [Action][class_action].

Fichier myaction1.php
function myaction1(Action &$action) {
// …
}

12.2.1.3.1 Récupération de valeurs d'environnement

Pour récupérer :

  • la valeur d'un paramètre applicatif :

    $parameterValue = $action->getParam("nom_du_paramètre");

  • le service d'accès à la base de données :

    $dbaccess = $action->dbaccess;

  • l'utilisateur courant :

    $user = $action->user; // Objet de type `Account`

  • l'application liée à l'action (retourne une instance d'objet de la classe Application :

    $application = $action->parent; // Objet de type `Application`
 

  • les valeurs passées dans l'URL :

    Une action peut être lancée par l'activation d'un lien hypertexte ou la soumission d'un formulaire. L'URL appelée peut contenir des paramètres, dont les valeurs sont récupérées par l'intermédiaire de la méthode Action::getArgument. Toutefois, il faut préférer l'utilisation de la classe ActionUsage pour la récupération des paramètres.

    $val = $action->getArgument("url_val", "val_par_defaut");

12.2.1.3.2 Vérifier les arguments et donner l'usage

La classe ActionUsage permet de valider que les arguments reçus sont valides (attribut obligatoire/optionnel).

Si l'option strict est mise à true (valeur par défaut), tout argument non compris dans l'usage provoquera une erreur et l'action sera déroutée dès l'appel à verify().

Exemple d'utilisation de ActionUsage :

function my_color(Action &$action)
{
    $usage = new ActionUsage($action);
    $usage->setText(_("Get color map"));
    $red = $usage->addOptionalParameter("red", "red level", array(), 128);
    $quality = $usage->addOptionalParameter("quality", "quality", array(), 20);
    $usage->verify();
 
    if (!is_numeric($red)) $usage->exitError('red must be a integer');
    if (!is_numeric($quality)) $usage->exitError('quality must be a integer');
}

12.2.1.3.3 Afficher/Transmettre des données dans le template

Il faut utiliser l'attribut lay de l'objet $action qui est passé en paramètre. L'attribut lay est un objet de la classe Layout :

$action->lay->set("mydata", "val_to_be_sent");

Plus d'informations sur les templates sont disponibles ici.

12.2.1.3.4 Mise en garde et astuces

  • Pour sortir de la fonction et afficher un message d'erreur à l'utilisateur, il faut utiliser la méthode exitError() :
$action->exitError("Message d'erreur");

12.2.1.4 Contenu d'un fichier exemple de template d'action : myaction1.xml

Le template de l'action peut faire référence à ou plusieurs zones.

Le reste de la page entre les deux balises doit être du code HTML valide ou utiliser le système de template de Dynacase.

Note : Bien que la plupart des templates produisent des pages HTML, le template peut aussi produire tout type de données textuelles (HTML, JS, CSS, JSON, XML, CSV, etc.). Une action peut aussi retourner des fichiers binaires mais dans ce cas ce n'est pas l'objet lay qui sera utilisé pour le retour.

12.2.2 Exécuter une action

Une action est exécutée sur le serveur en indiquant le nom de l'application et le nom de l'action dans l'url d'accès.

Le nom de l'application est indiqué dans le paramètre app et le nom de l'action dans le paramètre action.

Exemple :

?app=MY_APP&action=MY_ACTION

Les actions peuvent aussi être exécutées en mode console avec wsh.

Source : applications_actions/ecrire_action.md Dynacase Platform 3.2 | Core Manuel de référence, version 3.2 édition 13, © Anakeen Labs <labs@anakeen.com>
×
Publié sous licence CC (http://creativecommons.org/licenses/by-nc-sa/2.0/fr/) par Anakeen [www.anakeen.com]
Attribution Vous devez créditer l'Oeuvre, intégrer un lien vers la licence et indiquer si des modifications ont été effectuées à l'Oeuvre. Vous devez indiquer ces informations par tous les moyens possibles mais vous ne pouvez pas suggérer que l'Offrant vous soutient ou soutient la façon dont vous avez utilisé son Oeuvre.
Pas d’Utilisation Commerciale Vous n'êtes pas autoriser à faire un usage commercial de cette Oeuvre, tout ou partie du matériel la composant.
Partage dans les Mêmes Conditions Dans le cas où vous effectuez un remix, que vous transformez, ou créez à partir du matériel composant l'Oeuvre originale, vous devez diffuser l'Oeuvre modifiée dans les même conditions, c'est à dire avec la même licence avec laquelle l'Oeuvre originale a été diffusée.