Inclure un upload dans une page

Cas d'utilisation

Pour un article, on souhaite réaliser un upload d'une image qui sera ensuite associée au document en cours d'édition.

Upload en iframe

Une action abstraite 'Action_Upload' permet de gérer les fonctionnalités de base d'upload (choix du fichier, gestion du fichier reçu par le serveur, etc) en mode "pseudo ajax" à l'aide d'un iframe. Ce processus d'upload comporte 4 actions :

• création de l'iframe pour le choix de fichier (action chooseFile)
• affichage du formulaire d'upload dans l'iframe (action displayForm)
• traitement du fichier reçu, création d'un document avec ce fichier et affichage d'une modale pour saisir des informations (action proceedFile)
• enregistrement des informations et fermeture de la modale, fermeture qui déclenche des mises à jour Majax dans la page (action saveInstance)

Déclaration des noms des actions

Afin de pouvoir réaliser un upload, il faut d'abord déclarer, pour la classe Article, que l'on va enclencher un processus d'upload pour associer une image et déclarer les noms des actions qui doivent être utilisées dans l'URL. Le fichier actions.xml doit donc déclarer les actions suivantes :

 <action name="chooseFile"
           group="uploadImage" action="chooseFile">
 </action>
 <action name="displayForm"
           group="uploadImage" action="displayForm">
 </action>
 <action name="proceedFile"
           group="uploadImage" action="proceedFile">
 </action>
 <action name="saveInstance"
           group="uploadImage" action="saveInstance">

Dans le package Article, la classe d'action correspondante est alors SydonieDocument_Article_action_uploadImage et elle dérive de l'action abstraite Abstract_SydonieDocument_action_upload.

<?php
// /monprojet/Package/action/action_uploadImage.php
class SydonieDocument_Event_action_uploadImage extends Action_Upload {

}

Inclusion de l'upload dans la page

Le template d'article doit simplement effectuer l'appel à l'action 'chooseFile':

<?php echo runAction($obj, 'chooseFile'); ?>

Celui-ci fait automatiquement appel à l'iframe (via l'action 'iframeContent') et lorsque le fichier est bien reçu, appelle l'action 'proceedFile'. 

Toute cette partie est donc gérée par l'action Action_Upload.

Hook définis par Action_Upload

Afin de pouvoir agir sur les options de l'upload, des méthodes 'hook' sont proposées par Action_Upload. Que permettent-elles de contrôler ?

Types de fichiers acceptés

La méthode 'isOkUploadedFile' déclare le(s) type(s) de fichier acceptable pour l'upload :

 protected function isOkUploadedFile($path, $fileInfos) {
   switch ($fileInfos['type']) {
     case 'image/png':
     case 'image/jpeg':
       return true;
   }
   return 'UnsupportedFileType';
 }

Type de document à créer

Si le type de fichier déposé est acceptable, il faut déclarer la classe de document qui doit être instanciée avec le fichier. La méthode 'getEntityClass' défonit cela :

protected function getEntityClass($path, $fileInfos) {

   return 'SydonieDocument_Image';

} Une fois le document créé, une modale s'ouvre avec le formulaire de création de ce type de document. La validation du formulaire déclenche l'enregistrement des données et l'appel au hook "post enregistrement"

Instructions suivant l'enregistrement du document uploadé

La méthode 'onInstanceOk' est appelée, permettant ainsi de placer dse Statements entre le document Article et le document Image par exemple:

 protected function onInstanceOk($imageInstance) {
   // $this->instance est ici l'instance de l'article (on est dans une action de la classe Article)
   $st = getManager('Statements')->add($this->instance, 'HAS_IMAGE', $imageInstance);
 }

Interactions MAJAX

Lors de la fermeture de la modale, il faut déclarer l'événement MAJAX qui sera envoyé. Cet événement permattra de déclencher les éventuelles mises à jour de la page principale. La méthode 'getDataMajax' permet de réaliser cela :

 protected function getDataMajax() {
   return 'majaxFire_imageUploaded';
 }

Les zones de la page ayant un attribut 'data-majax' avec la valeur 'majaxListenTo_imageUploaded' seront alors mises à jour avec l'URL spécifiéer dans data-url.

Autres hooks

Moins utiles en général mais aussi disponibles, les hooks 'onFileOk', 'onSydonieDataOk' peuvent apporte encore plus de contrôle à l'action d'upload.