# Classe SmartElement

Toutes les Smart Structures de Smart Element héritent de cette classe. Celle-ci décrit l'ensemble des propriétés communes aux Smart Elements de toutes les Smart Structures.
Elle donne accès aux méthodes communes de manipulation de Smart Elements, comme la modification de Smart Element, la récupération de valeur de Smart Fields ou le mécanisme de hook.

# Propriétés de la classe SmartElement

Les propriétés de la classe SmartElement peuvent être récupérées au moyen de la méthode SmartElement::getPropertyValue.
De façon générale, bien que ces propriétés ne soient marquées comme private, leur affectation ne doit passer que par les setters appropriés.
Les propriétés n'ayant pas de setter spécifiques sont modifiées par effet de bord d'autres méthodes du Smart Element;
par exemple, SmartElement::revision ne doit pas être modifié, mais SmartElement::revise incrémente cette propriété.

# Liste des propriétés

adate

Date de dernier accès au Smart Element.

allocated

Identifiant système de l'utilisateur auquel le Smart Element est affecté.

archiveid

Id de l'archive dans laquelle est contenu le Smart Element.
Note: cette propriété n'est portée que par le document archivé. Pour trouver la liste des lignées de Smart Elements archivées, il faut faire une recherche sur toutes les révisions.

atags

Balises applicatives (Tags positionnés sur le Smart Element).
Ces tags permettent aux applications de marquer les Smart Elements pour des traitements spécifiques.
Les tags sont stockés dans une chaîne de caractères et sont séparés par des \n.
La méthodes SmartElement::getATag() vérifie la présence d'une balise applicative.

cdate

Date de création de la révision.
Pour obtenir la date de création de la lignée de Smart Elements, il faut récupérer celle de la révision 0.
Le format de la date est YYYY-MM-DD HH:MM:SS.

classname

Nom de la classe associée au Smart Element. Utilisé uniquement pour les Smart Structures.

confidential

Indique si le Smart Element est confidentiel.
Dans ce cas, confidential vaut 1.

cvid

Identifiant du Smart Element contrôle de vue associé à ce Smart Element.

doctype

Type de Smart Element.
Utilisé en interne pour des optimisations de performance et des contrôles.

  • F: Smart Element normal,
  • D: Dossier (Dir),
  • S: Recherche (Search),
  • P: Profil,
  • T: Temporaire,
  • I: Incomplet,
  • Z: Smart Element supprimé (Zombie),
  • W: Cycle de vie (Workflow),
  • C: Smart Structure (Class).

dprofid

Identifiant du profil dynamique associé à ce Smart Element.
Lorsque le Smart Element est soumis à un profil dynamique, ce dernier lui permet de calculer le profil qui lui sera appliqué, lequel est stocké sur le Smart Element lui-même. Ainsi lorsque la propriété dprofid est renseignée, la propriété profid est égale à l'id du Smart Element (ce qui correspont à un profil dédié).

fromid

Id de la Smart Structure d'appartenance.

icon

Référence au fichier d'icône du Smart Element.
La valeur est:

  • le nom de l'icône,
  • ou la référence d'un fichier du vault (sous la forme <type-mime>|<vaultid>|<file-title>).

initid

Id du premier Smart Element de la lignée de Smart Elements.
Il est notamment utile pour les recherches.

Imodify

Permet de savoir si le Smart Element a été modifié depuis sa dernière révision.
Les valeurs sont:

  • Y: La révision est la révision courante et a été modifiée depuis la dernière révision,
  • L: La révision est la dernière révision avant la révision courante,
  • D: La révision est supprimée,
  • N:
  • Toute révision figée du Smart Element (autre que la N-1): dans ce cas, locked vaut -1,
  • La révision est la révision courante du Smart Element, mais identique à la révision N-1.

locked

Indique l'identifiant système de l'utilisateur qui a verrouillé le Smart Element:

  • Chiffre négatif (inférieur à -1): la valeur absolue indique l'identifiant système de l'utilisateur ayant verrouillé le Smart Element automatiquement. Ce verrou est posé lorsqu'un utilisateur clique sur le bouton de modification d'un Smart Element, et est supprimé automatiquement lors de la fin de l'édition, à la fermeture du navigateur (au moyen de l'événement onBeforeUnload), ainsi que par le script cleanContext,
  • Chiffre positif: identifiant système de l'utilisateur ayant verrouillé le Smart Element manuellement,
  • 0: pas de verrou,
  • -1: Smart Element révisé (figé).

name

Nom logique du Smart Element.
Référence toujours la version courante d'un Smart Element. Le nom logique est identique quelque soit la révision d'un même Smart Element.
Lorsqu'on affecte un nom logique, il est affecté sur l'ensemble de la lignée de Smart Elements.
Si le nom logique est utilisé comme référence pour accéder à un Smart Element, c'est la dernière révision qui sera retournée.

owner

Identifiant système de l'utilisateur ayant créé le Smart Element.
Cette valeur est spécifique à chaque révision.

prelid

Identifiant du Smart Element (dossier) de la relation primaire.
Cela correspond au parent lors d'une représentation arborescente.
Cette propriété est gérée automatiquement avec les règles de gestion suivantes:

  • lorsque le Smart Element n'a jamais été inséré dans un dossier: le premier dossier dans lequel est inséré le Smart Element,
  • lorsque le Smart Element est déplacé dans un nouveau dossier: le dernier dossier dans le quel est déplacé le Smart Element,
  • lorsque le Smart Element est retiré d'un dossier: si le Smart Element est dans un autre dossier, alors celui-ci est selectionné.

profid

Identifiant du [profil de Smart Element][profdoc].

  • Chiffre négatif: profil non activé,
  • 0: pas de profil,
  • Vide: pas de profil,
  • Chiffre positif: profil actif:
  • Identique à l'id du Smart Element: contrôle dédié,
  • Autre valeur positive: profil lié, non dynamique.

mdate

Date de révision.
Pour un Smart Element non révisé, c'est la date de dernière modification. Le format de cette date est un entier (unix timestamp).

revision

Numéro d'ordre du Smart Element dans sa lignée de Smart Elements.

state

Etape du Smart Element ou référence à un identifiant de Smart Element état libre.

title

Titre du Smart Element.

usefor

Type d'utilisation du Smart Element:

  • S: La Smart Structure est Système: elle n'apparaît pas par défaut dans la liste des Smart Structures pour les recherches, recherches détaillées ou rapports.
    Le caractère S peut aussi être placé devant les autres caractères décrits ci-dessous pour masquer la Smart Structure dans les recherches,
  • W: Le Smart Element est un cycle de vie (Workflow),
  • P: Le Smart Element est un profil (Profil).

version

Libellé de la version; il est vide par défaut.
Note: La version n'est pas obligatoirement numérique, elle peut aussi être alphanumérique; mais elle ne doit pas contenir de "retour chariot".

wid

Identifiant du Smart Element cycle de vie associé à ce Smart Element.

# Méthodes de la classe SmartElement

Ce chapitre décrit les méthodes de manipulation de Smart Elements.

# addArrayRow

    string addArrayRow( string $idAttr,
                        array $tv,
                        int $index = -1)

La méthode addArrayRow permet d'ajouter, ou d'insérer à un indice donné, une ligne dans un Smart Field de type array.
La ligne insérée entraîne un décalage des lignes d'indice supérieur, qui montent alors toutes d'un cran.

Avertissements

Lors de chaque appel à addArrayRow, un setValue est effectué pour chacune des colonnes de l'array. Pour ajouter de nombreuses lignes, il peut être plus efficace de gérer manuellement l'ajout dans chaque colonne.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field de type array auquel on souhaite ajouter, ou insérer, une ligne.

tv (array)

Un tableau associatif dont la cle est le nom d'un Smart Field colonne du array, et la valeur est la valeur à affecter à cette colonne.

index (int)

index permet de spécifier l'indice ( à partir de 0 ) où insérer la ligne dans le tableau.
Si index vaut 0, alors la ligne est insérée au début du tableau. Si index vaut -1 ou est supérieur ou égal au nombre de lignes du tableau, la ligne est alors ajoutée à la fin du tableau.

# Valeur de retour

La méthode 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.

# Erreur / Exception

une erreur est retournée si:

  • le Smart Field idAttr n'est pas de type array,
  • la valeur tv n'est pas un array PHP,
  • une clef de tv n'est pas le nom d'un Smart Field attaché au Smart Field idAttr.

# Exemple

Soit un Smart Field faces de type array auquel sont rattachés les Smart Fields face_firstname et face_lastname de type text.

namespace My;
$photo = new SmartElement("MyPhoto");
$photo->clearArrayValues(\SmartStructure\Fields\MyPhoto::faces);

$row = array(
  \SmartStructure\Fields\MyPhoto::face_firstname => 'Marge',
  \SmartStructure\Fields\MyPhoto::face_lastname => 'Simpson'
);
$photo->addArrayRow(\SmartStructure\Fields\MyPhoto::faces, $row);

$row = array(
  \SmartStructure\Fields\MyPhoto::face_firstname => 'Homer',
  \SmartStructure\Fields\MyPhoto::face_lastname => 'Simpson'
);
$photo->addArrayRow(\SmartStructure\Fields\MyPhoto::faces, $row);

$row = array(
  \SmartStructure\Fields\MyPhoto::face_firstname => 'Lisa',
  \SmartStructure\Fields\MyPhoto::face_lastname => 'Simpson'
);
$photo->addArrayRow(\SmartStructure\Fields\MyPhoto::faces, $row, 1);

$row = array(
  \SmartStructure\Fields\MyPhoto::face_firstname => 'Bart',
  \SmartStructure\Fields\MyPhoto::face_lastname => 'Simpson'
);
$photo->addArrayRow(MyPhoto::faces, $row, 0);

Le tableau MyPhoto::faces résultat est alors composé comme suit:

Firstname Lastname
#0 Bart Simpson
#1 Marge Simpson
#2 Lisa Simpson
#3 Homer Simpson

# addHistoryEntry

    string addHistoryEntry( string $comment = '',
                            int $level = DocHisto::INFO,
                            string $code = '',
                            int $uid = '')

Cette méthode permet d'enregistrer un nouveau message daté dans l'historique du Smart Element.

Avertissements

Les messages enregistrés ne sont pas localisables. Cela implique que les messages restitués par l'historique ne sont pas traduits.

# Liste des paramètres

comment (string)

Message qui sera enregistré dans l'historique.

level (int)

Niveau du message:

  • DocHisto::NOTICE : notification,
  • DocHisto::INFO : message d'information (valeur par défaut),
  • DocHisto::MESSAGE : message standard,
  • DocHisto::WARNING : message d'avertissement,
  • DocHisto::ERROR : message d'erreur. Dans ce cas, le message est aussi ajouté au fichier log d'erreur du serveur Apache.

code (string)

Code du message: ce code peut être utilisé pour répertorier certaines entrées dans l'historique. Par exemple, le code CREATE est utilisé pour indiquer les messages relatifs à la création d'un Smart Element. La méthode SmartElement::getHisto() permet de filtrer en fonction du code les messages de l'historique.

uid (int)

Identifiant système du compte utilisateur. Si celui-ci est vide, alors le message sera attribué à l'utilisateur courant.

# Erreur / Exceptions

Une exception peut être levée en cas de problème d'enregistrement.

# Exemple

Enregistrement d'un nouveau message d'avertissement.

use Anakeen\SmartElementManager;

$d = SmartElementManager::createDocument("MY_DOCUMENT");
$d->store();
if ($d->isAlive()) {
  // enregistrement
  $d->addHistoryEntry("Hello world", DocHisto::WARNING);
}

Notes

Il n'y a pas de méthode depuis la classe SmartElement permettant de supprimer des messages de l'historique. Pour manipuler et gérer l'historique du Smart Element, il faut utiliser la classe DocHisto.

# clearValue

    string clearValue( string $attrid)

La méthode clearValue permet d'effacer la valeur d'un Smart Field de type non array.

# Liste des paramètres

attrid (string)

Le nom du Smart Field ( de type non array) à effacer.

# Valeur de retour

La méthode 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.

# Erreur / Exception

Les erreurs retournées sont les mêmes que celles retournée par la méthode SmartElement::setValue.

# Exemple

namespace My;
use SmartStructure\Fields\MyFacture as MyFact;

$facture = new SmartElment("MyFacture");
$facture->clearValue(MyFact::montant);

Notes

Pour effacer un Smart Field de type array, utilisez la méthode SmartElement::clearArrayValues.
Si le Smart Field effacé est de type docid avec une option doctitle, alors le Smart Field portant le titre est lui aussi effacé.

# arrayToRawValue

    string arrayToRawValue( array(string) $v,
                            string $br = '<BR>')

La méthode arrayToRawValue permet de sérialiser un ensemble de valeurs sous la forme d'une chaîne de caractères qui peut ensuite être utilisée pour positionner la valeur d'un Smart Field faisant parti d'un array, ou d'un Smart Field multi-valué, avec la méthode SmartElement::setValue.
Les valeurs sont sérialisées par une concaténation avec le caractère \n utilisé comme séparateur.

Avertissements

La méthode arrayToRawValue est une méthode de bas niveau que vous ne devriez utiliser qu'en dernier recours.
Il faut privilégier l'utilisation de la méthode setAttributeValue qui prend en charge automatiquement ces opérations de sérialisation.

# Liste des paramètres

v (array(string))

Une liste de chaînes de caractères.

br (string)

br permet de spécifier la chaîne de caractères pour substituer le caractère retour à la ligne \n dans les valeurs à sérialiser.
Par défaut, la chaîne de caractères de substitution est la chaîne <BR>

# Valeur de retour

La méthode arrayToRawValue retourne une chaîne de caractères correspondant à la sérialisation des valeurs fournies.

# Exemple

Le Smart Field PHOTO_KEYWORD est un Smart Field de type texte multi-valué (option multiple).

namespace My;
use SmartStructure\Fields\MyPhoto as MyPics;

$motsCles = array("Tour Eiffel", "Champ de Mars", "Paris", "France");
$photo->setValue(MyPics::photo_keywords, $doc->arrayToRawValue($motsCles));

Notes

Les valeurs de la liste doivent être des scalaires(string,int,float).

# hasPermission

    bool hasPermission( string $aclName,
                        bool $strict = false)

Cette méthode permet de vérifier que l'utilisateur courant possède un droit particulier sur le Smart Element.
Cette méthode retourne true, si l'utilisateur possède le droit indiqué. Ce droit est indiqué dans le profil du SMart Element et peut être obtenu par un rôle ou un groupe.

# Liste des paramètres

aclName (string)

Nom du droit à examiner

strict (bool)

Indique s'il faut tenir compte de la suppléance :

  • si false (par défaut): les droits des titulaires sont aussi pris en compte.
  • si true : les droits des titulaires ne sont pas pris en compte.

# Valeur de retour

Retourne true dans les cas suivants:

  • si l'utilisateur possède le droit demandé,
  • si l'utilisateur est un "admin" (même si le droit n'existe pas). Retourne false dans les cas suivants:
  • si l'utilisateur ne possède pas le droit demandé ( hors "admin"),
  • si le droit n'est pas un des droits du Smart Element (hors "admin").

# Exemple

# Vérification du droit de modification

Le droit de modifier est le droit edit.

use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument("1420");
$doc->store();

if ($doc->isAlive()) {
  if ($doc->hasPermission("edit")) {
    printf('Utilisateur "%s" a le droit de modifier %s"' . '\n', getCurrentUser()->login, $doc->getTitle());
  } else {
    printf('Utilisateur "%s" n\'a pas le droit de modifier "%s"' . '\n', getCurrentUser()->login, $doc->getTitle());
  }
} else {
  printf("Smart Element non trouvé\n");
}

Attention

Le droit edit ne suffit pas forcément pour autoriser la modification. Il peut être nécessaire de vérifier aussi le verrou(propriété locked).

# Vérification de tous les droits

La liste des droits du Smart Element est dans la propriété acls de l'objet.

use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument("1420");
$doc->store();
if ($doc->isAlive()) {
  $acls = $docs->acls;
  printf('Utilisateur "%s" a les droits suivants pour "%s" : ' . '\n', getCurrentUser()->login, $doc->getTitle());
  foreach ($acls as $acl) {
    printf("Droit %-12s : %s\n", $acl, $doc->hasPermission($acl) ? "Oui" : "Non");
  }
} else {
  printf("Smart Element non trouvé \n");
}
  • Résultat:
Utilisateur "zoo.garde" a les droits suivants pour "Théodor" :
Droit view         : Oui
Droit edit         : Non
Droit delete       : Non
Droit send         : Non
Droit unlock       : Non
Droit confidential : Non
Droit wask         : Non

Notes

Les méthodes SmartElement::enableEditControl() et SmartElement::disableEditControl() n'ont pas d'impact sur cette méthode.

# delete

    string delete( bool $really = false,
                   bool $control = true,
                   bool $nopost = false)

Cette méthode est utilisé pour supprimer un Smart Element. Elle met le statut du Smart Element à "supprimé". La propriété doctype est affectée à Z(zombie) et locked est affectée à -1 dans le cas d'une suppression logique.

Avertissements

Cette méthode supprime toutes les révisions du Smart Element.

# Liste des paramètres

really (bool)

Si really est true, le Smart Element ainsi que toutes ses révisions sont supprimées de la base de données. Cette opération n'est pas annulable.
Si really est false,le Smart Element est supprimé de manière logique. Il est donc toujours présent en base de données mais juste noté comme étant supprimé.

control (bool)

Si control est true, le droit delete est vérifié pour l'utilisateur courant. Si l'utilisateur n'a pas ce privilège, la suppression est abandonnée.
Si control est false, la vérification des droits n'est pas effectuée.

nopost (bool)

Si nopost est true, alors les hooks SmartHooks::PREDELETE et SmartHooks::POSTDELETE ne sont pas exécutés.
Si nopost est false, ces deux hooks sont exécutés.

# Valeur de retour

Message d'erreur. Si la chaîne retournée est non nulle, le message indique l'erreur qui a interdit la suppression.

# Erreur / Exception

Une erreur est retournée si:

  • le Smart Element n'existe pas ou plus,
  • le Smart Element est déjà supprimé,
  • l'utilisateur n'a pas le droit delete sur le Smart Element,
  • le hook SmartHooks::PREDELETE retourne une erreur.

# Exemple

Suppression du Smart Element référencé par l'identificateur $documentId.

use Anaaken\Core\SmartElementManager;

$doc = SmartElementManager::createDocument($documentId);
$doc->store();
if ($doc->isAlive()) {
  $err = $doc->delete();
  // maintenant le Smart Element est supprimé
  if ($err === '') {
    printf("Suppression de %s [%d]", $doc->getTitle, $doc->id);
  }
}

Notes

Une entrée dans l'historique est enregistrée à chaque suppression.
Les Smart Elements supprimés logiquement sont toujours accessibles avec leur identifiant. Ils ne peuvent par contre plus être modifiés par l'interface web.
La classe SearchElements permet de rechercher les Smart Elements supprimés en utilisant le Smart Field trash.

# clearArrayValues

    string clearArrayValues( string $idAttr)

La méthode clearArrayValues permet de vider les valeurs d'un Smart Field de type array, en vidant le contenu de tous les Smart Fields rattachés à cet array.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field de type array dont on souhaite vider le contenu.

# Valeur de retour

La méthode 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.

# Erreur / Exceptions

Si le Smart Field idAttr spécifié n'est pas de type array, un message d'erreur est retourné.

# Exemple

Le Smart Field photo_list est un Smart Field de type array contenant les Smart Fields photo_file de type file et photo_comment de type htmltext.

namespace My;
use SmartStructure\Fields\MyAlbum;

$album->deleteArray(MyAlb::photo_list);

Le contenu des Smart Fields photo_file et photo_comment est alors effacé.
De la même manière, le tableau peut être vidé en vidant explicitement chacune des colonnes de l'array:

namespace My;
use SmartStructure\Fields\MyAlbum;

$album->clearValue(MyAlb::photo_file);
$album->clearValue(MyAlb::photo_comment);

# duplicate

    SmartElement|string duplicate( bool $temporary = false,
                                   bool $control = true,
                                   bool $linkfld = false,
                                   bool $copfile = false )

Cette méthode réalise une copie de l'objet SmartElement. Cette copie est enregistrée en base de données avec un nouvel identificateur.
La révision de la copie est affectée à zéro. Le profil de la copie est affectée au profil (cprofid) indiquée par la Smart Structure.
Si le Smart Element est lié à un cycle, l'état de la copie est l'état initial du cycle.

# Liste des paramètres

temporary (bool)

  • Si true, le Smart Element en base est créé comme Smart Element temporaire. Aucun profil n'est associé au Smart Element s'il est temporaire.
  • Si false: le Smart Element est créé avec un identificateur non temporaire.

control (bool)

  • Si true, la duplication est contrôlé par le droit create.
  • Si false: aucun contrôle de droit est réalisé.

linkfld (bool)

  • Si true, et si le Smart Element est un dossier. Alors les Smart Elements contenus dans le dossier original sont liés aussi au dossier copié.
    Les Smart Elements contenus ne sont pas dupliqués mais juste liés.

copyfile (bool)

Si true, les fichiers attachés au Smart Element (Smart Field de type file ou image ) sont dupliqué aussi. Si false: les fichiers sont liés aux fichiers originaux.

# Valeur de retour

Message d'erreur. Si la chaîne retournée est non nulle, le message indique l'erreur qui a interdit la suppression

# Erreur / Exception

Retourne un message d'erreur dans les cas suivants:

  • pas de droit de créer un Smart Element de la même Smart Structure,
  • retour SmartHooks::PREDUPLICATE non vide,
  • des Smart Fields sont en visibilité I.

Exceptions:

  • Anakeen\Exception("DOC0203") si le Smart Element à dupliquer est invalide.

# Exemple

Duplication du Smart Element référencé par l'identificateur $documentId.

use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument($documentId);
$doc->store();
if ($doc->isAlive()) {
  $copyDoc = $doc->duplicate();
  // maintenant le Smart Element est dupliqué
  if (is_string($copyDoc)) {
    $err = $copyDoc;
    printf("Erreur de duplication %s", $err);
  } else {
    printf("Duplication de %s [%d]", $doc->getTitle(), $doc->id, $copyDoc->getTitle(), $copyDoc->id);
  }
}

Notes

Une entrée dans l'historique du Smart Element dupliqué indique l'origine de la duplication.
Lors de la duplication à l'aide du menu "Dupliquer", le Smart Element dupliqué est inséré dans le même dossier primaire (propriété prelid) que l'origine.

# getArrayRawValues

    array|bool(false) getArrayRawValues( string $idAttr,
                                         int $index = -1)

La méthode getArrayRawValues retourne les valeurs des Smart Fields rattachés à ce Smart Field de type array, sous la forme d'une liste de lignes composées chacune d'un tableau associatif.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field de type array dont on souhaite obtenir les valeurs.

index (int)

index permet de ne retourner qu'une ligne en particulier en spécifiant l'indice (à partir de 0) de la ligne qu'on souhaite obtenir. Si index est égal à -1, alors toutes les lignes sont retournées. Si index est supérieur ou égal au nombre de lignes du tableau, alors une ligne vide est retournée.

# Valeur de retour

La méthode retourne le booléen false s'il y'a une erreur.
Soit le tableau suivant:

attr_1 attr_2 [...] attr_N
$L1_C1 $L1_C2 [...] $L1_CN
[...] [...] [...] [...]
$LM_C1 $LM_C2 [...] $LM_CN

S'il n'y pas d'erreur, la méthode retourne les lignes sous la forme suivante:

array(
    /* Ligne 1 */
    0 => array(
     'attr_1' => $L1_C1, /* Colonne 1 */
            'attr_2' => $L1_C2, /* Colonne 2 */
            […]
            'attr_N' => $L1_CN  /* Colonne N */
        ),

        [...]

        /* Ligne M */
        M => array(
            'attr_1' => $LM_C1,
            'attr_2' => $LM_C2,
            […]
            'attr_N' => $LM_CN
        )
    )

Si une ligne particulière est demandée (utilisation du paramètre index), alors seule la ligne demandée est retournée:

array(
    'attr_1' => $L1_C1, /* Colonne 1 */
    'attr_2' => $L1_C2, /* Colonne 2 */
    [...]
    'attr_N' => $L1_CN  /* Colonne N */
)

# Erreur / Exception

Une erreur est retournée (false) si:

  • le Smart Field idAttr n'est pas de type array.

# Exemple

  • Le Smart Field us_groups est de type array, avec les colonnes us_idgroup de type docid("IUSER") et us_group de type text.
$v = $iuser->getArrayRawValues(SmartStructure\Fields\Iuser::us_groups);
var_dump($v);
  • Résultat:
array(3) {
  [0]=>
  array(2) {
    ["us_group"]=>
    string(3) "Foo"
    ["us_idgroup"]=>
    string(4) "1058"
  }
  [1]=>
  array(2) {
    ["us_group"]=>
    string(3) "Bar"
    ["us_idgroup"]=>
    string(4) "1059"
  }
  [2]=>
  array(2) {
    ["us_group"]=>
    string(3) "Baz"
    ["us_idgroup"]=>
    string(4) "1060"
  }
}

# getAttribute

    BasicAttribute|bool(false) &getAttribute( string $idAttr,
                                               mixed & $oa = null)

La méthode getAttribute permet d'obtenir l'objet PHP (classe BasicAttribute) d'un Smart Field du Smart Element.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field dont on souhaite obtenir l'objet.

oa (mixed)

oa permet de spécifier une variable qui contiendra une référence à la valeur retournée par la méthode.
Cet argument est présent pour compatibilité par rapport à l'historique de la méthode.

# Valeur de retour

La méthode retourne un objet PHP de la classe BasicAttribute si le Smart Field existe ou le booléen false si le Smart Field demandé n'existe pas.

# Erreur / Exception

Si le Smart Field n'existe pas, le booléen false retourné.

# Exemple

/*
 * Obtenir le type du Smart Field "montant"
 */
$oa = $doc->getAttribute(SmartStructure\Fields\Facture::montant);
printf("Le Smart Field '%s' est de type '%s'.", $oa->id, $oa->type);
  • Résultat:
Le Smart Field 'montant' est de type 'money'.

Notes

Le Smart Field demandé peut être un Smart Field déclaré sur la Smart Structure du Smart Element, ou bien un Smart Field déclaré sur une Smart Structure mère. La Smart Structure d'origine du Smart Field est alors consultable via la propriété docid de l'objet de Smart Field qui contient l'identifiant de la Smart Structure qui déclare ce Smart Field.
Cette fonction permet entre autre de modifier les propriétés d'un Smart Field à la volée, ce qui permet de modifier:

  • son libellé, s'il n'est pas traduit,
  • sa visibilité,
  • ses propriétés. Généralement, ces modifications sont faites lors de la preEdition du Smart Element.

# getCustomTitle

    string getCustomTitle()

La méthode getCustomTitle permet de surcharger la méthode de composition du titre par défaut des Smart Elements, et de définir sa propre méthode de composition du titre.
Par défaut, le titre est composé en concaténant la valeur des Smart Fields déclarés avec la caractéristique in_title.

Avertissements

Dans les rapports, la colonne titre est recalculée à l'aide de cette méthode. La particularité des rapports est que la liste des Smart Elements utilisée pour afficher son rapport est composée de Smart Elements incomplets.
Un Smart Element incomplet ne contient qu'un sous ensemble des données du Smart Element. Dans le cas du rapport, il ne contient que les données à afficher.
Par conséquent, si la composition du titre fait appel à des données non présentées, il sera affiché de manière partielle.
Il est possible de prendre en comte ca cas particulier en vérifiant le statut du Smart Element.

public function getCustomTitle() {
    if ($this->doctype === 'I') { // Smart Element incomplet
        return $this->title; // Titre original
    } else {
        // Titre personnalisé
        return $this->myComplexDynamicTitle();
    }
}

# Valeur de retour

La méthode retourne une chaîne de caractères qui est le titre du Smart Element.

# Exemple

namespace Facturation;

class ArchiveFacture extends Anakeen\SmartStructures\Dir
{
  /*
   *   Compose le titre avec la valeur du Smart Field "ref_client" et
   *   l'"id" du Smart Element. Ex. : "ACMECorp-1234"
   */
  public function getCustomTitle()
  {
    return sprintf(
      "%s-%s",
      $this->getAttributeValue(SmartStructure\Fields\ArchiveFacture::ref_client),
      $this->getPropertyValue('id')
    );
  }
}

Notes

Lors de la construction d'un rapport, le Smart Element est incomplet et les valeurs de Smart Fields sont partiellement présents en fonction des colonnes affichées. Si le titre est dépendant d'un Smart Field qui n'est pas présent, le titre présenté dans le rapport peut être incomplet.
Pour s'assurer que le titre présenté est correct, il est possible de retourner le titre "courant" lorsque le Smart Element est incomplet comme le montre l'exemple suivant:

public function getCustomTitle() {
    if ($this->docType === 'I') { // Smart Element incomplet
        return $this->title;
    } else {
        // titre personnalisé
        $mySpecialTitle = sprintf("REF/%d/%d/%s",
                                   $this->initid,
                                   $this->revision,
                                   $this->getAttributeValue(SmartStructure\Fields\ArchiveFacture::ref_client));
        return $mySpecialTitle;
    }
}

# getDate

    string getDate( int $daydelta = 0,
                    int $dayhour = "",
                    int $daymin = "",
                    bool $getLocale = false)

La méthode getDate permet d'obtenir une date du jour compensée par un certain nombre de jours, d'heure ou de minutes.
La date retournée est au format texte international ou au format de la locale de l'utilisateur courant.
La valeur ainsi obtenue est utilisable pour affecter la valeur d'un Smart Field de type date ou timestamp avec la méthode SmartElement::setAttributeValue.

# Liste des paramètres

daydelta (int)

daydelta permet d'appliquer une compensation de la date en nombre de jours:

  • si daydelta est < 0, alors la date retournée est la date courante moins le nombre de jours demandés,
  • si daydelta est > 0, alors la date retournée est la date courante plus le nombre de jours demandés,
  • par défaut, daydelta est égal à 0 ete retourne donc la date courante.

dayhour (int)

dayhour permet d'appliquer une compensation en nombre d'heures:

  • si dayhour est différent de la chaîne vide, alors une compensation exprimée en nombre d'heures est appliquée,
  • par défaut, dayhour est égal à la chaîne vide.

daymin (int)

daymin permet d'appliquer une compensation en nombre de minutes:

  • si daymin est différent de la chaîne vide, alors une compensation exprimée en nombre de minutes est appliquée,
  • par défaut, daymin est égal à la chaîne vide.

getlocale (bool)

getlocale permet de spécifier si la date doit être retournée localisée en fonction de la locale de l'utilisateur courant.
Par défaut, getlocale est égal à false, et la date retournée est au format international.

# Valeur de retour

La date est retournée en texte au format international ou localisé.
Si getlocale est égal à false, alors la date est retournée au format international Y-m-d ou Y-m-d H:i s'il y a eu ajout d'heures ou de minutes.
Si getlocale est égal à true, alors la date est retournée au format défini par la locale de l'utilisateur courant.

# Exemple

Obtenir la date d'hier, d'aujourd'hui et de demain:

/*
 * Date d'hier : -1 jour
 */
var_dump($doc->getDate(-1));

/*
 * Date du jour
 */
var_dump($doc->getDate());

/*
 * Date de demain : +1 jour
 */
var_dump($doc->getDate(1));
  • Résultat:
string(10) "2013-12-24"
string(10) "2013-12-25"
string(10) "2013-12-26"

Notes

Les compensations daydelta, dayhour et daymin sont cumulatives.

# getFamilyDocument

    SmartStructure|null getFamilyDocument()

La méthode getFamilyDocument permet d'obtenir l'objet SmartStructure de la Smart Structure du Smart Element courant.

# Valeur de retour

La méthode retourne l'objet SmartStructure de la Smart Structure du Smart Element courant ou null en cas d'erreur.

# Erreur / Exception

La méthode retourne la valeur null s'il y a une erreur d'inclusion du fichier PHP déclaration de la Smart Structure du Smart Element courant.

# Exemple

$fam = $doc->getFamilyDocument();

printf("Le Smart Element '%s' est issue de la Smart Structure '%s'.", $doc->getTitle(), $fam->getTitle());

# getFamilyParameterValue

    string getFamilyParameterValue( string $idp,
                                    string $def = "")

La méthode getFamilyParameterValue permet d'obtenir la valeur des paramètres de la Smart Structure du Smart Element courant.

# Liste des paramètres

idp (string)

Le nom du paramètre dont on souhaite obtenir la valeur.

def (string)

def permet de spécifier la valeur par défaut retournée par la méthode si le nom du paramètre idp n'existe pas.
Par défaut, la valeur est une chaîne vide.

# Valeur de retour

La méthode retourne la valeur du paramètre demandé, ou la valeur par défaut def si le paramètre demandé n'existe pas.
Dans le cas où le paramètre est défini sur une Smart Structure parente et que la valeur pour la Smart Structure est vide, alors la valeur de la Smart Structure parente sera retournée. La recherche de la valeur se fait sur toute l'ascendance jusqu'à trouver une valeur non vide.
Si en définitive, la valeur des parents est aussi vide, alors la valeur def sera retournée.

# Erreur / Exception

Si le Smart Field demandé n'existe pas, la valeur par défaut def est retournée.

# Exemple

La Smart Structure Facture comporte un paramètre qui permet de spécifier la valeur du taux de TVA:

/*
 * Lire le taux de TVA défini sur le paramètre TAUX_TVA de la Smart Structure `$facture`
 */
$tva = $facture->getFamilyParameterValue('TAUX_TVA', 0);
if ($tva <= 0) {
  throw new Exception(sprintf("Le taux de TVA doit être > 0 !"));
}

# getMultipleRawValues

    mixed getMultipleRawValues( string $idAttr,
                                string $def = "",
                                int $index = -1)

La méthode getMultipleRawValues permet d'obtenir les valeurs de Smart Fields multi-valués.
Ceux-ci peuvent être:

  • des Smart Fields déclarés avec l'option multiple=yes,
  • des Smart Fields rattachés à un Smart Field de type array.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field multi-valué dont on souhaite obtenir les valeurs.

def (string)

def permet de spécifier la valeur par défaut qui sera retournée si le Smart Field n'est pas valué.
Par défaut, la valeur est une chaîne vide.

index (int)

index permet d'obtenir la valeur à un indice (à partir de 0) donné.

  • si index est égal à -1, alors toutes les valeurs du Smart Field sont retournées,
  • si index est supérieur ou égal au nombre de valeurs, alors la valeur par défaut définie par def est retournée.

# Valeur de retour

La méthode retourne:

  • la valeur (scalaire), si le paramètre index est différent de -1,
  • les valeurs (array) si index vaut -1,
  • ou la valeur scalaire par défaut def si le Smart Field n'est pas valué.

# Exemple

  • Le Smart Field us_groups est de type array, avec les colonnes us_idgroup de type docid("IUSER") et us_group de type text.
/*
 * Obtenir l'ensemble des valeurs de la colonne `us_group`
 */

$v = $iuser->getMultipleRawValues(SmartStructure\Fields\Iuser::us_group);
var_dump($v);
  • Résultat:
array(3) {
  [0]=>
  string(3) "Foo"
  [1]=>
  string(3) "Bar"
  [2]=>
  string(3) "Baz"
}
  • Le Smart Field us_groups est de type array, avec les colonnes us_idgroup de type docid("IUSER") et us_group de type text.
/*
 * Obtenir la deuxième valeur de la colonne `us_group`
 */

$v = $iuser->getMultipleRawValues(SmartStructure\Fields\Iuser::us_group, "", 1);
var_dump($v);
  • Résultat
string(3) "Bar"

# getOldRawValue

    string getOldRawValue( string $idAttribute )

Cette méthode récupère la valeur précédent l'appel aux méthodes de modification de valeurs de Smart Fields. Si la valeur précédente est inchangée suite à l'appel d'une méthode de modification, la méthode retournera le booléen false.
Les principales méthodes de modification de valeur sont :

Avertissements

Cette méthode ne récupère que les valeurs changées sur un objet. Si on instancie deux fois le même Smart Element, alors les modifications de l'un ne sont pas répercutées sur l'autre.
Si le Smart Field n'a pas encore été modifié, la valeur de retour est false (après une création). Les enregistrements de valeurs modifiés sont remis à zéro lors d'une révision (SmartElement::revise).

# Liste des paramètres

idAttribute (string)

Identifiant du Smart Field.

# Valeur de retour

La valeur de retour indique la valeur brute précédente à la modification.

setValue getRawValue getOldValue
"vert" "vert" false
"jaune" "jaune" "vert"
"bleu" "bleu" "jaune"
"bleu" "bleu" "jaune"
null null "bleu"

Si la valeur n'a pas encore été changée, le retour est false.
Si l'identifiant du Smart Field n'existe pas, le retour est également false.

# Exemple

# Evolution du retour de getOldRawValue

Le Smart Element de l'exemple a son Smart Field my_numberone initialisé à -3.

use SmartStructure\Fields\MyFamily as MyAttr;
use Anakeen\SmartElementManager;

function printOldValue(SmartElement $doc)
{
  printf("    Valeur:");
  var_dump($doc->getRawValeur(MyAttr::my_numberone));
  printf("Ancienne valeur:");
  var_dump($doc->getOldRawValue(MyAttr::my_numberone));
  printf("#-------------------------------------------\n");
}

function updateValue(SmartElement $doc, $newValue)
{
  if ($newValue === null) {
    printf("    Efface valeur :null");
    $doc->clearValue(MyAttr::my_numberone, $newValue);
  } else {
    printf("    mis à jour valeur :");
    var_dump($newValue);
    $doc->setValue(MyAttr::my_numberone, $newValue);
  }
}
/**@var Anakeen\SmartStructures\MyFamily */
$myDoc = SmartElementManager::createDocumen("MY_DOCUMENT");
if ($myDoc->isAlive()) {
  printOldValue($myDoc);

  updateValue($myDoc, 34);
  printOldValue($myDoc);

  updateValue($myDoc, 35);
  printOldValue($myDoc);

  updateValue($myDoc, 35);
  printOldValue($myDoc);

  updateValue($myDoc, null);
  printOldValue($myDoc);

  updateValue($myDoc, 35);
  printOldValue($myDoc);
}
  • Résultat:
         Valeur :string(2) "-3"
Ancienne Valeur :bool(false)
#---------------------
     maj valeur :int(34)
         Valeur :string(2) "34"
Ancienne Valeur :string(2) "-3"
#---------------------
     maj valeur :int(35)
         Valeur :string(2) "35"
Ancienne Valeur :string(2) "34"
#---------------------
     maj valeur :int(35)
         Valeur :string(2) "35"
Ancienne Valeur :string(2) "34"
#---------------------
  efface valeur :null
         Valeur :string(0) ""
Ancienne Valeur :string(2) "35"
#---------------------
     maj valeur :int(35)
         Valeur :string(2) "35"
Ancienne Valeur :string(0) ""
#---------------------

# getOldRawValues

    string[] getOldRawValues()

Cette méthode récupère la liste des valeurs des Smart Fields modifiés depuis l'instanciation de l'objet SmartElement. Voir SmartElement::getOldRawValue() pour plus de détails.

# Valeur de retour

Retourne un tableau indexé par l'identifiant du Smart Field (en minuscules). Chaque Smart Fields modifiés a sa propre entrée dans le tableau. Les Smart Fields non modifiés n'ont pas d'entrée dans le tableau.

# Exemple

Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MyStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 30 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 30 R ::mySum(MY_NUMBERONE,MY_NUMBERTWO)
END

avec la classe :

namespace My;
use SmartStructure\Fields\MyFamily as MyAttributes;

class MyFamily extends Anakeen\SmartElement
{
  public function mySum($x, $y)
  {
    return $x + $y;
  }
}

Le code suivant indique le résultat de getOldRawValues():

if ($myDoc->isAlive()) {
  print "### Valeurs initiales ###\n";
  print_r($myDoc->getValues());
  $myDoc->setValue(MyAttributes::my_numberone, 342);
  $myDoc->setValue(MyAttributes::my_numbertwo, 352);
  $myDoc->refresh();

  print "### Nouvelles valeurs ### \n";
  print_r($myDoc->getValues());

  print "### Anciennes valeurs modifiées ### \n";
  print_r($myDoc->getOldRawValues());
}
  • Résultat:
### Valeurs initiales ###
Array
(
    [my_numberone] => 34
    [my_numbertwo] => 35
    [my_sum] => 69
    [my_redactor] => 5838
)

### Nouvelles valeurs  ###
Array
(
    [my_numberone] => 342
    [my_numbertwo] => 352
    [my_sum] => 694
    [my_redactor] => 5838
)
### Anciennes valeurs modifiées  ###
Array
(
    [my_numberone] => 34
    [my_numbertwo] => 35
    [my_sum] => 69
)

# getPropertyValue

    string|bool (false) getPropertyValue( string $prop )

La méthode getPropertyValue permet d'obtenir les valeurs des propriétés du Smart Element courant (telles que id, initid, revision, etc...).

# Liste des paramètres

prop (string)

Le nom de la propriété dont on souhaite obtenir la valeur.

# Valeur de retour

La méthode retourne la valeur de la propriété demandée, ou false si a propriété demandée n'existe pas.

# Erreur / Exception

La méthode retourne false si la propriété demandée n'existe pas.

# Exemple

/*
 * Obtenir la date de création du Smart Element
 */
$cdate = $doc->getPropertyValue('cdate');

# getState

    string getState()

La méthode getState retourne le nom de l'état du Smart Element si celui-ci est associé à un cycle de vie.

# Valeur de retour

La méthode retourne le nom de l'état du Smart Element si celui-ci est associé à un cycle de vie. Si le Smart Element ne possède pas de cycle, alors une chaîne vide est retournée.

# Exemple

Contrôler que la facture est dans l'état Payée (PAID):

$state = $facture->getState();
if ($state !== 'PAID') {
  throw new Exception(sprintf("La facture '%s' n'est pas dans l'état payée.", $facture->getTitle()));
}

Notes

Cette fonction est un raccourci vers la propriété state du Smart Element. Pour avoir la version affichée dans l'interface de l'état, il suffit de traduire celui-ci avec la fonction _.

# getTitle

    string getTitle( mixed $id = -1,
                     string $def = "",
                     bool $latest = false )

La méthode getTitle permet de récupérer le titre:

  • du Smart Element courant,
  • d'un Smart Element donné en spécifiant son identifiant (numérique ou logique),
  • ou d'un ensemble de Smart Element en spécifiant leur identifiants (numérique ou logique).

Avertissements

Bien que la méthode getTitle accepte de travailler sur plusieurs Smart Elements, il est préférable d'utiliser la classe DocTitle pour travailler sur un grand nombre de Smart Elements.

# Liste des paramètres

id (mixed)

id permet de spécifier le ou les Smart Elements dont on souhaite obtenir le titre.

  • si id est égal à -1, alors le titre du Smart Element courant est retourné,
  • si id est l'identifiant numérique ou le nom logique d'un Smart Element, alors le titre du Smart Element correspondant est retourné,
  • si id est de la forme {firstId, secondId, ..., nId}, alors id est traité comme étant une liste d'identifiants de Smart Elements (identifiant numérique ou nom logique). Attention: Dans le cas où id est un array, la valeur par défaut est retournée , sans erreur.
    La valeur par défaut de id est -1.

def (string)

def permet de spécifier la valeur par défaut qui sera retournée si le Smart Element n'existe pas.
Par défaut, la valeur est une chaîne vide.

latest (bool)

latest permet de spécifier si l'on souhaite obtenir le titre de la dernière révision du Smart Element.
Par défaut, latest est égal à false et donc c'est le titre du Smart Element référencé par l'identifiant qui est retourné ( et non celui de la dernière révision).

# Valeur de retour

La méthode retourne une chaîne de caractère contenant le titre du Smart Element demandé, ou les titres des Smart Elements demandés, séparés par le caractère \n.

# Exemple

    var_dump($doc->getTitle());
    /* Résultat
    * string (27) "Titre Smart Element courant"
    */

    var_dump($doc->getTitle(1234));
    */ Résultat
    * string(24) "Titre Smart Element 1234"
    */

    var_dump($doc->getTitle($doc->arrayToRawValue(array(1234,2345,3456))));
    /* Résultat
    * string(80) "Titre Smart Element 1234
    * Titre Smart Element 2345
    * Titre Smart Element 3456"

Notes

Si le Smart Element, dont on souhaite obtenir le titre, est confidentiel, et que l'utilisateur courant n'a pas le droit confidential, alors le titre retourné est "Smart Element confidentiel".

# getRawValue

    string getRawValue( string $idAttribute, mixed $defaultValue = "")

Cette méthode retourne la valeur d'un Smart Field telle qu'elle est inscrite en base de données. Le type retourné est toujours une chaîne de caractères quel que soit le type de Smart Field.

# Liste des paramètres

idAttribute (string)

Identifiant du Smart Field.

defaultValue (string)

Valeur par défaut à retourner si la valeur est vide ou si le Smart Field n'existe pas.

# Valeur de retour

Si le Smart Field du Smart Element existe et s'il n'est pas vide, sa valeur brute est retournée.
Cette méthode retourne tout Smart Field de la classe sans vérification. Si ce Smart Field est non existant ou vide alors c'est la valeur par défaut qui sera retournée.

# Exemple

Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MyStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 30 R ::mySum(MY_NUMBERONE,MY_NUMBERTWO)
END

Utilisation des valeurs de my_numberone et my_numbertwo pour la méthode mySum du Smart Field calculé my_sum.
Avec la classe:

namespace My;
use SmartStructure\Fields\MyFamily as MyAttributes;

class MyFamily extends Anakeen\SmartElement
{
  public function mySum($x, $y)
  {
    $n1 = intval($this->getRawValue(MyAttributes::my_numberone));
    // si "my_numbertwo" est vide, alors la valeur sera 543
    $n2 = intval($this->getRawValue(MyAttributes::my_numbertwo, "543"));
    return $n1 + $n2;
  }
}

Vérification du Smart Field my_sum en fonction des valeurs de my_numberone et my_numbertwo.

use SmartStructure\Fields\MyFamily as Attributes\MyFamily;
use Anakeen\SmartElementManager;

    $myDoc = SmartElementManager::createDocument("MY_DOCUMENT");
    $myDoc->store();
    if ($myDoc->isAlive()) {
        $n1 = intval($myDoc->getRawValue(Attributes\MyFamily::my_numberone));
        $n2 = intval($myDoc->getRawValue(Attributes\MyFamily::my_numbertwo,"543"));
        $sum = intval($myDoc->getRawValue(attributes\MyFamily::my_sum));
        if ($sum !== ($n1 + $n2)) {
            printf("La somme est incorrecte : %d + %d <> %d ! \n", $n1, $n2, $sum);
        }
    }

Notes

Format brut en fonction des types de Smart Fields:

date

Les dates sont retournées sous la forme "YYYY-MM-DD".

timestamp

Les horo-dates sont retournées sous la forme "YYYY-mm-DD HH:MM:SS".

time

Les temps sont retournés sous la forme "HH:MM:SS".

file, image

Les pointeurs de fichiers sous la forme [mimeType]|[vaultId]|[filename].

htmltext

Le texte retourné est un fragment html dont les entités html (caractères accentués notamment) ont été convertis en caractères utf-8.

Pour les autres types, aucun formatage spécial n'est appliqué, la valeur brute correspond à la valeur donnée.
Pour les valeurs multiples, chaque valeur est séparée par le caractère , (virgule).
Pour les multiples à 2 niveaux (Smart Field multiple dans un tableau), le premier niveau a comme séparateur le caractère , et le deuxième niveau est un autre tableau de la forme {firstId, secondId, ..., nId}.

Exemple: { { 1234 } , { 567 , 8876 , 987 } , { 678 , 295 } } indique la structure à 2 niveaux suivante:

1. -
    - 1. 1234
2. -
    - 1. 567
    - 2. 8876
    - 3. 987
3. -
    - 1.678
    - 2.295

# getAttributeValue

    mixed getAttributeValue( string $idAttribute)

La méthode retourne la valeur typée d'un Smart Field du Smart Element.

Avertissements

Le retour de cette méthode peut être utilisé pour mettre à jours des valeurs avec la méthode SmartElement::setAttributeValue(). Par contre, ces valeurs typées sont incompatibles avec la méthode SmartElement::setValue() qui prend un argument des valeurs brutes.

# Liste des paramètres

idAttribute [int](string)

Identifiant du Smart Field.

# Valeur de retour

Retourne la valeur typée du Smart Field en fonction des types de Smart Fields:

  • date, timestamp

    Les dates sont retournées avec un objet de la classe DateTime (classe interne de PHP).

  • time

    Les temps sont retournés avec le type string sous la forme "HH:MM:SS".

  • file, image

    Les pointeurs des fichiers sont retournés sous la forme [mimeType]|[vaultId]|[filename].

  • int

    Les nombres entiers sont retournés avec le type int.

  • double, money Les nombres décimaux sont retournés avec le type float.

Les autres types sont retournés sous forme de chaîne de caractère (type string).
Les valeurs multiples sont retournées avec un objet de type array. Les valeurs multiples ayant aussi des valeurs multiples (cas des Smart Field multiples dans les tableaux) sont retournés avec un objet de type array[] (tableau à 2 dimensions).
Si une valeur est vide, la valeur null sera retournée. Dans le cas d'un attribut multiple, le retour pour une valeur vide (aucune valeur) sera un tableau vide array().
Pour les Smart Field de type array, la valeur retournée est un tableau à deux dimensions. La première dimension est l'index (numérique - 0 à n) de la rangée et la deuxième est l'identifiant de l'attribut. Chaque élément contient une valeur typée.

# Erreur / Exception

Retourne une exception Anakeen\Exception dans les cas suivants:

  • le Smart Field n'existe pas,
  • ou si le Smart Field ne contient pas de valeur (type tab, frame ou menu).

# Exemple

Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MyFamily
DFLDID auto
ICON classe.png
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 40 R ::mySum(MY_NUMBERONE,MY_NUMBERTWO)
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 50 W
ATTR MY_REF MY_IDENTIFICATION Référence N N text 70 W
ATTR MY_T_PARTNER MY_IDENTIFICATION participants N N array 80 W
ATTR MY_COAUTHORS MY_T_PARTNER co-auteurs N N account 90 W
ATTR MY_CODATE MY_T_PARTNER date d'entrée N N date 10 W
END
  • Vérification du Smart Field my_sum en fonction des valeurs de my_numberone et my_numbertwo.
use SmartStructure\Fields\MyFamily as MyAttributes;
use Anakeen\SmartElementManager;

    $myDoc = SmartElementManager::createDocument("MY_DOCUMENT");
    $myDoc->store();
    if ($myDoc->isAlive()) {
        $n1 = $myDoc->getAttributeValue(MyAttributes::my_numberone,
        $n2 = $myDoc->getAttributeValue(MyAttributes::my_numbertwo),
        $sum = $myDoc->getAttibuteValue (MyAttributes,::my_sum).

Retour d'un tableau. Le Smart Element a deux rangées.

use SmartStructure\Fields\MyStructure as MyAttributes;
use Anakeen\SmartElementManager;

$myDoc = SmartElementManager::createDocument("MY_DOCUMENT");
$myDoc->store();
if ($myDoc->isAlive()) {
  $participants = $myDoc > getAttributeValue(MyAttributes::my_t_partner);
  print_r($participants);
}
Array
(
    [0] => Array
        (
            [my_coauthors] => "5838"
            [my_codate] => DateTime Object
                (
                    [date] => "2013-07-04 00:00:00"
                    [timezone_type] => 3
                    [timezone] => Europe/Paris
                )
        )
    [1] => Array
        (
            [my_coauthors] => "5837"
            [my_codate] => DateTime Object
                (
                    [date] => "2013-06-11 00:00:00"
                    [timezone_type] => 3
                    [timezone] => "Europe/Paris"
                )
        )
)

# isAlive

    bool isAlive()

La méthode isAlive permet de savoir si un Smart Element est vivant.
Un Smart Element est vivant si:

  • le Smart Element est stocké en base de données,
  • la propriété doctype est différente de Z.

# Valeur de retour

La méthode retourne true si le Smart Element est vivant ou false dans le cas contraire.

# Exemple

use Anakeen\SmartElementManager;

    $facture = SmartElementManager::createDocument($id);
    $facture->store();
    if (!$facture->isAlive()) {
        throw new Exception(sprintf" Le Smart Element avc l'identifiant '%d' n'existe pas ou a été supprimé.", $id));
    }
use Anakeen\SmartElementManager;
/*
 * $facture est un objet qui n'existe qu'en mémoire,
 * par conséquent, isAlive() retourne `false`
 */
$facture = SmartElementManager::createDocument('FACTURE');
$facture->store();
var_dump($facture->isAlive());

/*
 * Une fois l'objet sauvegardé en base de données
 * isAlive() retourne alors `true`
 */
$facture->store();
var_dump($facture->isAlive());
  • Résultat
bool(false)
bool(true)

# isChanged

    bool isChanged()

La méthode isChanged permet de savoir si des Smart Fields du Smart Element ont été changés via l'utilisation de méthodes de modification des valeurs de Smart Fields (par exemple SmartElement::setValue ou SmartElement::clearValue).

# Valeur de retour

La méthode retourne true si au moins une valeur a été changée, ou false si aucune valeur n'a été changée.

# Exemple

Lors de la validation du formulaire d'édition d'un Smart Element, il est possible de détecter avec la méthode isChanged si l'utilisateur a changé la valeur d'un Smart Field ou non.

namespace Facturation;

class Facture extends Anakeen\SmartElement
{
    public function registerHooks()
    {
        parent::registerHooks();
        $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
            if ($err = parent::postStore()) !== "") {
                return $err;
            }

            /*
            * Régénérer le PDF seulement si quelque chose
            * a été changé sur la facture.
            */
            if ($this->isChanged()) {
                return $this->generate_PDF();
            }
            return "";
        });
    }
}

Notes

Le statut de modification est remis à false après le déclenchement des méthodes SmartElement::postInsert et SmartElement::postUpdate.

# getLatestId

    int|bool (false) getLatestId( bool $fixed = false,
                                  bool $forcequery = false)

La méthode getLatestId permet d'obtenir l'identifiant de la dernière révision du Smart Element, si le Smart Element est révisable, ou est associé à un cycle de vie.

# Liste des paramètres

fixed (bool)

fixed permet d'indiquer qu'on souhaite obtenir l'identifiant de la dernière révision figée ( voir propriété lmodify).
Par défaut, fixed vaut false, et c'est l'identifiant de la dernière révision qui est retourné (indépendamment du fait que ce soit une révision figée ou non).

forcequery (bool)

forcequery permet de forcer l'exécution d'une requête en base de données pour rechercher la dernière révision.
Par défaut forcequery vaut false, et une nouvelle requête en base de données n'est pas exécutée pour la recherche de la dernière révision. Si ce paramètre n'est pas passé à true l'id retourné est le dernier id connu lors de la récupération du Smart Element en base.

# Valeur de retour

La méthode retourne l'identifiant de la dernière révision lorsque cette dernière est trouvée, sinon le booléen false est retourné en cas d'erreur.

# Erreur / Exception

La méthode retourne false si la propriété id du Smart Element est vide.

# Exemple

/*
 * Obtenir l'identifiant de la dernière révision
 * de la facture
 */
$latestId = $facture->getLatestId();
/*
 * Imprimer cette dernière révision de la facture
 */
imprimerFacture($latestId);

# rawValueToArray

    array rawValueToArray( string $v)

La méthode rawValueToArray permet de dé-sérialiser une valeur sous la forme d'une chaîne de caractères issue d'un Smart Field faisant parti d'un array, ou d'un Smart Field multi-valué, obtenue via la méthode SmartElement::getRawValue.

Avertissements

La méthode **rawValueToArray est une méthode de bas niveau qu'il ne faut utiliser qu'en dernier recours.
Il faut privilégier l'utilisation de la méthode **getAttributeValue** qui prend en charge automatiquement ces opérations de dé-sérialisation.

# Liste des paramètres

v (string)

La chaîne de caractères à dé-sérialiser.

# Valeur de retour

La méthode rawValueToArray retourne un array contenant les valeurs issues de la chaîne de caractères fournie.

# Exemple

Le Smart Field PHOTO_KEYWORDS est un Smart Field de type texte avec l'option multiple.

$v = $photo->getRawValue(SmartStructure\Fields\MyPhoto::photo_keywords);
var_dump($photo->rawValueToArray($v));
  • Résultat
array(4) {
  [0]=>
  string(11) "Tour Eiffel"
  [1]=>
  string(13) "Champ de Mars"
  [2]=>
  string(5) "Paris"
  [3]=>
  string(6) "France"
}

# removeArrayRow

    string removeArrayRow( string $idAttr,
                           int $index)

La méthode removeArrayRow permet de supprimer une ligne à un indice donnée dans un Smart Field de type array.
La ligne supprimée entraîne un décalage des lignes d'indice supérieur, qui descendent alors toutes d'un cran.

Avertissements

Lors de chaque appel à removeArrayRow, un setValue est effectué pour chacune des colonnes de l'array. Pour supprimer de nombreuses lignes, il peut être plus efficace de gérer manuellement la suppression dans chaque colonne.

# Liste des paramètres

idAttr (string)

Le nom du Smart Field de type array dans lequel on souhaite supprimer une ligne.

index (int)

index permet de spécifier l'indice ( à partir de 0 ) de la ligne qu'on souhaite supprimer.
Si index est inférieur à 0 ou supérieur ou égal au nombre de lignes du tableau, alors le tableau n'est pas modifié et reste inchangé.

# Valeur de retour

La méthode re'tourne 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.

# Erreur / Exception

Une erreur est retournée si le Smart Field idAttr n'est pas de type array.

# Exemple

/* Soit le tableau `MyPhoto::faces` composé comme suit :

   +-----------+----------+
   | Firstname | Lastname |
   +===========+==========+
#0 | Bart      | Simpson  |
#1 | Marge     | Simpson  |
#2 | Lisa      | Simpson  |
#3 | Homer     | Simpson  |
   +-----------+----------+
*/

$photo->removeArrayRow(SmartStructure\Fields\MyPhoto::faces, 0)

/* Après la suppression de la première ligne (indice 0) :

   +-----------+----------+
   | Firstname | Lastname |
   +===========+==========+
#0 | Marge     | Simpson  |
#1 | Lisa      | Simpson  |
#2 | Homer     | Simpson  |
   +-----------+----------+
*/

$photo->removeArrayRow(SmartStructure\Fields\MyPhoto::faces, 1)

/* Après la suppression de la ligne entre Marge et Homer (indice 1) :

   +-----------+----------+
   | Firstname | Lastname |
   +===========+==========+
#0 | Marge     | Simpson  |
#1 | Homer     | Simpson  |
   +-----------+----------+
*/

# refresh

    string refresh()

Cette méthode est appelée depuis l'interface lors de la consultation du Smart Element unitaire mais pas depuis les interfaces présentant les listes de Smart Elements.
Cette méthode est appelée depuis la méthode SmartElement::store().

Avertissements

Les Smart Fields calculés en visibilité I ne sont pas mis à jour. La visibilité appliquée est celle donnée par le contrôle de vue (vue par défaut).

# Valeur de retour

Cette méthode retourne les messages fournis par les hooks preRefresh() et postRefresh(). Ce message est présenté sur l'interface web de consultation de Smart Element lors de l'affichage du Smart Element.

# Exemple

Actualisation d'un ensemble de Smart Elements.

use Anakeen\Search\SearchElements;

$s = new SearchElements("MYFAMILY");

$dl = $s->search()->getResults();

$messages = array();
foreach ($dl as $doc) {
  $messages[$doc->id] = $doc->refresh();
}

Notes

Lors de l'actualisation du Smart Element, les hooks suivants sont lancés:

Les affectations des Smart Fields calculés sont réalisées par la méthode specRefreshGen() qui est générée lors de l'importation de la Smart Structure. Cette méthode est appelée entre les hooks SmartElement::preRefresh() et SmartElement::postRefresh().

# revise

    string revise( string $comment = '')

Le Smart Element courant est enregistré en base et est figé. Sa propriété locked vaut alors -1. La méthode SmartElement::isFixed() permet de savoir si un Smart Element est figé.
Une copie du Smart Element est créée. Un nouvel identifiant est créé et est affecté à la propriété id. Le Smart Element conserve le même identifiant initial (propriété initid) et son numéro de révision (propriété revision) est incrémenté de un.
L'objet courant devient le nouveau Smart Element avec un nouvel identifiant.

Avertissements

Un Smart Element figé ne peut pas être révisé. Un Smart Element qui n'a pas d'identifiant ne peut pas être révisé.

# Liste des paramètres

comment (string)

si comment n'est pas vide, le message sera ajouté à l'historique avant la révision.

# Valeur de retour

Message d'erreur. Si un message non vide est retourné alors la révision a été abandonnée ( la raison est donnée par le message d'erreur).

# Erreur / Exception

Les causes d'erreurs sont :

  • Smart Element figé,
  • problème de droits: la révision nécessite le droit edit sur le Smart Element et le droit create sur la Smart Structure du Smart Element,
  • retour d'erreur de hook preRevise().

# Exemple

Exemple de création d'une révision.

use Anakeen\SmartElementManager;

$d = SmartElementManager::createDocument("MY_DOCUMENT");
$d->store();
if ($d->isAlive()) {
  printf("Identifiant %d\n", $d->id);
  $err = $d->revise();
  if (empty($err)) {
    printf("Nouvel identifiant %d", $d->id);
  } else {
    printf("Erreur de révision %s", $err);
  }
}

Notes

Lors d'un ajout de Smart Element, les hooks suivants sont lancés:

# Hook preRevise

Le hook preRevise a pour rôle de valider les conditions de révision du Smart Element. Si cette méthode retourne une chaîne de caractère non-vide alors elle est considérée comme un retour d'erreur et la révision n'est pas effectuée. Ce message est retourné par la méthode SmartElement::revise().

# Hook postRevise

Le hook postRevise a pour rôle de réaliser un post-traitement après la révision. Cette méthode utilise la nouvelle révision. Si cette méthode retourne une chaîne de caractères non-vide, alors elle est considérée comme un message d'erreur. Ce message est enregistré dans l'historique du Smart Element.

# setState

string setState ( string $newstate,
                  string $comment     = '',
                    bool $force       = false,
                    bool $withcontrol = true,
                    bool $wm1         = true,
                    bool $wm2         = true,
                    bool $wneed       = true,
                    bool $wm0         = true,
                    bool $wm3         = true,
                string & $msg         = '' )

La méthode setState permet de changer l'état du Smart Element si celui-ci a un cycle de vie associé.

# Liste des paramètres

newstate (string)

newstate est le nom de l'état de destination dans lequel on souhaite mettre le Smart Element.

comment (string)

comment permet de spécifier un commentaire facultatif qui est inscrit dans l'historique du Smart Element suite à son changement d'état.
Par défaut, comment est une chaîne vide, et aucun message additionnel n'est inscrit dans l'historique du Smart Element.

force (bool)

force permet de forcer le changement d'état pour le cas ou l'état demandé n'est pas associé à une transition valide du cycle de vie.
Par défaut force est à false, et le nouvel état demandé de destination doit alors avoir une transition valide avec l'état actuel ( de départ) du Smart Element.

withcontrol (bool)

withcontrol permet de désactiver le contrôle des droits sur les transitions du cycle.
Par défaut, withcontrol est à true, et le contrôle des droits sur les transitions du cycle est appliqué.

wm1 (bool)

wm1 permet de spécifier si la méthode m1 de la transition doit être appliquée.
Par défaut, wm1 est à true, et la méthode m1 de la transition est appliquée.

wm2 (bool)

wm2 permet de spécifier si la méthode m2 de la transition doit être appliquée.
Par défaut, wm2 est à true, et la méthode m2 de la transition est appliquée.

wneed (bool)

wneed permet de spécifier si le contrôle des Smart Fields obligatoire du Smart Element doit être appliqué.
Par défaut, wneed est à true, et le contrôle des Smart Fields obligatoire du Smart Element est appliqué.

wm0 (bool)

wm0 permet de spécifier si la méthode m0 de la transition doit être appliquée.
Par défaut, wm0 est à true, et la méthode m0 de la transition est appliquée.

wm3 (bool)

wm3 permet de spécifier si la méthode m3 de la transition doit être appliquée.
Par défaut, wm3 est à true, et la méthode m3 de la transition doit être appliquée.

msg (string)

msg est une référence facultative à une chaîne de caractères qui est retournée par la méthode et qui contient les messages retournées par les méthodes m1, m2 et l'émission des mails déclarés sur le cycle.

# Valeur de retour

La méthode retourne une chaîne vide s'il n'y a pas d'erreurs, ou une chaîne non-vide contenant un message d'erreur si la transition n'a pas pu être réalisée.

# Erreur / Exception

La méthode retourne un message d'erreur si :

  • l'état newstate demandé est vide,
  • le Smart Element n'a pas de cycle de vie,
  • le cycle de vie associé au Smart Element n'existe pas,
  • le cycle de vie associé au Smart Element est corrompu (ex. syntaxe PHP invalide),
  • l'état newstate de destination n'existe pas ou n'est pas associé à une transition valide et que force est à false,
  • l'état newstate de destination n'existe pas ou n'est pas associé à une transition valide et que l'utilisateur n'est pas le super-utilisateur admin,
  • wm0 est à true et la méthode m0 n'existe pas,
  • wm0 est à true et l'exécution de la méthode m0 a retournée un message d'erreur,
  • wm1 est à true et la méthode m1 n'existe pas,
  • wm1 est à true et l'exécution de la méthode m1 a retournée un message d'erreur,
  • wneed est à true et le contrôle des Smart Fields obligatoire a retourné un message d'erreur,
  • la révision ou l'inscription du Smart Element en base de données ont retournés un message d'erreur,
  • wm2 est à true et la méthode m2 n'existe pas,
  • wm3 est à true et la méthode m3 n'existe pas,
  • le changement d'affectation du Smart Element déclaré sur le cycle, a retourné un message d'erreur.

# Exemple

/*
 * Mettre la facture dans l'état 'Archivé'
 */
$err = $facture->setState("ST_ARCHIVED");
if ($err !== "") {
  throw new Exception(sptrinf("La facture n'a pas pu être archivée: %s", $err));
}

Notes

Pour qu'il y ait changement d'état, il faut que l'état newstate de destination demandé ait une transition valide depuis l'état de départ actuel du Smart Element.
S'il n'y a pas de transitions entre l'état de départ actuel du Smart Element et le nouvel état newstate demandé, alors une erreur est remontée.
Dans ce cas, pour forcer le changement d'état, il faut utiliser le paramètre force avec une valeur à true.

# setValue

    string setValue( string $attributeIdentifier,
                     string|string[] $value,
                     int $index = -1,
                     int &$kvalue = null)

Cette méthode modifie la valeur d'un Smart Field de l'objet SmartElement. La modification n'est pas enregistrée en base de données.

Avertissements

Pour enregistrer la modification, il est nécessaire d'appeler la méthode **SmartElement::store().
Les résultats fournis par la méthode SmartElement::getAttributeValue() ne peuvent pas être utilisés directement par cette méthode.
Si la valeur est une chaîne vide ou égale à null, alors la valeur du Smart Field n'est pas modifiée. Si la valeur est égale à un espace ``, la valeur est effacée.
Les espaces et certains caractères invisibles en début et fin de valeur sont supprimés. La fonction trim est utilisée pour réaliser cette suppression.

# Liste des paramètres

attributeIdentifier (string)

Identifiant du Smart Field à modifier

value (string|string[])

Nouvelle valeur brute. Dans le cas d'un Smart Field multiple, il est possible d'indiquer les différentes valeurs brutes dans un tableau.

index (int)

Dans le cas où le Smart Field est multiple, indique l'index de la valeur à modifier.

kvalue (int)

En cas d'erreur et dans le cas où le Smart Field est multiple, indique l'index de la première valeur erronée du Smart Field multiple.

# Valeur de retour

Message d'erreur. Retourne une chaîne vide s'il n'y a pas d'erreur.

# Erreur / Exception

En cas d'erreur, un message non vide est retourné. LEs principales causes d'erreurs sont :

  • insuffisance de privilèges . nécessite le droit edit,
  • Smart Field inexistant,
  • contenu de la valeur incohérent par rapport au type de Smart Field,
  • visibilité I sur le Smart Field.

# Exemple

Calcul de la somme des Smart Fields my_numberone et my_numbertwo et enregistrement dans le Smart Field my_sum. Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MyStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 30 R
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 30 R
ATTR MY_MAIL MY_IDENTIFICATION adresse courriel N N text 10 R
END
# Mise a jour de Smart Field après modification du Smart Element

Le rédacteur est le dernier à avoir modifier le Smart Element. Calcul de la somme des Smart Fields my_numberone et my_numbertwo et enregistrement dans le Smart Field my_sum.

namespace My;
use SmartStructure\Fields\MyFamily as MyAttributes;

class MyFamily extends Anakeen\SmartElement
{
  /**
   * Mise à jour de l'attribut `my_sum`
   */
  protected function setMyRawSum()
  {
    $n1 = intval($this->getRawValue(MyAttributes::my_numberone));
    $n2 = intval($this->getRawValue(MyAttributes::my_numbertwo));
    return $this->setValue(MyAttributes::my_sum, $n1 + $n2);
  }
  /**
   * Le rédacteur est l'utilisateur courant
   */
  protected function setMyRedactor()
  {
    return $this->setValue(MyAttributes::my_redactorn, getCurrentUser()->fid);
  }
    public function registerHooks()
    {
        parent::registerHooks();
        $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
            $err = parent::postStore();
            if (empty($err)) {
              $err = $this->setMyRawSum();
              $err .= $this->setMyRedactor();
            }
            return $err;
        });
}

# setAttributeValue

    void setAttributeValue( string $attributeIdentifier,
                            mixed $value)

La méthode setAttributeValue modifie la valeur d'un Smart Field de l'objet SmartElement. La modification n'est pas enregistrée en base de données.

Avertissements

Pour enregistrer la modification, il est nécessaire d'appeler la méthode SmartElement::store().
Les résultats fournis par la méthode SmartElement::getRawValue() ne peuvent pas être utilisés directement par cette méthode.
Les espaces et certains caractères invisibles en début et fin de valeur sont supprimés. La fonction trim est utilisée pour réaliser cette suppression.

# Liste des paramètres

attributeIdentifier (string)

Identifiant du Smart Field à modifier.

value (mixed)

Nouvelle valeur typée. Le type de la valeur est fonction du type du Smart Field.
Il est possible d'affecter aussi les Smart Fields de type array avec un tableau à 2 dimensions. La première dimension est l'index de la rangée, la deuxième dimension est l'identifiant du Smart Field.

# Erreur / Exception

Retourne une une exception de type Anakeen\Exception dans les cas suivants:

  • le Smart Field n'existe pas,
  • le type de Smart Field ne peut recevoir de valeur (frame,tab,menu).
  • la valeur est incompatible avec le type de Smart Field,
  • une valeur scalaire est donnée pour un Smart Field multiple.

# Exemple

Calcul de la somme des Smart Fields my_numberone et my_numbertwo et enregistrement dans le Smart Field my_sum.
Mise à jour du Smart Field my_mail avec l'adresse courriel du rédacteur.
Soit la Smart Structure suivante :

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MyStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 30 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 30 R
ATTR MY_MAIL MY_IDENTIFICATION Adresse courriel N N text 10 R
END
# Mise à jour de Smart Field après modification du Smart Element
namespace My;
use SmartStructure\Fields\MyStructure as MyAttributes;
use SmartStructure\Fields\Iuser as AIuser;
use Anakeen\SmartElementManager;

class MyStructure extends Anakeen\SmartElement
{
    /**
    * Mise  jour du SmartField `my_sum`
    */
    protected function setMySum()
    {
        $n1 = $this->getAttributeValue(MyAttributes::my_numberone);
        $n2 = $this->getAttributeValue(MyAttributes::my_numbertwo);
        $this->setAttributeValue(MyAttributes::my_sum, ($n1 + $n2);
    }
    /**
    * Mise à jour du SmartField `my_mail` avec l'adresse de courriel du rédacteur
    */
    protected function setMyMail()
    {
        $redacId = $this->getAttributeValue(MyAttributes::my_redactor);
        if ($redacId === null) {
            $this->clearValue(MyAttributes::my_mail);
        } else {
            $redacDoc = SmartElementManager::createDocument($redacId);
            $redacDoc->store();
            if ($redacDoc->isAlive()) {
                $this->setAttributeValue(MyAttributes::my_mail, $redacDoc->getAttributeValue(AIuser::us_mail));
            } else {
                $this->clearValue(MyAttributes::my_mail);
            }
        }
    }
    public function registerHooks()
    {
        parent::registerHooks();
        $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
            $err = parent::postStore();
            if (empty($err)) {
                $this->setMySum();
                $this->setMyMail();
            }
            return $err;
        });
    }
}
# Avec traitement des exceptions

Calcul de la prochaine échéance dans 7 jours après la dernière modification.

namespace My;
use SmartStructure\Fields\MyStructure as MyAttributes;
use SmartStructure\Fields\Iuser as AIuser;
use Anakeen\SmartElementManager;

class MyStructure extends Anakeen\SmartElement
{
    /**
    * prochaine échéance dans 7 jours
    */
    protected function setNextDate()
    {
        $d = new \DateTime('now');
        $d->modify('+7 day');
        $this->setAttributeValue(MyAttributes::my_nextdate, $d);
    }
    public function registerHooks()
    {
        parent::registerHooks();
        $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
            $err = parent::postStore();
            if (empty($err)) {
                try {
                    $this->setNextDate();
                } catch (\Anakeen\Core\SmartStructure\SmartFieldValueException $e) {
                    $err = sprintf("Valeur erronée %s", $e->getDcpMessage());
                } catch (\Anakeen\Core\SmartStructure\SmartFieldValueException $e) {
                    $err = sprintf("Erreur de Smart Field %s", $e->getDcpMessage());
                }
            }
            return $err;
        });
    }
# Affectation de tableau

Soit les Smart Structures suivantes:

BEGIN Ma Smart Structure MYSTRUCTURE
CLASS My\MyStructure
DFLDID auto
ICON classe.png
// idattr idframe label T A type ord vis
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 50 W
ATTR MY_MAIL MY_IDENTIFICATION Mail N N text 60 R
ATTR MY_REF MY_IDENTIFICATION Référence N N text 70 W
ATTR MY_T_PARTNER MY_IDENTIFICATION participants N N array 80 W
ATTR MY_COAUTHORS MY_T_PARTNER co-auteurs N N account 90 W
ATTR MY_COMAIL MY_T_PARTNER Adresse mail N N text 11 W
END
BEGIN Contact MYCONTACT
// idattr idframe label T A type ord vis need link ... phpfunc ... option
ATTR MY_FR_IDENT état civil N N frame W
ATTR MY_NAME MY_FR_IDENT nom Y N text 30 W Y
ATTR MY_FNAME MY_FR_IDENT prénom Y N text 35 W Y
ATTR MY_MAIL MY_FR_IDENT mail N Y text 40 W mailto:%MY_MAIL%
ATTR MY_ISPARTNER MY_FR_IDENT Partenaire? N Y enum 45 W no Pas partenaire, yes Partenaire
END

La méthode setMyPartners va rechercher tous les contacts partenaire et va les insérer dans le tableau my_t_partner en renseignant l'identifiant et l'adresse mail de chaque partenaire.

namespace My;
use SmartStructure\Fields\MyStructure as MyAttributes;
use SmartStructure\Fields\MyContact as AMyContact;

class MyStructure extends Anakeen\SmartElement
{
  protected function setMyPartners()
  {
    // Recherche des partenaires
    $s = new \SearchElements(AMyContact::my_name);

    $s->addFilter("%s = 'yes'", AMyContact::my_ispartner);
    $dl = $s->search()->getResults();

    // On affecte le tableau à 2 dimensions de valeurs
    $partners = array();
    foreach ($dl as $contact) {
      $partners[] = array(
        MyAttributes::my_coauthors => $contact->id,
        MyAttributes::my_comail => $contact->getAttributeValue(AMyContact::my_mail)
      );
    }
    $this->setAttributeValue(MyAttributes::my_t_partner, $partners);
  }

  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
      $this->setMyPartners();
    });
  }
}

# store

    string store( StoreInfo &$info = null, bool $skipConstraint = false )

Cette méthode permet la modification ou la création de Smart Element. Si le Smart Element n'a pas d'identifiant (id), une création de Smart Element est effectuée, sinon le Smart Element est mis à jour.

Avertissements

Le Smart Element n'est pas enregistré en base de donnée que si un changement a été détecté.
Si un Smart Field est affecté à sa valeur initiale, aucun changement n'est détecté et le Smart Element ne sera pas enregistré.
La détection de changement est réalisée par la méthode SmartElement::setValue, ainsi que les méthodes de plus hauts niveaux telles que SmartElement::setAttributeValue() ou SmartElement::addArrayRow().
Si les valeurs de Smart Fields sont directement modifiées dans l'objet, la méthode SmartElement::store() ne réalise pas l'enregistrement.

# Liste des paramètres

info (StoreInfo)

Si info est fourni, il contiendra les différents messages fournis par les hooks, ainsi que le code d'erreur.

skipConstraint (bool)

Si la valeur est à false, alors les contraintes sur le Smart Element ne sont pas testées.

# Valeur de retour

La valeur de retour contient le message d'erreur.
Si l'enregistrement s'est bien passé le retour est une chaîne de caractères vide. Dans le cas contraire, le texte de l'erreur est retourné.
Des informations plus détaillées sont disponibles dans le paramètre $info.

# Erreur / Exception

Si l'enregistrement en base de donnée n'a pas pu être réalisée, alors la méthode retourne un message d'erreur.
Le code de retour du paramètre $info est indiqué dans le Smart Field errorCode. Les différents codes d'erreur de $info->errorCode sont:

  • StoreInfo::NO_ERROR

    Pas d'erreur.

  • StoreInfo::CREATE_ERROR

    Erreur lors de la création. Peut provenir du hook SmartElement::preCreated(), d'un problème de droits ou d'un problème d'accès à la base de données.

  • StoreInfo::UPDATE_ERROR

    Erreur lors de la mise à jour. Peut provenir d'un problème de droits ou d'un problème d'accès à la base de données.

  • StoreInfo::CONSTRAINT_ERROR

    Une des contraintes n'a pas été validée.

  • StoreInfo::PRESTORE_ERROR

    Erreur déclenchée par le hook SmartElement::preStore().

Une exception Anakeen\Database\Exception peut être levée en cas de problème d'enregistrement au niveau de la base de données (problème d'accès, problème d'unicité d'index, problème d'incohérence de type).

# Exemple

Soit la structure MY_STRUCTURE suivante:

BEGIN Ma structure MYSTRUCTURE
CLASS My\MyStructure
// idattr idframe label T A type ord vis
ATTR MY_IDENTIFICATION identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
END
# Modification d'un Smart Element

Enregistrement d'une modification sans contrôle d'erreur.

use SmartStructure\Fields\MyStructure as MyAttributes;
use Anakeen\SmartElementManager;

$d = SmartElementManager::createDocument('MY_DOCUMENT');
$d->setValue(MyAttributes::my_numberone, 234);
$d->store($info);
# Création d'un Smart Element

Enregistrement d'un nouveau Smart Element sans contrôle d'erreur

use SmartStructure\Fields\MyStructure as MyAttributes;
use Anakeen\SmartElementManager;

$d = SmartElementManager::createDocument("MY_STRUCTURE");
$d->store();
$d->setValue(MyAttributes::my_numberone, 234);
$d->setValue(MyAttributes::my_numbertwo, 873);
$d->store($info);
printf("Nouvel identifiant: %d\n", $d->id);
# Contrôle des erreurs d'enregistrement

Les codes d'erreurs de $info permettent de préciser l'origine du problème.

use SmartStructure\Fields\MyStructure as MyAttributes;
use Anakeen\SmartElementManager;

$d = SmartElementManager::createDocument("MY_DOCUMENT");
$d->store();
$err = $d->setValue(MyAttributes::my_numberone, 234);

if (empty($err)) {
    $err = $d->store($info);
    if (!empty($err)) {
        switch ($info->errorCode) {
            case StoreInfo::NO_ERROR:
                // pas d'erreurs
                break;
            case StoreInfo::CONSTRAINT_ERROR:
                printf("Erreur de contrainte :\n");
                foreach ($info->constraint as $constraintInfo)[
                    printf("Coontrainte sur le SmartField %s non respectée: %s\n",
                        $constraintInfo["id"],
                        $constraintInfo["err"]);
                }
                break;
            default:
                printf("Erreur d'enregistrement: %s", $err);
        }
    }
}

Notes

Lors d'un ajout de Smart Element, les hooks suivants sont lancés:

Lors d'une mise à jour de Smart Elements les hooks suivants sont lancés:

# undelete

    string undelete()

Cette méthode permet d'annuler la suppression d'un Smart Element.

Avertissements

Cette méthode ne permet pas de restaurer un Smart Element qui a été supprimé physiquement.

# Valeur de retour

Message d'erreur. Si la chaîne retournée est non nulle, le message indique l'erreur qui a interdit la restauration.

# Erreur / Exception

Une erreur est retournée si:

  • le Smart Element n'existe pas ou plus (physiquement supprimé),
  • le Smart Element n'est pas supprimé,
  • l'utilisateur n'a pas le droit delete sur le Smart Element,
  • le hook preUndelete() retourne une erreur.

# Exemple

Restauration du Smart Element référencé par l'identificateur $documentId.

use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument($documentId);
$doc->store();
if ($doc->isAffected() && !$doc->isAlive()) {
  $err = $doc->undelete();
  // maintenant le Smart Element est vivant.
  if ($err === "") {
    printf("Restauration %s [%d]", $doc->getTitle(), $doc->id);
  }
}

# Hooks de la classe SmartElement

Ce chapitre décrit les méthodes hooks de la classe SmartElement qui sont utilisées dans les différentes méthodes de modification de Smart Element.
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é.

# preCreated

const PRECREATED = "preCreated";

Ce hook est utilisé par la méthode SmartElement::Add(), et appelé avant que le Smart Element soit créé en base. Il permet de vérifier si les conditions de création / révision de Smart Element sont valides. Ce hook est utilisable aussi pour préremplir des Smart Fields avant l'enregistrement.

Attention

Ce hook est aussi appelé lors de la révision d'un Smart Element.

Avertissements

Ce hook est appelé lors de la création initiale et lors des révisions du Smart Element. Toutefois, il est possible de différencier la création de la révision car:

  • lors d'une création les propriétés id et initid sont égales à chaîne vide,
  • lors d'une révision la propriété initid est valuée et id est égale à chaîne vide.

On peut donc reconnaître le cas de la révision de celui de la création initiale en faisant:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PRECREATED, function () {
      error_log('initid ' . var_export($this->initid, true));
      error_log('id ' . var_export($this->id, true));
      if ($this->initid === "") {
        error_log("I'm in first creation");
      } else {
        error_log("I'm in creation of a revision");
      }
    });
  }
}

Ce qui donne l'historique suivants, si l'on créée un Smart Element et que l'on révise celui-ci juste après:

  • lors de la création :
initid ''
id ''
I'm in first creation
  • lors de la révision:
initid '1453'
id ''
I'm in creation of a revision

# Valeur de retour

Si la méthode retourne une chaîne de caractères non-vide, elle considérée comme un message d'erreur et la création de Smart Element est abandonnée.

# Exemple

Dans la Smart Structure MySmartStructure, la création d'un Smart Element ne doit être possible que si la somme des Smart Fields MY_NUMBERONE et MY_NUMBERTWO est inférieur au paramètre MY_MAX de la Smart Structure.
Soit la Smart Structure suivante :

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
PARAM MY_PARAMETERS Paramètres N N frame 10 W
PARAM MY_MAX MY_PARAMETERS max N N int 20 W
END
<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PRECREATED, function () {
      $err = parent::preCreated();
      $n1 = $this->getAttributeValue(MyAttributes::my_numberone);
      $n2 = $this->getAttributeValue(MyAttributes::my_numbertwo);
      $max = $this->getFamilyParameterValue(MyAttributes::my_max);
      if ($n1 + $n2 > $max) {
        $err .= ($err ? "\n" : "") . sprintf("Max %d is reached", $max);
      }
      return $err;
    });
  }
}

Notes

En cas de Smart Structure héritée, il est nécessaire d'appeler le hook du parent pour disposer des mêmes fonctionnalités.
Ce hook est appelé par SmartElement::store() qu'en cas de création ou de révision tandis que le hook SmartElement::preStore() est appelé systématiquement par la méthode SmartElement::store().

# postCreated

const POSTCREATED = "postCreated";

Ce hook est appelé après l'enregistrement en base de données; il est aussi utilisable pour réaliser un post-traitement après une création de Smart Element.
Il ne peut pas annuler l'enregistrement.
Le Smart Element possède un identificateur et est déjà enregistré en base.
Ce hook est aussi appelé par SmartElement::revise() lorsque le Smart Element est révisé. Une révision entraîne une création en base de données.

# Valeur de retour

La valeur de retour est un message d'information. Ce message est enregistré dans l'historique du Smart Element.

# Exemple

Dans la Smart Structure MySmartStructure, une référence unique est enregistrée lors de la création du Smart Element.
Soit la Smart Structure suivante :

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
PARAM MY_REF MY_IDENTIFICATION Référence N N frame 10 R
END
<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTCREATED, function () {
      $msg = '';
      if ($this->revision == 0) {
        // création initiale
        $err = $this->setValue(MyAttributes::my_ref, uniqid('my'));
        if ($err) {
          $msg = sprintf("Pas d'identifiant");
        } else {
          $mst = sprintf("Création identifiant %s", $this->getRawValue(MyAttributes::my_ref));
        }
      }
      return $msg;
    });
  }
}

Notes

En cas de Smart Structure héritée, il est nécessaire d'appeler le hook du parent pour disposer des mêmes fonctionnalités.
Ce hook est appelé par SmartElement::store() qu'en cas de création ou de révision tandis que le hook SmartElement::postStore() est appelé systématiquement par la méthode SmartElement::store().

# preDelete

const PREDELETE = "preDelete";

Ce hook est utilisé par la méthode SmartElement::delete(), et est appelé avant la suppression du Smart Element.
IL permet d'ajouter des conditions spécifiques avant la suppression du Smart Element.

Avertissements

Ce hook est appelé après les contrôles de profils pour suppression du Smart Element.

# Valeur de retour

Ce hook renvoie un message d'erreur; si la méthode retourne une chaîne de caractères non-vide, elle est considérée comme un message d'erreur et la suppression est abandonnée.

# Exemple

Cet exemple, interdit la suppression si le Smart Field sp_protectionlevel vaut "top secret".

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREDELETE, function () {
      if ($this->getAttributeValue(MyAttributes::sp_protectionlevel) === "top secret") {
        return "Protected Smart Element"; // blocage de la suppression
      }
      return '';
    });
  }
}

Notes

Même le compte "admin" ne peut pas outrepasser les conditions de suppression de cette méthode.

# postDelete

const POSTDELETE = "postDelete";

Ce hook est utilisé par la méthode SmartElement::delete(), et est appelé après la suppression du Smart Element.
Il permet de réaliser un post-traitement après suppression du Smart Element.

Avertissements

Le Smart Element est déjà supprimé lors de l'appel. Dans le cas d'une suppression physique, il n'est plus en base de données.

# Valeur de retour

Ce hook renvoie un message d'information; il est enregistré dans l'historique du Smart Element.

# Exemple

Cet exemple supprime un Smart Element lié:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTDELETE, function () {
      $linkedId = $this->getAttributeValue(MyAttributes::sp_linkeddoc);
      if ($linkedId !== "") {
        $linked = \Anakeen\Core\SEManager::getDocument($linkedId);
        if ($linked->isAlive()) {
          return $linked->delete();
        }
      }
      return '';
    });
  }
}

# preDuplicate

const PREDUPLICATE = "preDuplicate";

Ce hook est utilisé par la méthode SmartElement::duplicate(), et est appelée avant la duplication du Smart Element.
Il permet d'ajouter des conditions spécifiques avant la duplication du Smart Element.

Avertissements

Ce hook est appelé sur le Smart Element en cours de duplication. Son identificateur est vide; il n'est pas encore enregistré en base de données.
Le Smart Element contient les valeurs des Smart Fields du Smart Element d'origine.

# Liste des paramètres

origin (SmartElement)

Smart Element d'origine de la duplication

# Valeur de retour

Ce hook renvoie un message d'erreur; si la méthode retourne une chaîne de caractères non-vide, elle est considérée comme un message d'erreur et la duplication est abandonnée.
Ce message est retourné par la méthode SmartElement::duplicate() si elle est non vide.

# Exemple

Cet exemple, interdit la duplication d'un Smart Element révisé:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREDUPLICATE, function (\Anakeen\SmartElement &$origin) {
      if ($origin->isFixed()) {
        return "Fixed Smart Element - not duplicated";
      }
      return '';
    });
  }
}

Notes

Même le compte "admin" ne peut pas outrepasser les conditions de duplication de cette méthode.
Le menu de duplication n'est pas accessible si cette méthode retourne un message d'erreur.

# postDuplicate

const POSTDUPLICATE = "postDuplicate";

Ce hook est utilisé par la méthode SmartElement::duplicate(), et est appelé après la duplication du Smart Element.
Il permet de réaliser un post-traitement après la duplication du Smart Element.

Avertissements

Ce hook est appelé sur le Smart Element en cours de duplication.
Le Smart Element vient d'être enregistré en base de données et contient un nouvel identificateur.

# Liste des paramètres

origin (SmartElement)

Smart Element d'origine de la duplication

# Valeur de retour

Ce hook renvoie un message d'information; ce dernier est enregistré dans l'historique du Smart Element.

# Exemple

Cet exemple, mémorise l'auteur de la duplication et ajoute une entrée dans l'historique du Smart Element originel:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTDUPLICATE, function (\Anakeen\SmartElement $se) {
      $se->addHistoryEntry("duplicated target %d", $this->initid);
      $this->setAttributeValue(MyAttributes::sp_duplicateby, $this->getUserId());
      $this->store();
      return '';
    });
  }
}

# preStore

const PRESTORE = "preStore";

Ce hook est utilisé par la méthode SmartElement::Store(), et est appelée avant l'enregistrement en base de données. Cette méthode doit vérifier si les conditions de modification de Smart Element sont valides.
Si cette méthode retourne un message d'erreur alors la modification est abandonnée et la méthode SmartElement::Store() retourne le message fourni par cette méthode afin d'indiquer l'échec.

Avertissements

Le Smart Element n'a pas encore d'identificateur lors d'une création.
Cette méthode n'est pas appelée lors d'une révision.

# Valeur de retour

Ce hook renvoie un message d'erreur; si la méthode retourne une chaîne de caractères non-vide, est est considérée comme un message d'erreur et la création de Smart Element est abandonnée.
Ce message est aussi stocké dans le paramètre de sortie $info->preStore de la méthode SmartElement::Store().

# Exemple

Dans la Smart Structure MySmartStructure, la modification d'un Smart Element ne doit être possible que si la somme des Smart Fields MY_NUMBERONE et MY_NUMBERTWO est inférieure au paramètre MY_MAX de la Smart Structure.
Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
PARAM MY_PARAMETERS Paramètres N N frame 10 W
PARAM MY_MAX MY_PARAMETERS max N N int 20 W
END
<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PRESTORE, function () {
      $err = '';
      $n1 = $this->getAttributeValue(MyAttributes::my_numberone);
      $n2 = $this->getAttributeValue(MyAttributes::my_numbertwo);
      $max = $this->getFamilyParameterValue(MyAttributes::my_max);
      if ($n1 + $n2 > $max) {
        $err = sprintf("Max %d is reached", $max);
      }
      return $err;
    });
  }
}

Notes

En cas de Smart Structure héritée, il est nécessaire d'appeler le hook du parent pour disposer des mêmes fonctionnalités.
Ce hook est appelé par SmartElement::store en cas de création, de révision, et de modification tandis que le hook SmartHooks::PRECREATED est appelé qu'en cas de création ou de révision.

# postStore

const POSTSTORE = "postStore";

Ce hook est utilisé par la méthode SmartElement::Store(), et est appelée après l'enregistrement en base de données.
Cette méthode est aussi utilisable pour réaliser un post-traitement après une modification.
Elle ne peut pas annuler l'enregistrement.
Le Smart Element possède un identificateur et est déjà enregistré en base.

Avertissements

Il ne faut pas appeler la méthode SmartElement::Store() dans cette méthode au risque d'avoir une boucle de récursion infinie.
Si des modifications de Smart Fields sont réalisées dans cette méthode, elles sont enregistrée en base par la méthode SmartElement::Store().

# Valeur de retour

La valeur de retour est un message d'information. Il est stocké dans le paramètre de sortie $info->postStore de la méthode SmartElement::Store().

# Exemple

Calcul de la somme des Smart Fields MY_NUMBERONE et MY_NUMBERTWO et enregistrement dans le Smart Field MY_SUM.
Soit la famille suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
PARAM MY_SUM MY_IDENTIFICATION nombre 1 +2 N N int 20 R
END

avec la classe:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function mySum($x, $y)
  {
    return $x + $y;
  }

  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTSTORE, function () {
      $n1 = $this->getAttributeValue(MyAttributes::my_numberone);
      $n2 = $this->getAttributeValue(MyAttributes::my_numbertwo);
      return $this->setAttributeValue(MyAttributes::my_sum, $this->mySum($n1, $n2));
    });
  }
}

Notes

En cas de Smart Structure héritée, il est nécessaire d'appeler le hook du parent pour disposer des mêmes fonctionnalités.
Ce hook est appelé par SmartElement::store() en cas de création, de révision et de modification, tandis que le hook SmartHooks::POSTCREATED est appelé qu'en cas de création ou de révision.

# preRefresh

const PREREFRESH = "preRefresh";

Ce hook est utilisé par la méthode SmartElement::refresh(), et est appelée avant la mise à jours des Smart Fields calculés.

Avertissements

Les contrôles relatifs au droit de modification sont désactivés pendant l'appel de cette méthode. Ceci permet à la méthode SmartElement::setValue() de ne pas vérifier les droits de modification.

# Valeur de retour

Cette méthode doit retourner une chaîne de caractères. Ce message est retourné par la méthode SmartElement::refresh().

# Exemple

Récupération de l'adresse mail du rédacteur et mise à jour. Si l'adresse est différente, un message est retourné.
Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis ... phpfunc
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_REDACTOR MY_IDENTIFICATION rédacteur N N account 30 W ::mySum(MY_NUMBERONE,MY_NUMBERTWO)
ATTR MY_MAIL MY_IDENTIFICATION Adresse courriel N N text 10 R
END

avec la classe:

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use SmartStructure\Fields\Iuser as Aiuser;
use Anakeen\SmartHooks;

class MySmartStructure extends Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREREFRESH, function () {
      $msg = '';
      $redactorId = $this->getRawValue(MyAttributes::my_redactor);
      if ($redactorId) {
        $du = \Anakeen\Core\SEManager::createDocument($redactorId);
        if ($du->isAlive()) {
          $redactorMail = $du->getRawValue(Aiuser::us_mail);
          if ($redactorMail !== $this->getRawValue(MyAttributes::my_mail)) {
            $err = $this->setValue(MyAttributes::my_mail, $du->getRawValue(Aiuser::us_mail));
            if (empty($err)) {
              $msg = sprintf("L'adresse du rédacteur a été changée. \n Nouvelle adresse : %s", $redactorMail);
            } else {
              $msg = sprintf("Erreur d'affectation : %s", $err);
            }
          }
        }
      } else {
        $this->clearValue(MyAttributes::my_mail);
      }
      return $msg;
    });
  }
}

# postRefresh

const POSTREFRESH = "postRefresh";

Ce hook est utilisé par la méthode SmartElement::refresh(), et est appelée après la mise à jour des Smart Fields calculés.

Avertissements

Les contrôles relatifs au droit de modification sont désactivés pendant l'appel de cette méthode. Ceci permet à la méthode SmartElement::setValue() de ne pas vérifier les droits de modification.

# Valeur de retour

Cette méthode doit retourner un message. Ce message est retourné par la méthode SmartElement::refresh().

# Exemple

Affichage d'un message si le Smart Field calculé my_sum est supérieur au paramètre my_max. Dans ce cas le Smart Field my_sum est mis à jour juste avant l'appel du hook SmartHooks::POSTREFRESH.
Soit la Smart Structure suivante:

BEGIN Ma Smart Structure MYSMARTSTRUCTURE
CLASS My\MySmartStructure
// idattr idframe label T A type ord vis phpfunc
ATTR MY_IDENTIFICATION Identification N N frame 10 W
ATTR MY_NUMBERONE MY_IDENTIFICATION nombre 1 Y N int 20 W
ATTR MY_NUMBERTWO MY_IDENTIFICATION nombre 2 N N int 30 W
ATTR MY_SUM MY_IDENTIFICATION nombre 1+2 N N int 30 R ::mySum(MY_NUMBERONE,MY_NUMBERTWO)
PARAM MY_PARAMETERS Paramètres N N frame 10 W
PARAM MY_MAX MY_PARAMETERS max N N int 20 W
END

avec la classe :

<?php
namespace My;
use SmartStructure\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function mySum($x, $y)
  {
    return $x + $y;
  }
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTREFRESH, function () {
      $msg = '';
      $sum = $this->getAttributeValue(MyAttributes::my_sum);
      $max = $this->getFamilyParameterValue(MyAttributes::my_max);
      if ($sum > $max) {
        $msg = sprintf("Max %d is reached", $max);
      }
      return $msg;
    });
  }
}

# preAffect

const PREAFFECT = "preAffect";

Cette méthode permet de contrôler l'affectation des données avant leur affectation dans l'objet. Au moment de l'appel, l'objet SmartElement contient les valeurs affectées du précédent SmartElement.
Cette méthode ne peut pas empêcher l'affectation mais peut modifier les données affectées.

Avertissements

Ce hook est appelé pour toute affectation d'objet SmartElement. Elle est appelée principalement par les fonctions de récupération de Smart Element et de recherche, mais aussi par les méthodes de révision et de changement d'état.
Cette méthode étant bas-niveau, les tests et traitement définis dans cette fonction peuvent pénaliser les temps de traitement.
Lors d'une recherche, Ce hook est appelé pour chacun des Smart Element trouvés si l'option de retour précise le retour d'objet. Dans le cas de retour brut, cette méthode n'est pas appelée car il n'y a pas de création d'objet.

# Liste des paramètres

data (array)

Contient les valeurs qui seront affectées à l'objet. Le tableau est indexé par les noms des Smart Fields et propriétés du Smart Element.
Ces valeur peuvent être modifiées. Le tableau "data" sert ensuite lors de l'affectation.
Les valeurs indexées values" et attrids contiennet aussi l'ensemble des Smart Field sous une forme sérialisée.

more (bool)

Indique que si les données fournies par le paramètre data sont incomplètes, alors les données manquantes sont récupérées depuis l'index values (s'il existe) fourni dans ce même paramètre data.
Il est possible de modifier ce paramètre afin de forcer ou inhiber ce fonctionnement. Note: Dans le cas d'une recherche, ce paramètre est mis à true.

reset (bool)

Indique que toutes les données de la précédente affectation seront effacées. Cela concerne les propriétés et les Smart Fields mais aussi les variables privées.
Il est possible de modifier ce paramètre afin de forcer ou inhiber le reset.
Note: Dans le cas d'une recherche, ce paramètre est mis à true.

# Exemple

Forcer l'affectation d'un Smart Field suivant une certaine condition. Si aucun message d'avertissement (my_warning) n'est indiqué et le niveau (my_order) est supérieur à 10, alors on indique un message par défaut.

<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREAFFECT, function (array &$data, &$more, &$reset) {
      if (!$data[MyAttributes::my_warning]) {
        if ($data[MyAttributes::my_order] > 20) {
          $data[MyAttributes::my_warning] = "Emergency level priority";
        } elseif ($data[MyAttributes::my_order] > 10) {
          $data[MyAttributes::my_warning] = "High level priority";
        }
      }
    });
  }
}

# postAffect

const POSTAFFECT = "postAffect";

Ce hook permet de réaliser un traitement sur le Smart Element après affectation. Au moment de l'appel, le Smart Element est initialisé avec les données fournies par l'argument data.

# Liste des paramètres

data (array)

Contient les valeurs qui ont été affectées à l'objet. Le tableau est indexé par les noms des Smart Fields et propriétés du Smart Element.
Les valeurs indexées values et attrids contiennet aussi l'ensemble des Smart Fields sous une forme sérialisée.

more (bool)

Indique que si les données fournies par le paramètre data étaient incomplètes, alors les données manquantes ont été récupérées depuis l'index values (s'il existe) fourni dans ce même paramètre data. Note: Dans le cas d'une recherche, ce paramètre est mis à true.

reset (bool)

Indique que toutes les données de la précédente affectation ont été effacées. Cela concerne les propriétés et les Smart Fields mais aussi les variables privées.
Note: Dans le cas d'une recherche, ce paramètre est mis à true.

# Exemple

Réinitialisation d'une variable privée en cas de réaffectation.

<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  const MYINIT = 4;
  private $myPrivate = self::MYINIT;

  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTAFFECT, function (array $data, $more, $reset) {
      if ($reset) {
        $this->myPrivate = self::MYINIT;
      }
    });
  }
}

NOTES

Cette méthode n'est pas appelée si aucune donnée n'est fournie dans le tableau data.

# preImport

const PREIMPORT = "preImport";

Ce hook est utilisé par la méthode ImportSingleDocument::import(), et est appelée avant l'enregistrement en basae de données d'un Smart Element lors d'une importation.
Cette méthode n'est pas utilisée pour les importations de Smart Structures de Smart Element.
Elle permet d'ajouter une condition spécifique d'importation ou de réaliser un prétraitement avant l'enregistrement.
Au moment de l'appel, le Smart Element contient les nouvelles valeurs indiquées dans le fichier d'importation, mais elles ne sont pas encore enregistrées en base de données.

Avertissements

Ce hook est appelé qu'il s'agisse d'une création ou d'une mise à jour. Dans le cas d'une création, le Smart Element n'a pas encore d'identificateur.
La méthode SmartElement::store() ne doit pas être appelée depuis cette méthode de manière explicite pour enregistrer les éventuelles modifications. Dans le cas d'une création, cela provoquerait une création prématurée en base de données.

# Liste des paramètres

extra (array)

Contient les valeurs supplémentaires indiquées dans le fichier d'importation. Ces paramètres supplémentaires peuvent servir à réaliser le prétraitement.

# Valeur de retour

Message d'erreur. Si la méthode retourne une chaîne de caractères non-vide, elle est considérée comme un message d'erreur et l'importation du Smart Element est abandonnée.

# Exemple

Soit la ligne d'importation suivante:

ORDER ZOO_SPECIES spec id folder id sp_latinname extra:status extra:special
DOC ZOO_SPECIES MY_MAMMUTH - Mammuthus disappeared protected

Dans cet exemple, le Smart Element "Mammuthus"de la Smart Structure "ZOO_SPECIES" aura comme paramètre passé à preImport:

array(
  'status' => 'disappeared',
  'special' => 'protected'
);
<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREIMPORT, function (array $extra = array()) {
      //ajout d'une condition d'importation
      if ($this->getRawValue(MyAttributes::sp_latinname) == '') {
        return _("Latin name must not be empty");
      }

      // modification de Smart Field en fonction des extra
      if (isset($extra["status"]) && $extra["status"] === "alive") {
        $this->clearValue(MyAttributes::sp_deathdate);
      }
      if (isset($extra["special"]) && $extra["special"] === "protected") {
        $this->setAttributeValue(MyAttributes::sp_protectionlevel, "2");
      }
      return '';
    });
  }
}

Notes

Dans le cas d'une modification de Smart Element, la méthode SmartElement::getOldRawValue() peut être utilisée pour avoir la valeur originelle d'un Smart Field.

# postImport

const POSTIMPORT = "postImport";

Ce hook utilisé par la méthode importSingleDocument::import(), et est appelée après l'enregistrement en base de données d'un Smart Element lors d'une importation.
Cette méthode n'est pas utilisée pour les importations de Smart Structures de Smart Element.
Elle permet de réaliser un post-traitement après l'enregistrement.

Avertissements

Ce hook est appelé qu'il s'agisse d'une création ou d'une mis à jour.
La méthode SmartElement::store() doit être appelée depuis cette méthode si des Smart Fields ont été modifiés par cette méthode.

# Liste des paramètres

extra (array)

Contient les valeurs supplémentaires indiquées dans le fichier d'importation. Ces paramètres supplémentaires peuvent servir à réaliser le post-traitement.

# Valeur de retour

Message d'erreur. Ce message est indiqué dans le rapport d'importation.

# Exemple

Soit la ligne d'importation suivante:

ORDER ZOO_SPECIES spec id folder id sp_latinname extra:status extra:special
DOC ZOO_SPECIES MY_MAMMUTH - Mammuthus disappeared protected

Dans cet exemple, le Smart Element "Mammuthus"de la Smart Structure "ZOO_SPECIES" aura comme paramètre passé à postImport:

array(
  'status' => 'disappeared',
  'special' => 'protected'
);
<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTIMPORT, function (array $extra = array()) {
      if (isset($extra["special"]) && $extra["special"] === "protected") {
        $this->setAttributeValue(MyAttributes::sp_protectionlevel, "2");
        return $this->store(); // L'enregistrement en base doit être effectué pour prendre en compte la modification
      }
      return '';
    });
  }
}

Notes

Il est possible d'utiliser des Smart Fields de classes (privées ou publiques) pour partager des informations entre SmartHook::PREIMPORT et SmartHooks::POSTIMPORT.

# preUndelete

const PREUNDELETE = "preUndelete";

Ce hook est utilisé par la méthode SmartElement::undelete(), et est utilisé avant la restauration d'un Smart Element.

Avertissements

Ce hook est appelé après les contrôles de profils pour suppression du Smart Element.
Le Smart Element est encore en statut supprimé (locked=-1 et doctype=Z).

# Valeur de retour

Message d'erreur. Si la méthode retourne une chaîne de caractères non-vide, elle est considérée comme un message d'erreur et la restauration est abandonnée.
Ce message est retourné par la méthode SmartElement::undelete() si elle est non-vide.

# Exemple

Cet exemple interdit la suppression si le Smart Field sp_protectionlevel vaut "archived".

<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::PREUNDELETE, function () {
      if ($this->getAttributeValue(MyAttributes::sp_protectionlevel) === "archived") {
        return "Archive Smart Element"; // blocage de la restauration
      }
      return '';
    });
  }
}

Notes

Même le compte "admin" ne peut pas outrepasser les conditions de restauration de cette méthode.
Le menu de restauration n'est pas accessible si cette méthode retourne un message d'erreur.

# postUndelete

const POSTUNDELETE = "postUndelete";

Ce hook est utilisé par la méthode SmartElement::undelete, et est appelé après la restauration d'un Smart Element.
Elle permet de réaliser un post-traitement après restauration du Smart Element.

Avertissements

Le Smart Element est de nouveau vivant.

# Valeur de retour

Message d'information. Ce message est affiché à l'utilisateur lorsqu'il réalise une restauration depuis l'interface web. Ce message est aussi enregistré dans l'historique du Smart Element.

# Exemple

Cet exemple mémorise l'auteur de la restauration si le Smart Field sp_protectionlevel vaut "low".

<?php
namespace My;
use SmartStructures\Fields\MySmartStructure as MyAttributes;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTUNDELETE, function () {
      if ($this->getAttributeValue(MyAttributes::sp_protectionlevel) === "low") {
        $this->setAttributeValue(MyAttributes::sp_restoreby, \Anakeen\Core\ContextManager::getCurrentUser()->fid);
        $this->store();
        return "Low restauration";
      }
      return '';
    });
  }
}

# postStructureImport

const POSTSTRUCTUREIMPORT = "postStructureImport";

Ce hook est utilisé lorsque la définition d'une Smart Structure est importé que ce soit pour une création ou une mise à jour. Elle permet de réaliser un post-traitement lié à la mise à jour d'une smart structure.

WARNING

Avertissement L'objet "this" est un objet SmartElement de la structure mais sans identifiant.

# Liste des paramètres

smartStructure (SmartStructure)

La Smart Structure qui a été mise à jour

# Valeur de retour

Aucun.

# Exemple

Cet exemple ajoute un index sur la table de base de données associées à la SmartStructure.

<?php
namespace My;
use SmartStructure\Fields\Devbill as DevbillFields;
use Anakeen\Core\SmartStructure;
use Anakeen\SmartHooks;

class MySmartStructure extends \Anakeen\SmartElement
{
  public function registerHooks()
  {
    parent::registerHooks();
    $this->getHooks()->addListener(SmartHooks::POSTSTRUCTUREIMPORT, function (SmartStructure $structure) {
      $index = new \Anakeen\Database\SmartIndex($structure);
      $index->setUnique(false);
      $index->setColumns([DevbillFields::bill_cost]);
      if (!$index->exists()) {
        $index->create();
        $structure->addHistoryEntry($index);
      }
    });
  }
}

# Gestion des minuteurs de Smart Elements

Les minuteurs permettent de déclencher des actions différées sur les Smart Elements. Le paramétrage d'un cycle de vie permet de les attacher et de les détacher automatiquement lors des passages de transitions.
Ce chapitre présente les méthodes permettant de gérer les minuteurs de manière explicite sans forcément avoir recours à un cycle de vie.

# attachTimer

    string attachTimer( TimerHooks &$timer,
                        SmartElement $origin = null,
                        string $execdate = null)

Cette méthode permet d'attacher un minuteur particulier sur le Smart Element.

Avertissements

Le même minuteur ne peut pas être attaché plusieurs fois sur le même Smart Element.
Si le paramètre execdate est non vide, la caractéristique dynamique tm_dyndate d'un minuteur est ignorée.
Le minuteur ne peut pas êtr eposé sur une révision précise du Smart Element. Les minuteurs sont attachés sur la dernière révision du Smart Element.

# Liste des paramètres

timer (TimerHooks)

SmartElement Minuteur qui doit être attaché au Smart Element.

origin (SmartElement)

Smart Element ayant initié l'attachement. Ce paramètre optionnel permet d'identifier un attachement. Il est utilisé par la méthode SmartElement::unattachAlltimer().

execdate (string)

Date au format YYYY-MM-DD HH:MM ou YYYY-MM-DD. Cette date sert de date de référence si elle est non vide.
Si cette date est vide, la date de référence est calculée en fonction de la date de référence indiquée sur le minuteur (Smart Field tm_dyndate). Si la date référence du minuteur est aussi vide, alors la ate de référence est la date d'attachement.

# Valeur de retour

La valeur de retour est le message d'erreur. Un retour vide indique que l'opération s'est bien déroulée.

# Erreur / Exception

Les cas de retours d'erreurs sont:

  • ce minuteur est déjà attaché,
  • le Smart Element "minuteur" n'est pas un minuteur,
  • le minuteur n'a déclaré aucune action.

# Exemple

Soit le minuteur, qui décrit qu'il faut exécuter la méthode "myMethod" après une journée avec un décalage de 3 heures, suivant:

Attribut Label Valeur
tm_delay Délai en jours 1
tm_hdelay Délai en heure 0
tm_dyndate Date de référence null
tm_refdaydelta Décalage en jours 0
tm_refhourdelta Décalage en heure 3
tm_iteration Nombre d'itération 1
tm_tmail Courrier à envoyer [null]
tm_method Méthode à exécuter [::myMethod()]
# Attacher un minuteur maintenant
use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument(1427);
$doc->store();
$timer = SmartElementManager::createDocument(13509);
$timer->store();
$err = $doc->attachTimer($timer);

if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultat
*/
Array
(
    [0] => Array
        (
            [timerid] => 13509
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] =>    2014-10-15 16:21:00
            [referencedate] => 2014-10-15 19:21:00
            [tododate] =>      2014-10-16 19:21:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 16
        )
)

La date d'exécution est positionné à la date de l'attachement plus une journée et 3 heures (tm_delay + tm_rehoufdelta).

# Attacher un minuteur avec une date donnée
use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument(1427);
$doc->store();
$timer = SmartElementManager::createDocument(13509);
$timer->store();
$err = $doc->attachTimer($timer, null, "2014-12-25 12:00");

if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultat
*/
Array
(
    [0] => Array
        (
            [timerid] => 13509
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] =>    2014-10-15 16:18:00
            [referencedate] => 2014-12-25 15:00:00
            [tododate] =>      2014-12-26 15:00:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 14
        )
)

La date d'exécution est positionnée à la date de référence plus une journée et 3 heures (tm_delay + tm_refhourdelta).

Notes

Une entrée, de niveau notice, est enregistrée dans l'historique pour indiquer le lien du minuteur.

# getAttachedTimer

    array getAttachedTimer()

Cette méthode renvoie les informations des minuteurs qui sont attachés au Smart Element.

# Valeur de retour

Le retour est un tableau de valeur indexé. Si le tableau est vide, alors aucun minuteur n'est attaché au Smart Element.

Clef Description Exemple
timerid Identifiant du document Timer 13510
level Nombre de fois qu'une action a été exécutée depuis l'attachement. Dépend du nombre d'itération et du nombre d'actions 0
originid Identifiant du document Origine
docid Identifiant initial (initid) du document portant le minuteur 1427
title Titre du document portant le minuteur Éléonore
fromid Identifiant de la famille du document portant le minuteur 1059
attachdate Date d'attachement du minuteur 2014-10-15 17:24:00
referencedate Date de référence du minuteur 2012-10-01 05:00:00
tododate Date de prochaine échéance 2012-10-01 05:00:00
donedate Date à laquelle l'action a été exécutée
actions Actions à faire (chaîne serialisée) a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
result Résultat de l'action
id Identifiant de l'attachement 22

Seuls les liens actifs sont retournés. Les actions effectuées ne sont pas retournées.

# Exemple

Deux minuteurs sont liés au Smart Element n°1427. Le premier minuteur n°13509 est lié à l'origine n°1090. Le deuxième minuteur n'est pas lié.

use Anakeen\SmartElementManager;

$origin = SmartElementManager::createDocument(1090);
$origin->store();
$doc = SmartElementManager::createDocument(1427);
$doc->store();
$firstTimer = SmartElementManager::createDocument(13509);
$firstTimer->store();
$secTimer = SmartElementManager::createDocument(13510);
$secTimer->store();

$err = $doc->attachTimer($firstTimer, $origin);
$err = $doc->attachTimer($secTimer);
print "Links:\n";
if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultats
*/
Links
Array
(
    [0] => Array
        (
            [timerid] => 13509
            [level] => 0
            [originid] => 1090
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:19:00
            [referencedate] => 2014-10-16 13:19:00
            [tododate] => 2014-10-17 13:19:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 31
        )
    [1] => Array
        (
            [timerid] => 13510
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:19:00
            [referencedate] => 2012-10-01 05:00:00
            [tododate] => 2012-10-01 05:00:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 32
        )
)

# unattachTimer

    string unattachTimer(TimerHooks $timer)

Cette méthode permet de détacher un minuteur précis du Smart Element.

# Liste des paramètres

timer (TimerHooks)

Smart Element minuteur qui doit être détaché du Smart Element.

# Valeur de retour

La valeur de retour est le message d'erreur. Un retour vide indique que l'opération s'est bien déroulée.
Si le minuteur n'est pas présent, aucun message d'erreur n'est retourné.

# Erreur / Exception

Les cas de retours d'erreurs sont:

  • le Smart Element "minuteur" n'est pas un minuteur,
  • erreur d'accès interne à la base de donnée.

# Exemple

use Anakeen\SmartElementManager;

$doc = SmartElementManager::createDocument(1427);
$doc->store();
$timer = SmartElementManager::createDocument(13510);
$timer->store();
print "Before\n";
print_r($doc->getAttachedTimers());
$err = $doc->unattachTimer($timer);

print "After\n";
if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultats
*/
Before:
    Array
    (
        [0] => Array
            (
                [timerid] => 13510
                [level] => 0
                [originid] =>
                [docid] => 1427
                [title] => Éléonore
                [fromid] => 1059
                [attachdate] => 2014-10-15 17:24:00
                [referencedate] => 2012-10-01 05:00:00
                [tododate] => 2012-10-01 05:00:00
                [donedate] =>
                [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
                [result] =>
                [id] => 22
            )
    )
/*
* Le minuteur n'est plus enregistré
*/
After:
    Array
    (
    )

Notes

Une entrée, de niveau notice, est enregistrée dans l'historique pour indiquer détachement du minuteur.

# unattachAllTimers

    string unattachAllTimers( SmartElement $origin = null)

Cette méthode permet de supprimer tout ou un sous-ensemble de minuteurs associés au Smart Element.
Si l'origine est vide, tous les minuteurs sont détachés.
Si l'origine est indiquée, seuls les minuteurs issus de cette origine sont détachés.

# Liste des paramètres

origin (SmartElement)

Filtre permettant de détacher un sous-ensemble. L'origine est donné par l'argument origine de la méthode SmartElement::attachTimer().

# Valeur de retour

La valeur de retour est le message d'erreur. Un retour vide indique que l'opération s'est bien déroulée.

# Erreur / Exception

Les cas de retours d'erreurs sont:

  • erreur d'accès interne à la base de donnée.

# Exemple

# Détacher tous les minuteurs
use Anakeen\SmartElementManager;

$origin = SmartElementManager::createDocument(1090);
$origin->store();
$doc = SmartElementManager::createDocument(1427);
$doc->store();
$firstTimer = SmartElementManager::createDocument(13509);
$firstTimer->store();
$secTimer = SmartElementManager::createDocument(13510);
$secTimer->store();

$err = $doc->attachTimer($firstTimer, $origin);
$err .= $doc->attachTimer($secTimer);

print "Active timers: \n";
print_r($doc->getAttachedTimers());

$err .= $doc->unattachAllTimers();

print "After origin deletion : \n";
if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultats
*/
Active timers:
Array
(
    [0] => Array
        (
            [timerid] => 13509
            [level] => 0
            [originid] => 1090
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:12:00
            [referencedate] => 2014-10-16 13:12:00
            [tododate] => 2014-10-17 13:12:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 25
        )
    [1] => Array
        (
            [timerid] => 13510
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:12:00
            [referencedate] => 2012-10-01 05:00:00
            [tododate] => 2012-10-01 05:00:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 26
        )
)
/*
* After origin deletion :
*/
Array
(
)
# Détacher en fonction de l'origine
use Anakeen\SmartElementManager;

$origin = SmartElementManager::createDocument(1090);
$origin->store();
$doc = SmartElementManager::createDocument(1427);
$doc->store();
$firstTimer = SmartElementManager::createDocument(13509);
$firstTimer->store();
$secTimer = SmartElementManager::createDocument(13510);
$secTimer->store();

$err = $doc->attachTimer($firstTimer, $origin);
$err .= $doc->attachTimer($secTimer);

print "Active timers: \n";
print_r($doc->getAttachedTimers());

$err .= $doc->unattachAllTimers($origin);

print "After origin deletion : \n";
if (empty($err)) {
  print_r($doc->getAttachedTimers());
} else {
  print "$err\n";
}
/*
* Résultats
*/
Active timers:
Array
(
    [0] => Array
        (
            [timerid] => 13509
            [level] => 0
            [originid] => 1090
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:12:00
            [referencedate] => 2014-10-16 13:12:00
            [tododate] => 2014-10-17 13:12:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 25
        )
    [1] => Array
        (
            [timerid] => 13510
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:12:00
            [referencedate] => 2012-10-01 05:00:00
            [tododate] => 2012-10-01 05:00:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 26
        )
)
/*
* After origin deletion :
*/
Array
(
    [0] => Array
        (
            [timerid] => 13510
            [level] => 0
            [originid] =>
            [docid] => 1427
            [title] => Éléonore
            [fromid] => 1059
            [attachdate] => 2014-10-16 10:12:00
            [referencedate] => 2012-10-01 05:00:00
            [tododate] => 2012-10-01 05:00:00
            [donedate] =>
            [actions] => a:3:{s:5:"state";s:0:"";s:5:"tmail";s:0:"";s:6:"method";s:12:"::myMethod()";}
            [result] =>
            [id] => 26
        )
)

Notes

Une entrée, de niveau notice, est enregistrée dans l'historique pour indiquer le détachement des minuteurs.