17.11.6 Mise en forme d'une collection de documents

17.11.6.1 Collection de documents

Les collections de documents sont, comme évoqués dans le chapitre d'introduction, des ensembles de documents statiques (répertoires) ou dynamiques (recherches).

17.11.6.2 Classe de formatage

La classe FormatCollection facilite la mise en forme de ces ensembles de documents pour leur utilisations ultérieures (exportation ou interface homme- machine).

17.11.6.3 Liste des paramètres entrants

Le classe prend en entrée des objets DocumentList

Exemple pour le formatage des documents 9 et 12.

$documentList=new DocumentList();
$documentList->addDocumentIdentifiers(array(9,12)); // 
 
$formatCollection =new FormatCollection();
$formatCollection->useCollection($documentList);
$render=$formatCollection->render();

: les objets DocumentList peuvent être initialisés soit avec des id, soit avec des objets SearchDoc.

17.11.6.4 Sortie

Le résultat du "render" donne un tableau avec une entrée par document formaté. Par défaut seul le titre et l'identifiant (id) sont retournés, aucun attribut n'est utilisé. Chaque entrée contient un champ "properties" indiquant les propriétés et un champ "attributes" contenant les attributs. Ce dernier est vide si aucun attribut n'a été indiqué dans le formatage.

Array 
( 
    [0] => Array 
        ( 
            ["properties"] => Array 
                ( 
                    ["id"] => 12
                    ["title"] => "les profils" 
                ) 
        ) 
    [1] => Array 
        ( 
            ["properties"] => Array 
                ( 
                    ["id"] => 9 
                    ["title"] => "Racine" 
                ) 
        ) 
)

3.2.18 Les documents ayant des attributs en visibilité I ne sont pas exportés par défaut. La méthode ::setVerifyAttributeAccess(false) permet d'exporter sans tenir compte de la visibilité I.

17.11.6.5 Formatage des propriétés

Les propriétés accessibles sont les suivantes :

les propriétés brutes : ensemble des propriétés d'un document,

les propriétés formatées :

  • url : URL d'accès en visualisation du document,
  • family : informations sur la famille du document, cette structure contient le
    • titre de la famille (title),
    • le nom logique (name),
    • l'identifiant (numérique) (id),
    • l'adresse de téléchargement de l'icône (icon),
  • creationDate : date de création de la lignée documentaire,
  • createdBy : informations sur le créateur de la lignée documentaire, cette structure contient
    • le nom du créateur (title),
    • le nom logique du document lié au compte du créateur (name),
    • l'identifiant (numérique) (id),
    • l'adresse de téléchargement de l'icône (icon) du document représentant le créateur,
  • revisionData : informations sur la révision du document, cette structure contient :
    • un booléen indiquant si le document a été modifié (isModified) depuis sa dernière révision,
    • son identifiant (id),
    • son numéro de révision (number),
    • les informations sur le créateur de la révision (createdBy), cette structure est similaire à createdBy,
  • viewController : informations sur la vue en cours d'application, cette structure contient
    • l'identifiant du contrôle de vue (id),
    • son titre (title),
  • workflow : informations sur le cycle de vie associé au document, cette structure contient
    • l'identifiant (id),
    • le titre du cycle de vie (title),
  • tags : tag documentaire associés au document, cette structure est une liste de valeurs,
  • security : information liées aux droits du documents, cette structure contient
    • lock : verrou. La propriété contient :
      • id identifiant du verrou,
      • temporary : indique si le verrou est temporaire ou permanent,
      • lockedBy : identifiant du compte de l'utilisateur ayant verrouillé le document,
    • readOnly : un booléen indiquant si le document est en lecture seule ,
    • fixed :un booléen indiquant si le document est figé ,
    • profil : profil associé au document :
      • id : identifiant du profil,
      • icon : l'adresse de téléchargement de l'icône du profil ,
      • type : type : linked (lié) ou private (privé),
      • activated : un booléen indiquant si le profil est activé ,
      • title : titre du profil,
    • confidentiality : sa confidentialité,
  • status : information sur le statut du document, trois valeurs sont possibles
    • deleted : document supprimé,
    • fixed : document figé,
    • alive : document vivant,
  • note : liste des post-it associés au document,
  • type : type du document, les valeurs suivantes sont possibles :
    • document : document standard,
    • folder : dossier : collection statique de documents,
    • search : recherche : collection dynamique de documents,
    • family : famille : définition d'une famille de documents,
    • profil : profil : document de modèle de profil,
    • workflow : document de cycle de vie,
  • state : état du document, cette structure contient :
    • reference : clef de l'étape,
    • color : couleur de l'étape,
    • activity : activité de l'étape (vide si document est figé, - ancienne révision - ),
    • stateLabel : libellé de l'état de l'étape,
    • displayValue : libellé de l'étape. Il est égal à l'activité si le document est en dernière révision et si l'activité est déclarée sinon il est égal au libellé de l'état,
  • usage : Usage du document. Les valeurs suivantes sont possibles :
    • normal : usage normal,
    • system : document de configuration (exemple cycle de vie, profil).

Exemple :

$searchDoc=new SearchDoc('',"ZOO_TEST");
$searchDoc->setObjectReturn();
$documentList=$searchDoc->getDocumentList();
 
$formatCollection=new FormatCollection();
$formatCollection->useCollection($documentList);
$formatCollection->addProperty($formatCollection::propState);
$r=$formatCollection->render();
print_r($r);

Le résultat est :

["properties"] => Array 
            ( 
                ["id"] => 67978 
                ["title"] => "Nouga" 
                ["state"] => statePropertyValue Object 
                    ( 
                        ["reference"] => "zoo_transmited" 
                        ["color"] => "#A8DF78" 
                        ["activity"] => "Vérification de l'adoption" 
                        ["stateLabel"] => "Transmis" 
                        ["displayValue"] => "Vérification de l'adoption" 
                    ) 
            ) 
 

Un exemple de rendu de l'ensemble des propriétés sérialisé en JSON :

{
    "id": 1289,
    "title": "2013-05-07",
    "adate": "2014-12-16 16:51:42",
    "affected": {
        "id": 0,
        "title": ""
    },
    "allocated": null,
    "atags": null,
    "cdate": "2014-12-16 16:51:42",
    "confidential": null,
    "createdBy": {
        "id": 1008,
        "title": "Master Default",
        "icon": "resizeimg.php?img=Images%2Fdynacase-iuser.png&size=24"
    },
    "creationDate": "2014-12-16 16:51:42",
    "cvid": null,
    "doctype": "F",
    "dprofid": "0",
    "family": {
        "title": "Entrée",
        "name": "ZOO_ENTREE",
        "id": 1059,
        "icon": "resizeimg.php?img=Images%2Fentree.gif&size=24"
    },
    "fromid": "1059",
    "icon": "resizeimg.php?img=Images%2Fentree.gif&size=24",
    "initid": 1289,
    "lastAccessDate": "2014-12-16 16:51:42",
    "lastModificationDate": "2014-12-16 16:52:06",
    "lmodify": "Y",
    "locked": 0,
    "name": null,
    "note": {
        "id": 0,
        "title": ""
    },
    "owner": "1",
    "postitid": null,
    "prelid": null,
    "profid": "1084",
    "revdate": "2014-12-16 16:52:06",
    "revision": 0,
    "revisionData": {
        "isModified": true,
        "id": 1289,
        "number": 0,
        "createdBy": {
            "id": 1008,
            "title": "Master Default",
            "icon": "resizeimg.php?img=Images%2Fdynacase-iuser.png&size=24"
        }
    },
    "security": {
        "lock": {
            "id": 0
        },
        "readOnly": false,
        "fixed": false,
        "profil": {
            "id": 1084,
            "icon": "resizeimg.php?img=Images%2Fprofil.gif&size=24",
            "type": "linked",
            "activated": true,
            "title": "Caisse"
        },
        "confidentiality": "public"
    },
    "status": "alive",
    "tags": [],
    "type": "document",
    "usage": "normal",
    "usefor": "N",
    "version": null,
    "viewController": {
        "id": 0,
        "title": ""
    },
    "wid": null,
    "workflow": {
        "id": 0,
        "title": ""
    }
}

17.11.6.6 Formatage des attributs

Les valeurs des attributs se placent dans le tableau "attributes". Chacun des attributs a un champ "value" qui indique la valeur brute et "displayValue" qui indique la valeur affichable. Pour ajouter les attributs à formater, il faut utiliser la méthode "addAttribute".

$formatCollection=new FormatCollection();
$formatCollection->useCollection($documentList);
$formatCollection->addAttribute("tst_title")->addAttribute("tst_double");
$r=$formatCollection->render();

Extrait de la partie "attributes"

[attributes] => Array
            (
                ["tst_title"] => textAttributeValue Object
                    (
                        ["value"] => "Le tour du monde"
                        ["displayValue"] => "Le tour du monde"
                    )
                ["tst_double"] => doubleAttributeValue Object
                    (
                        ["value"] => 3.14
                        ["displayValue"] => "3,14"
                    )

: Si un attribut n'a pas de valeur, le formatage sera "null" quelque soit le type d'attribut.

Si un attribut n'existe pas la structure (value, displayValue) sera remplie avec la variable identifiée par la méthode "::setNc()".

$searchDoc=new SearchDoc('',"DIR");
$searchDoc->setObjectReturn();
$documentList=$searchDoc->search()->getDocumentList();
$formatCollection=new FormatCollection();
$formatCollection->useCollection($documentList);
$formatCollection->setNc("nc");
$formatCollection->addProperty($formatCollection::propState);
$formatCollection->addAttribute("tst_title")->addAttribute("ba_desc");
$r=$formatCollection->render();

Exemple avec un attribut "vide" (ba_desc) et un attribut inexistant.

[attributes] => Array 
                ( 
                    ["tst_title"] => unknowAttributeValue Object 
                        ( 
                            ["value"] => "nc" 
                            ["displayValue"] => "nc" 
                        ) 
                    ["ba_desc"] => null
                )

Si l'option "showempty" est indiquée dans l'attribut, le rendu d'une valeur nulle sera remplacée par la valeur de l'option.

17.11.6.7 Rendu des attributs

17.11.6.7.1 type text 

["tst_text"] => textAttributeValue Object
                (
                    ["value"] => "Testing"
                    ["displayValue"] => "before Testing"
                )

La valeur formatée tient compte du format mis dans le type dans cet exemple : text("before %s")

17.11.6.7.2 type int 

[tst_int] => intAttributeValue Object
                    (
                        ["value"] => 10
                        ["displayValue"] => "0010"
                    )
 

La valeur formatée tient compte du format mis dans le type. Dans cet exemple : int("%04d"). La valeur est de type "int".

17.11.6.7.3 type double 

[tst_double] => doubleAttributeValue Object
                    (
                        ["value"] => 0
                        ["displayValue"] => "0,00"
                    )

La valeur formatée tient compte du format mis dans le type. Dans cet exemple : double("%.02f"). Le point est transformé en virgule si la locale est "fr_FR". La valeur est de type "double".

17.11.6.7.4 type date 

[tst_date] => dateAttributeValue Object
                    (
                        ["value"] => "2012-06-08"
                        ["displayValue"] => "08/06/2012"
                    )

La valeur formatée tient compte du format mis dans le type. S'il n'y a pas de format, cela dépend du format de la locale de l'utilisateur.

17.11.6.7.5 type timestamp 

[tst_ts] => dateAttributeValue Object
                    (
                        ["value"] => "2012-06-13 11:27:00"
                        ["displayValue"] => "13/06/2012 11:27"
                    )

La valeur formatée tient compte du format mis dans le type. S'il n'y a pas de format, cela dépend du format de la locale de l'utilisateur.

17.11.6.7.6 type file 

["tst_file"] => fileAttributeValue Object
    (
        ["size"] => 572
        ["creationDate"] => "2014-10-14 11:44:20"
        ["fileName"] => "iuserplus.csv"
        ["url"] => "file/13502/807/fi_ofile/1/iuserplus.csv?cache=no&inline=yes"
        ["mime"] => "text/plain"
        ["icon"] => "resizeimg.php?img=CORE%2FImages%2Fmime-txt.png&size=14"
        ["value"] => "text/plain|807|iuserplus.csv"
        ["displayValue"] => "iuserplus.csv"
    )

La valeur formatée est le titre du fichier.

Éléments retournés :

  • size : taille en octets du fichier
  • creationDate : date d'enregistrement du fichier
  • fileName : nom du fichier
  • url : url de téléchargement du fichier
  • mime : type mime du fichier
  • icon : icône représentant le type de fichier
  • value : valeur brute (référence au fichier)
  • displayValue : nom du fichier

17.11.6.7.7 type image 

["tst_img"] => imageAttributeValue Object
(
    ["thumbnail"] => "file/13505/810/img_file/-1/tree.jpg?cache=no&inline=yes&width=48"
    ["size"] => 584894
    ["creationDate"] => "2014-10-14 13:59:30"
    ["fileName"] => "tree.jpg"
    ["url"] => "file/13505/810/img_file/-1/tree.jpg?cache=no&inline=yes"
    ["mime"] => "image/jpeg"
    ["icon"] => "resizeimg.php?img=CORE%2FImages%2Fmime-image.png&size=24"
    ["value"] => "image/jpeg|810|tree.jpg"
    ["displayValue"] => "tree.jpg"
 )

Éléments retournés :

  • thumbnail : url de téléchargement de la miniature de l'image
  • size : taille en octets de l'image
  • creationDate : date d'enregistrement de l'image
  • fileName : nom de l'image
  • url : url de téléchargement de l'image
  • mime : type mime de l'image
  • icon : icône représentant le type de l'image
  • value : valeur brute (référence à l'image)
  • displayValue : nom de l'image

Note : La largeur de la miniature peut être définie avec l'attribut imageThumbnailSize de la classe FormatCollection. Elle est de 48px par défaut.

17.11.6.7.8 type docid - account 

["tst_relation"] => docidAttributeValue Object
(
    ["familyRelation"] => "TST_FMTCOL"
    ["url"] => "?app=FDL&OPENDOC&mode=view&id=84412&latest=Y"
    ["icon"] => "resizeimg.php?img=Images/test.png&size=14"
    ["revision"] => -1
    ["initid"] => 84412
    ["value"] => "84412"
    ["displayValue"] => "Test 1"
)
  • familyRelation : indique le format du type de relation.
  • url : L'url permet d'accéder à la page de consultation du document.
  • icon : La taille de l'icône du document pointé est par défaut de 14px. Elle peut être modifiée avec l'attribut relationIconSize de la classe FormatCollection.
  • revision : 3.2.21 Contient le numéro de la révision si l'option "docrev=fixed".
    Contient "state:<état>" si l'option est "docrev=state(<état>)".
    Sinon contient -1 pour indiquer que c'est la dernière révision qui doit être utilisée.
  • initid : 3.2.21La propriété initid du document cible
  • value : La valeur brute indique l'identifiant numérique du document stocké. Il est généralement différent de l'initid en cas de lien vers une révision spécifique.
  • displayValue : La valeur formatée indique le titre du document pointé.

17.11.6.7.9 type enum 

["tst_enum"] => enumAttributeValue Object
(
    ["value"] => 1
    ["displayValue"] => "Un"
    ["exists"] => true
)

La valeur formatée donne le libellé de l'énuméré.

3.2.21 La propriété "exists" indique si la valeur fait partie du référenciel de l'énuméré. Cette propriété peut être false dans le cas de l'option etype=free : autorisation de pose d'un autre choix par l'utilisateur.

17.11.6.7.10 type htmltext

Si le flag stripHtmlTags (méthode stripHtmlTags) est à true les balises HTML sont supprimées dans la displayValue.

17.11.6.7.11 type longtext

3.2.18 Si l'attribut est dans un array les séparateurs de cellules sont des sauts de lignes \n). Vous pouvez les configurer à l'aide de la méthode setLongtextMultipleBrToCr.

17.11.6.7.12 Autres types

["x_attr"] => standardAttributeValue Object
(
    ["value"] => "12:20:00"
    ["displayValue"] => "12:20:00"
)

La valeur et la valeur formatée sont égales.

17.11.6.8 Rendu des attributs multiples

Les attributs multiples sont rendus dans des tableaux de structure. Exemple avec deux valeurs de l'attribut "tst_colors".

["tst_colors"] => Array
(
    [0] => standardAttributeValue Object
        (
            ["value"] => "#80CCFF"
            ["displayValue"] => "#80CCFF"
        )
    [1] => standardAttributeValue Object
        (
            ["value"] => "#FFD77A"
            ["displayValue"] => "#FFD77A"
        )
)

La même structure à deux niveaux est rendue pour les multiples dans les tableaux. Cela est limité à l'attribut docid.

[tst_relation_multiple] => Array
(
   [0] => Array
       (
           [0] => docidAttributeValue Object
               (
                   ["familyRelation"] => "TST_FMTCOL"
                   ["url"] => "?app=FDL&amp;action=OPENDOC..."
                   ["icon"] => 
                   ["initid"] => 84412
                   ["revision"] => -1
                   ["value"] => "84412"
                   ["displayValue"] => "Test 1"
               )
       )
   [1] => Array
       (
           [0] => docidAttributeValue Object
               (
                   ["familyRelation"] => "TST_FMTCOL"
                   ["url"] => ?"app=FDL&amp;action=OPENDOC..."
                   ["icon"] => 
                   ["initid"] => 84412
                   ["revision"] => -1
                   ["value"] => "84412"
                   ["displayValue"] => "Test 1"
               )
           [1] => docidAttributeValue Object
               (
                   ["familyRelation"] => "TST_FMTCOL"
                   ["url"] => "?app=FDL&amp;action=OPENDOC..."
                   ["icon"] => 
                   ["initid"] => 86854
                   ["revision"] => -1
                   ["value"] => "86854"
                   ["displayValue"] => "Test 2"
               )

17.11.6.9 Hook de rendu

3.2.18 Le rendu proposé par la classe n'est pas toujours le rendu attendu par un outil externe, il est possible de modifier celui-ci en utilisant les hook de rendu.

17.11.6.9.1 Hook de document

Il est possible d'inscrire un hook qui est appliqué après le rendu de chaque document pour modifier le tableau formaté produit.

Exemple, ajout d'une URI particulière :

$formatCollection->setDocumentRenderHook(function ($values, \Doc $document) {
    $values["uri"] = sprintf("http://api.example.net/%s", $document->getPropertyValue("initid");
    return $values;
});

Le hook s'ajoute à l'aide de la fonction setDocumentRenderHook celle-ci prend en entrée un callable et l'exécute à chaque rendu de document. La fonction reçoit en entrée :

  • values : le tableau de valeur calculé,
  • document : l'objet document en cours.

Elle doit retourner l'objet values modifié.

17.11.6.9.2 Hook d'attribut

Il est possible d'inscrire un hook qui est appliqué après le rendu de chaque attribut pour modifier le rendu d'attribut produit.

Exemple, uniformisation des valeurs vides :

$formatCollection->setAttributeRenderHook(function ($attributeValue, $attribute) {
     if ($attributeValue === null) {
         /**
          * @var \NormalAttribute $attribute
          */
         if ($attribute->isMultiple()) {
             $attributeValue = array();
         } else {
             $attributeValue = new \StandardAttributeValue($attribute, null);
         }
     }
     return $attributeValue;
 });

Le hook s'ajoute à l'aide de la fonction setAttributeRenderHook celle-ci prend en entrée un callable et l'exécute à chaque rendu d'attribut. La fonction reçoit en entrée :

  • attributeValue : la valeur de l'attribut calculé,
  • attribute : l'objet attribut en cours,
  • document : l'objet document en cours.

Elle doit retourner l'objet attributeValue modifié.

17.11.6.9.3 Hook de propriété

Il est possible d'inscrire un hook qui est appliqué après le rendu de chaque propriété pour modifier le rendu de la propriété.

Exemple, passage à false de la propriété state pour les documents n'ayant pas d'état :

$formatCollection->setPropertyRenderHook(function ($propertyValue, $propertyId) {
     if ($propertyId === "state" && !$propertyValue->reference) {
         $propertyValue = false;
     }
     return $propertyValue;
 });

Le hook s'ajoute à l'aide de la fonction setPropertyRenderHook celle-ci prend en entrée un callable et l'exécute à chaque rendu de propriété. La fonction reçoit en entrée :

  • propertyValue : la valeur de la propriété calculée,
  • propertyId : identifiant de la propriété en cours,
  • document : l'objet document en cours.

Elle doit retourner l'objet propertyValue modifié.

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