# Classe Dir

La Smart Structure DIR ("Dossier"), permet de référencer des Smart Elements au sein d'une même collection. Cette Smart Structure hérite de la classe Dir.
Un Smart Element de la Smart Structure DIR est appelé un dossier.
Les méthodes de la Smart Structure DIR permettent de gérer le référencement (ajout ou suppression) de Smart Elements dans des dossiers.
Lors de l'ajout ou de la suppression des Smart Elements des dossiers, des hooks peuvent être appelés.

# Méthodes de la classe Dir

# insertDocument

    string insertDocument(string $docid,
                          string $mode = "latest",
                          bool $noprepost = false,
                          bool $forsrestrict = false,
                          bool $nocontrol = false)

Cette méthode permet d'ajouter une référence de Smart Element à un dossier. Une référence correspond à un Smart Element sans tenir compte de ses révisions.
La référence correspond à l'identifiant initial du Smart Element (initid).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

Avertissements

Si la référence existe déjà dans le dossier, la référence est ignorée.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element à insérer dans le dossier. Cet identifiant peut correspondre à n'importe quelle révision du Smart Element.

mode (string)

Seule la valeur latest (valeur par défaut) est supportée.

noprepost (bool)

noprepost permet de désactiver l'appel des méthodes hooks DirHooks::PREINSERT et DirHooks::POSTINSERT appelées respectivement avant et après l'insertion du Smart Element dans le dossier.
Valeur par défaut: false (activation des hooks).

forcerestrict (bool)

forcerestrict permet de désactiver le contrôle des restrictions d'insertion.
Valeur par défaut: false (contrôle de restriction effectué).

nocontrol (bool)

nocontrol permet de désactiver le contrôle du droit d'insertion de Smart Elements dans le dossier.
Valeur par défaut: **false (contrôle de droits effectué).

# Erreurs / Exceptions

Les erreurs peuvent être :

L'utilisateur ne possède pas le droit d'insertion (droit modify) de Smart Elements dans le dossier,
Le dossier est verrouillé par un autre utilisateur. (voir paramètre nocontrol ci-dessus),
Le Smart Element inséré n'est pas compatible par rapport aux restrictions appliquées sur le dossier (voir paramètre forcerestrict ci-dessus),
Les méthodes hooks DirHooks::PREINSERT ou DirHooks::POSTINSERT ont retourné une erreur (voir paramètre noprepost ci-dessus).

# Exemple

La Smart Structure "Groupe d'utilisateurs" (IGROUP) hérite de GROUP qui hérite de DIR et permet de gérer l'affectation d'utilisateurs dans les groupes.

L'exemple ci-dessous montre comment insérer l'utilisateur ayant pour nom logique USR_EMMA_PEEL dans le groupe ayant pour nom logique GRP_THE_AVENGERS

<?php
use Anakeen\SmartElementManager;
use Anakeen\Search\SearchElements;

$group = SmartElementManager::getDocument(2283);
$user = SmartElementManager::getDocument(3006);

/*
 * Afficher le contenu du groupe
 */

printf("* Content of DIR '%s': \n", $group->getTitle());
$s = new SearchElements();
$s->useCollection($group->id);
$members = $s->search()->getResults();
if (count($members) <= 0) {
  printf("\t<empty>\n");
} else {
  foreach ($members as $elmt) {
    printf("\t(%d) '%s'\n", $elmt['id'], $elmt['title']);
  }
}
/*
 * Insérer l'utilisateur dans le groupe
 */

printf("* Inserting '%s' into '%s'.\n", $user->getTitle(), $group->getTitle());
$err = $group->insertDocument($user->id);
if ($err != '') {
  throw new \Exception(
    sprintf(
      "Error inserting user (%d) '%s' into group (%d) '%s': %s",
      $user->id,
      $user->title,
      $group->id,
      $group->title,
      $err
    )
  );
}
/*
 * Afficher le contenu du groupe
 */
printf("* Content of DIR '%s':\n", $group->getTitle());
$s = new SearchElements();
$s->useCollection($group->id);
$members = $s->search();
if (count($members) <= 0) {
  printf("\t<empty>\n");
} else {
  foreach ($members as $elmt) {
    printf("\t(%d) '%s'\n", $elmt['id'], $elmt['title']);
  }
}

# insertMultipleDocuments

    string insertMultipleDocuments( array $tdocs,
                                    string $mode = "latest",
                                    bool $noprepost = false,
                                    & $tinserted = array(),
                                    & $twarning = array(),
                                    & $info = array())

Cette méthode permet d'insérer plusieurs Smart Elements dans le même dossier.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur.

# Liste des paramètres

tdocs (array)

tdocs est une liste de Smart Elements bruts (voir Retour de Smart Elements bruts avec SearchElements) à insérer dans le dossier.

mode (string)

Seule la valeur latest (valeur par défaut) est supportée.

noprepost (bool)

noprepost permet de désactiver l'appel des méthodes hooks DirHooks::PREINSERTMULTIPLE,DirHooks::PREINSERT,DirHooks::POSTINSERT et DirHooks::POSTINSERTMULTIPLE appelées respectivement avant et après l'insertion des Smart Elements dans le dossier.
Valeur par défaut: false (activation des hooks).

tinserted (string[])

tinserted référence un array associatif retourné par la méthode.
Les clés sont les identifiants (initid) des Smart Elements insérés dans le dossier et la valeur est un message indiquant que le Smart Element a été inséré dans le dossier.
Exemple de valeur retournée dans le array référencé:

array(
  1234 => 'Smart Element 1234 inséré',
  2345 => 'Smart Element 2345 inséré'
);

twarning (string[])

twarning référence un array associatif retourné par la méthode.
Les clés sont les identifiants des Smart Elements qui n'ont pas pu être insérés dans le dossier et la valeur est le message d'erreur de l'insertion.

info (array)

info référence un array associatif retourné par la méthode.
Il contient les erreurs retournées par les différents hooks, et est de la forme suivante :

    array(
        'error' => "Message d'erreur global de insertMultipleDocuments",
        'modifyError' => "Erreur liée au droit de modification"
        'preInsertMultipleDocuments' => "Message d'erreur de preInsertMultipleDocuments",
        'preInsertDocument'           => array(
            "Message d'erreur de preInsertDocument#1",
            ...
            "Message d'erreur de perInsertDocument#N"
            ),
        'postInsertDocument'          => array(
            "Message d'erreur de postInsertDocument#1",
            ...
            "Message d'erreur de postInsertDocument#N"
            ),
        'postInsertMultipleDocuments' => "Message d'erreur de postInsertMultipleDocuments()"
    )

# Erreurs / Exceptions

Les erreurs peuvent êtres:

L'utilisateur ne possède pas le droit d'insertion de Smart Element dans le dossier,
Le dossier est verrouillé par un autre utilisateur,
Les méthodes d'hooks preInsertMultipleDocuments,preInsertDocument,postInsertDocument et postInsertMultipleDocuments ont retournées une erreur (voir paramètre noprepost ci-dessus).

Les Smart Elements qui n'ont pas pu être insérés dans le dossier peuvent être consultés via l'argument retour $twarning passé à la méthode inserMultipleDocuments.

# Exemple

L'exemple suivant va rechercher tous les utilisateurs dont l'adresse mail contient @the-avengers.net, et les insérer dans un nouveau groupe GRP_THE_AVENGERS

<?php
use Anakeen\Search\SearchElementData;

use Anakeen\SmartElementManager;

$group = SmartElementManager::createDocument('IGROUP');
$group->setAttributeValue('us_login', 'grp_the_avengers');
$group->setAttributeValue('grp_name', 'Groupe@the-avengers.net');
$group->store();

/*
 * Affecter un nom logique au groupe
 */

$group->setLogicalName('GRP_THE_AVENGERS');

/*
 * Rechercher tous les utilisateurs ayant une
 * adresse mail en "@the-avengers.net".
 */
$s = new SearchElementData('IUSER');
$s->addFilter("us_extmail LIKE '%@the-avengers.net'");
$users = $s->search()->getResults();
if (count($users) > 0) {
  /*
   * Insérer tous ces utilisateurs dans le groupe.
   */
  $insertedList = array();
  $warningList = array();
  $err = $group->insertMultipleDocuments($users, "latest", false, $insertedList, $warningList);
  if ($err != '') {
    printf("* Some Smart Elements have not been inserted: %s", $err);
  }
  printf("* %d insertions :\n", count($insertedList));
  foreach ($insertedList as $docId => $msg) {
    printf("\t[%s] %s\n", $docId, $msg);
  }
  printf("* %d warnings :\n", count($warningList));
  foreach ($warningList as $docId => $warningMsg) {
    printf("\t[%d] %s\n", $docId, $warningMsg);
  }
}

Résultat

* 2 insertions :
        [1057] Insertion Smart Element Peel Emma
        [1058] Insertion Smart Element Steed John
* 0 warnings :

# removeDocument

    string removeDocument( string $docid,
                           bool $noprepost = false,
                           bool $nocontrol = false)

Cette méthode enlève une référence de Smart Element au dossier.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element à enlever du dossier.

noprepost (bool)

noprepost permet de désactiver l'appel des méthodes hooks preRemoveDocument et postRemoveDocument appelées respectivement avant et après la suppression du Smart Element dans le dossier.
Valeurs par défault : false (active les méthodes hooks)

nocontrol (bool)

nocontrol permet de désactiver le contrôle du droit de modification du dossier.
Valeur par défaut : false (le contrôle du droit de modification du dossier est effectué)

# Erreurs / Exceptions

Les erreurs peuvent être:

L'utilisateur ne possède pas le droit de modifier le contenu du dossier (voir paramètre nocontrol ci-dessus).
Les méthodes hooks preRemoveDocument ou postRemoveDocument ont retourné une erreur (voir paramètre noprepost ci-dessus).

Si le Smart Element à enlever n'est pas présent, aucune erreur n'est retournée.

# Exemple

<?php
use Anakeen\SmartElementManager;
use Anakeen\Search\SearchElements;

/** @var \SmartStructure\Dir $dossier */
$dossier = SmartElementManager::getDocument('MY_FOLDER');

/*
 * Rechercher tous les Smart Elements référencés dans le dossier
 */
$s = new SearchElements();
$s->useCollection($dossier->id);
$docList = $s->search();

/*
 * Enlever les Smart Elements du dossier
 */
foreach ($docList as $doc) {
  $err = $dossier->removeDocument($doc['initid']);
  if ($err != '') {
    printf("Error removing Smart Element: '%d' from DIR: %s", $doc['id'], $err);
  }
}

# hooks de la classe Dir

Ce chapitre décrit les méthodes hooks de la classe Dir.
Ces méthodes sont toutes vides. Elles ne contiennent aucun code à part la valeur de retour. Par contre, si la Smart Structure dérive d'une autre Smart Structure, il est nécessaire d'appeler le hook du parent afin de garantir l'intégrité.
Il est toutefois possible de ne pas appeler la méthode parente si le comportement doit être radicalement modifié.

# clear

string clear()

Cette méthode efface le contenu du dossier.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# canModify

string canModify()

Cette méthode vérifie si l'utilisateur courrant a le droit d'ajouter ou de supprimer des Smart Elements dans le dossier.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Exemple

$err = $this->canModify();
if ($err != "") {
  return $err;
} else {
  // TO DO
}

# Hooks de la classe Dir

Ce chapitre décrit les méthodes hooks de la classe Dir.
Ces méthodes sont toutes vides. elles ne contiennent aucun code à part la valeur de retour. Par contre, si la Smart Structure dérive d'une autre Smart Structure, il est nécessaire d'appeler le hook du parent afin de garantir l'intégrité.
Il est toutefois possible de ne pas appeler la méthode parente si le comportement doit être radicalement modifié.

# DirHooks::PREINSERT

    string function ( string $docid, bool $multiple = false )

La fonction du hook DirHooks::PREINSERT est appelée par la méthode insertDocument ou insertMultipleDocuments avant l'insertion du Smart Element dans le dossier (si l'argument noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreurs, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element qui va être inséré dans le Dossier.

multiple (bool)

multiple est positionné par la méthode insertMultipleDocuments pour indiquer que preInsertDocument est appelé dans le cadre de l'insertion de plusieurs documents.
Valeurs possibles:

true: Indique que le Smart Element inséré l'est dans le cadre de l'insertion de plusieurs Smart Elements,

false: Indique qu'un seul Smart Element est inséré dans le dossier.

# Erreurs / Exceptions

Si la fonction du hook DirHooks::PREINSERT retourne une chaîne non-vide, alors l'insertion n'est pas faite, et la méthode insertDocument retourne avec le message retourné par le hook.

# Exemple

<?php
namespace Facturation;

use Anakeen\SmartElementManager;
use Anakeen\SmartStructures\Dir\DirHooks;

class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::PREINSERT, function ($docId, $multiple = false) {
      $facture = SmartElementManager::createDocument($docId, true); // prendre la dernière révision
      if ($facture->isAlive()) {
        if ($facture->isPaid()) {
          return sprintf(
            "La facture '%s' ne peut être déposé dans le dossier d'archivage car elle n'est pas payée.",
            $facture->getTitle()
          );
        }
      }
      return "";
    });
  }

  protected function isPaid()
  {
    // Test de facturation
  }
}

# DirHooks::POSTINSERT

    string function( string $docid, bool &$multiple = false)

La fonction du hook DirHooks::POSTINSERT est appelée par la méthode insertDocument ou insertMultipleDocuments après l'insertion du Smart Element dans le Dossier (si noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element qui a été inséré dans le Dossier.

multiple (bool)

multiple est positionné par la méthode insertMultipleDocuments pour indiquer que postInsertDocument est appelé dans le cadre de l'insertion de plusieurs Smart Elements.
Valeurs possibles:

true: Indique que le Smart Element inséré l'est dans le cadre de l'insertion de plusieurs Smart Elements,

false: Indique qu'un seul Smart Element est inséré dans le dossier.

# Exemple

<?php
namespace Facturation;

use Anakeen\SmartElementManager;
use Anakeen\SmartStructures\Dir\DirHooks;

class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::POSTINSERT, function ($docId, $multiple = false) {
      $facture = SmartElementManager::createDocument($docId, true); // prendre la dernière révision
      $facture->archiverFacture();

      return "";
    });
  }

  protected function archiverFacture()
  {
    // Archivage facturation
  }
}

# DirHooks::PREINSERTMULTIPLE

string preInsertMultipleDocuments( string[]|int[] $tdocids)

Cette méthode est appelée par la méthode insertMultipleDocuments avant l'insertion des Smart Elements dans le Dossier (si noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

tdocids (string[]|int[])

Liste d'identifiants (identifiant numérique ou nom logique) des Smart Elements qui vont être insérés dans le dossier.

# Erreurs / Exceptions

Si la fonction du hook DirHooks::PREINSERTMULTIPLE retourne une chaîne non-vide, alors l'insertion n'est pas faite, et la méthode insertMultipleDocuments retourne avec le message retourné par preInsertMultipleDocuments.

# Exemple

<?php
namespace Facturation;

class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::PREINSERTMULTIPLE, function (&$rawDocList) {
      if (count($rawDocList) > 10) {
        return sprintf("Vous ne pouvez insérer que jusqu'à 10 Smart Elements à la fois.");
      }
      return "";
    });
  }
}

# DirHooks::POSTINSERTMULTIPLE

string(int[] | (string[] & $tdocids));

La fonction du hook DirHooks::POSTINSERTMULTIPLE est appelée par la méthode insertMultipleDocuments après l'insertion de Smart Elements dans le Dossier (si noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

tdocids (string[] | int[])

Liste d'identifiants (identifiant numérique ou nom logique) des Smart Elements qui ont été insérés dans le dossier.

# Exemple

La fonction d'archivage ne doit être déclenchée qu'une seule fois lors de l'insertion de plusieurs Smart Elements. Par contre, cette fonction d'archivage doit aussi être déclenchée lors d'une insertion unitaire.

<?php
namespace Facturation;

use Anakeen\SmartStructures\Dir\DirHooks;
class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::POSTINSERTMULTIPLE, function (array $docIdList) {
      /*
       * Faire une archive du lot des Smart Elements insérés
       */
      return $this->archiveDocuments($docIdList);
    });
    $this->getHooks()->addListener(DirHooks::POSTINSERT, function ($docId, $multiple = false) {
      if ($multiple === false) {
        /*
         * Faire une archive du Smart Element inséré
         */
        $this->archiveDocuments([$docId]);
      }
    });
  }

  protected function archiveDocuments(array $docIds)
  {
    // Archivage d'une liste de Smart Elements
  }
}

# DirHooks::PREREMOVE

string function( string $docid)

La fonction du hook DirHooks::PREREMOVE est appelée par la méthode removeDocument avant la suppression d'un Smart Element dans le dossier (si noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element à enlever du dossier.

# Erreurs / Exceptions

Si la function hook DirHooks::PREREMOVE retourne une erreur, alors la suppression du Smart Element dans le dossier n'est pas effectuée.

# Exemple

<?php
namespace Facturation;

use Anakeen\SmartElementManager;
use Anakeen\SmartStructures\Dir\DirHooks;
class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::PREREMOVE, function ($docId) {
      return $this->testPaiement($docId);
    });
  }
  public function testPaiement($docId)
  {
    $facture = SmartElementManager::createDocument($docId, true); // prendre la dernière révision
    if (!$facture->isPaid()) {
      return sprintf('La facture doit être payée pour pouvoir être enlevée du dossier.');
    }
    return '';
  }
}

# postRemoveDocument

    string postRemoveDocument(string $docid)

Cette méthode est appelée par la méthode removeDocument après que le Smart Element ait été enlevé du dossier (si noprepost est égal à false).
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

docid (string)

L'identifiant (identifiant numérique ou nom logique) du Smart Element qui a été supprimé dans le dossier.

# Exemple

<?php
namespace Facturation;

use Anakeen\SmartElementManager;
use Anakeen\SmartStructures\Dir\DirHooks;
class ArchiveFacture extends \SmartStructure\Dir
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(DirHooks::POSTREMOVE, function ($docId) {
      /*
       * Mettre la facture dans l'état 'Brouillon'
       * lorsqu'elle est enlevée du dossier
       */
      $facture = SmartElementManager::createDocument($docId, true);
      $facture->setState('ST_Brouillon');
      return "";
    });
  }
}

← Classe ApiUsage Classe SmartElement →