Manuel de référence

# Smart Structure

Une Smart Structure est un objet interne de la plateforme permettant de définir des structures de données.
Une fois la structure importée, la plateforme fournit automatiquement :

  • la persistance de donnée,
  • des formulaires web de saisie et de visualisation des données,
  • un système d'historique des modifications,
  • un système de gestion des droits de création, lecture, écriture, suppression,
  • etc.

Pour faire un parallèle avec la programmation objet, la Smart Structure est l'équivalent d'une classe.

# Configuration des propriétés d'une Smart Structure

# Initialisation d'une Smart Structure

La configuration initiale d'une smart structure est réalisée avec un fichier XML de configuration. Ce fichier XML doit utiliser le namespace https://platform.anakeen.com/4/schemas/smart/1.0.

Les propriétés à référencer en premier sont :

  • sa référence (nom logique)
  • sa structure mère s'il s'agit d'une structure héritée.

Cette configuration doit être définie dans un fichier XML dans la balise structure-configuration.

xml path Description
structure-configuration/@name (*) Nom logique - référence unique de la Smart Structure
structure-configuration/@id Identifiant système (réservé aux structures systèmes de la plateforme)
structure-configuration/@label Libellé de la Smart Structure

La configuration de l'héritage doit être importée en premier. Il n'est pas possible de modifier l'héritage par la suite.

# Configuration d'une structure sans héritage

Exemple : ./src/vendor/My/SmartStructures/MyFirstStructure/MyFirstStructureConfig.xml

<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MyFirstStructure" label="Ma première structure">
        <smart:fields>
            <smart:field-set name="my_fr_ident" type="frame" label="Identification" access="ReadWrite">
                <smart:field-text name="my_title" label="Titre" access="ReadWrite" is-title="true" needed="true"/>
            </smart:field-set>
        </smart:fields>
    </smart:structure-configuration>
</smart:config>

# Configuration d'une structure avec héritage

L'héritage de structure est déclaré avec la balise extends dans l'attribut ref. Une fois la balise extends interprétée par le serveur, il n'est plus possible de modifier l'héritage. Il n'est pas nécessaire de répéter cet héritage dans d'autres fichiers de configuration de cette même Smart Structure.

Exemple : ./src/vendor/My/SmartStructures/MySecondStructure/MySecondStructureConfig.xml

Ici la structure MySecondStructure hérite de la structure MyFirstStructure.




 
 








<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MySecondStructure" label="Ma deuxième structure">
        <!-- Référence le nom logique de la structure parente -->
        <smart:extends ref="MyFirstStructure"/>
        <smart:fields>
            <smart:field-set name="my_fr_ident" extended="true">
                <smart:field-text name="my_subtitle" label="Sous-Titre" access="ReadWrite" />
            </smart:field-set>
        </smart:fields>
    </smart:structure-configuration>
</smart:config>

# Importation d'une configuration de Smart Structure

# Mise à jour manuelle de la configuration d'une Smart Structure

Pour créer ou mettre à jour une configuration de Smart Structure, il faut téléverser le fichier de configuration sur le serveur et lancer la commande suivante sur le serveur.

    ./ank.php --script=importConfiguration --file="<config file.xml>"

# Mise à jour automatique

Cette mise à jour peut être enregistrée dans le fichier info.xml disponible à la racine du code source du module. La commande d'importation doit être placée dans la balise process sous la balise post-install (exécutée à la première installation du module) ou post-upgrade (exécutée à chaque mise à jour).

Exemple info.xml :

<?xml version="1.0" ?>
<module xmlns="https://platform.anakeen.com/4/schemas/app/1.0"
        name="mymodule" version="1.0.0">
    <description>My Module</description>
    <post-install>
        <process command="./ank.php --script=importConfiguration --file=vendor/My/SmartStructures/MyFirstStructure/MyFirstStructureConfig.xml"/>
    </post-install>
    <post-upgrade>
        <process command="./ank.php --script=importConfiguration --file=vendor/My/SmartStructures/MyFirstStructure/MyFirstStructureConfig.xml"/>
    </post-upgrade>
</module>

Dans ce cas, le fichier de configuration est réinterprété à chaque installation ou mise à jour du module.

# Icône de la Smart Structure

L'icône d'une Smart Structure est un fichier png. Il est recommandé que l'image soit carrée et de taille entre 64x64px et 256x256px.

Le fichier doit être placé sur le serveur dans le répertoire public/Images. Il est référencé dans l'attribut structure-configuration/icon/@file.

Exemple avec le fichier public/Images/myFirstStructure.png :




 
 



<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MyFirstStructure" >
        <!-- Chemin du fichier relatif à `public/Images/` -->
        <smart:icon file="myFirstStructure.png"/>
    </smart:structure-configuration>
</smart:config>

L'icône est prise en compte seulement si la structure ne possède pas encore d'icône. Pour changer une icône déjà enregistrée d'une structure, il faut mettre l'attribut structure-configuration/icon/@reset à true.

Méthodes et propriétés PHP pour gérer les icones :

  • Anakeen\SmartElement::getIcon()
  • Anakeen\SmartElement->icon

Remarque

Dans le cas où l'on souhaite mettre à jour l'icône d'une Smart Structure, lorsqu'une image est déposée dynamiquement dans le répertoire public/Images l'API ne renvoie pas cette image tant que le cache n'est pas nettoyé.

Pour nettoyer le cache, il faut appeler la fonction (new \Anakeen\Script\System())->clearFileCache().

# Révisabilité de la Smart Structure

# Non révisable

Pour indiquer que les Smart Elements de la Smart Structure ne sont jamais révisables, il faut indiquer false dans la balise structure-configuration/revisable.




 
 



<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MyFirstStructure" >
        <!-- Non révisable -->
        <smart:revisable>false</smart:tag>
    </smart:structure-configuration>
</smart:config>

Indiquer un nombre de révisions maximum. Lorsque ce maximum est atteint la plus ancienne révision est supprimée avant de créer la nouvelle.




 
 



<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MyFirstStructure" >
        <!-- Auto révisable -->
        <smart:revisable max="100">default</smart:tag>
    </smart:structure-configuration>
</smart:config>

Méthodes et propriétés PHP pour gérer les révisions :

  • Anakeen\SmartElement::addRevision()
  • Anakeen\SmartElement->revision

# Pose de tags sur la Smart Structure

Un tag est composé d'une référence et d'une éventuelle valeur.

La référence du tag est placée dans l'attribut structure-configuration/tag/@name. La valeur du tag est indiquée dans le contenu de la balise. Un tag vide a une valeur égale à true (booléen). Plusieurs tags peuvent être posés.




 
 
 



<?xml version="1.0" encoding="UTF-8"?>
<smart:config xmlns:smart="https://platform.anakeen.com/4/schemas/smart/1.0">
    <smart:structure-configuration name="MyFirstStructure" >
        <!-- Tags à poser` -->
        <smart:tag name="vendor">My Company</smart:tag>
        <smart:tag name="hello">World</smart:tag>
    </smart:structure-configuration>
</smart:config>

Méthodes PHP pour gérer les tags:

  • Anakeen\SmartElement::addATag()
  • Anakeen\SmartElement::getATag()
  • Anakeen\SmartElement::delATag()

← Smart Field →