# 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:
- SmartElement::preRefresh(),
- Calcul des Smart Fields calculés,
- SmartElement::postRefresh(),
- Enregistrement en base si modification détectée.
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:
- SmartElement::preRevise(),
- Fige le Smart Element et enregistrement en base,
- SmartElement::preCreated(),
- Copie du Smart Element et création du nouvel identifiant,
- SmartElement::postCreated(),
- SmartElement::postRevise().
# 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 | 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 | 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:
- SmartElement::preStore(),
- SmartElement::preCreated(),
- Enregistrement en base,
- SmartElement::postCreated(),
- SmartElement::preRefresh(),
- SmartElement::postRefresh(),
- Enregistrement en base si modification détectée depuis dernier enregistrement,
- SmartElement::postStore(),
- Enregistrement en base si modification détectée depuis dernier enregistrement,
Lors d'une mise à jour de Smart Elements les hooks suivants sont lancés:
- SmartElement::preStore(),
- SmartElement::preRefresh(),
- SmartElement::postRefresh(),
- Enregistrement en base,
- SmartElement::postStore(),
- Enregistrement en base si modification détectée depuis dernier enregistrement
# 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.
Avertissements
# 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.