La fonction ~list est une fonction de liste. Elle permet d'effectuer une extraction sur une base de données. Les sélecteurs supportés sont LM, LR, LF, LL, LN, LS, L1, LD et LE.

La fonction ~list prend comme arguments le nom indiqué dans templeet/config.php pour la base de donnée, la requête SQL à exécuter, puis les sélecteurs.

La fonction ~fld prend un argument, celui ci étant le nom de la colonne SQL que l'on souhaite récupérer. Il est possible d'indiquer un second argument (facultatif) permettant d'accéder aux colonnes dans des requêtes SQL imbriqués.

Si le second argument est négatif, la colonne accédée sera celle de la requête correspondant à un déplacement relatif par rapport à la requête en cours, ainsi ~fld('id',-1) accèdera à la colonne 'id' de la requête parente. Si le second argument est positif, la requête concerné sera celle dont la position absolue est indiqué par l'argument, ainsi ~fld('id',1) correspond à la colonne 'id' de la toute première requête effectué avec ~list.

Exemples d'utilisation des commandes ~list, et ~fld :

L'exemple suivant affiche le champ section de chaque enregistrement de la table sections :

~list("database",'SELECT section FROM sections',"LM",~fld("section"))

L'exemple suivant met en oeuvre les paramètres "LF", "LM", "LL" de la fonction ~list :

~list("database",'
SELECT 
    nom, prenom
FROM
    utilisateurs
ORDER BY
    nom, prenom
',
"LF",
    '<table border="1">
        <thead>
            <tr>
                <th>Nom</th>
                <th>Prénom</th>
            </tr>
        </thead>
        <tbody>
    ',
"LM",
    '
            <tr>
                <td>~fld("nom")</td>
                <td>~fld("prenom")</td>
            </tr>
    ',
"LL",
    '
        </tbody>
    </table>
    '
)

Exemple de résultat du code précédent :

Nom
Prénom 
 DUPOND 
 Pierre
 MARTIN
 Catherine  
 DUMONT  
 Sébastien 

NOTE : il est possible d'imbriquer la fonction ~list dans une autre fonction ~list. Cependant, dans la fonction ~list qui est contenue, il n'est pas possible d'accéder aux champs de la fonction ~list contenante s'il le second argument de ~fld n'est pas renseigné.

Exemple :

~list("database",               // <--- fonction ~list (1)
'
SELECT 
    section 
FROM 
    sections
',
"LM",
'
    ~list("database",            // <--- fonction ~list (2)
'
SELECT 
    nom,
    prenom
FROM
    utilisateurs
WHERE
    section="~fld("section")"     // <--- accès au champ section de la requête effectué par la fonction ~list (1)
',
"LF",'
    <table>
'
"LM",'
    <tr>
        <td>~fld("nom")</td>       // <--- accès au champ nom de la requête effectué par la fonction ~list (2)
        <td>~fld("prenom")</td>    // <--- accès au champ prenom de la requête effectué par la fonction ~list (2)
        <td>~fld("section")</td>   // <--- accès au champ prenom de la requête effectué par la fonction ~list (2)
    </tr>
'
    )
',
"LL",'
    </table>
'
)

Cette fonction permet de récupérer la valeur de variables internes Templeet.

• ~gfld("numrows") : permet d'avoir le nombre de lignes renvoyées par la requête.
• ~gfld("counter") : permet d'avoir le numéro de ligne courante (la première ligne a pour valeur 1).
• ~gfld("error") : permet d'avoir le message d'erreur.
• ~gfld("executedtime") : permet de récupérer le temps passé à exécuter la requête.

Exemple d'utilisation de la fonction ~gfld :

~list("database",'
SELECT 
    nom, prenom
FROM
    utilisateurs
ORDER BY
    nom, prenom
',
"LF",
    '<p>Nombre d\'enregistrement : ~gfld("numrows")</p>
    
    <table border="1">
        <thead>
            <tr>
                <th></th>
                <th>Nom</th>
                <th>Prénom</th>
            </tr>
        </thead>
        <tbody>
    ',
"LM",
    '
            <tr>
                <td>~gfld("counter")</td>
                <td>~fld("nom")</td>
                <td>~fld("prenom")</td>
            </tr>
    ',
"LL",
    '
        </tbody>
    </table>
    '
)

Exemple de résultat du code précédent :

Nombre d'enregistrement : 3
 
Nom
Prénom
1
 DUPOND
 Pierre
2
 MARTIN
 Catherine 
3
 DUMONT  
 Sébastien  
  

DUPOND

Cette fonction permet de retourner le résultat d'une requête sous forme de tableau.

Elle prend deux paramètres:

• la base de données
  
• la requête

Exemple:

tableau=dbfetcharray("database","
SELECT 
    nom, prenom
FROM
    utilisateurs
ORDER BY
    nom, prenom");

La fonction ~list_lastid renvoie l'identifiant généré par la dernière requête INSERT. Cet identifiant correspond à un champ qui est automatiquement incrémenté.

~list("foo", 'INSERT INTO table (field) VALUES ("bar")')
Index du dernier enregistrement inséré : ~list_lastid("foo")

La fonction list_querycolumns permet de récupérer une description simple d'une table d'une base de données.

Elle retourne un tableau qui représente chacun des champs de la table sous forme normalisée. En effet, en fonction de la base de données utilisée la déclaration des champs varie. Cette fonction permet de faire des vérifications simples sur les types des champs se trouvant dans une table. Pour chaque champs de la table, et donc chaque élément du tableau retourné, on a le nom du champs associé à la clef name et le type normalisé associé à la clef type.

Actuellement trois types sont gérés par la fonction:

• serial: numéro de série unique
  
• varchar: chaîne de longueur fixe
• text: chaîne de longueur variable
• int: entier
• bool: booléen

Soit la table MySQL suivante:

CREATE TABLE  `personnes` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `nom` char(50) DEFAULT NULL,
  `prenom` char(50) DEFAULT NULL,
  `age` int(11) DEFAULT NULL,
  `commentaire` text,
  PRIMARY KEY (`id`)
);

et le template suivant:

~print_r(list_querycolumns('database','personnes'))

Le résultat est alors:

Array
(
    [0] => Array
        (
            [name] => id
            [type] => serial
            [size] => 10
        )

    [1] => Array
        (
            [name] => nom
            [type] => varchar
            [size] => 50
        )

    [2] => Array
        (
            [name] => prenom
            [type] => varchar
            [size] => 50
        )

    [3] => Array
        (
            [name] => age
            [type] => int
            [size] => 11
        )

    [4] => Array
        (
            [name] => commentaire
            [type] => text
            [size] => 
        )

)

Cette fonction permet de connaitre le temps total passé par le serveur de base de données à traiter la requête.

Cette fonction, ainsi que ~list_prev() et ~getfirst() permet de créer un chaînage entre des pages présentant chacune une partie de liste. ~list_next() permet de créer le lien avec la page suivante.

Elle prend cinq paramètres:

• le numéro du premier élément
• le nombre d'éléments par page
• le nombre d'éléments dans la liste
• le code HTML à insérer si il y a une page suivante
• le code HTML à insérer si il n'y a pas de page suivante

Voir exemple ci-dessous.

~list_prev() permet de créer le lien avec la page précédente.

Elle prend quatre paramètres:

• le numéro du premier élément
• le nombre d'éléments par page
• le code HTML à insérer si il y a une page précédente
• le code HTML à insérer si il n'y a pas de page précédente

Voir exemple ci-dessous.

~getfirst() permet dans le troisième paramètre des fonctions ~next() et ~prev() de connaitre le numéro du premier élément de la page suivante et précédente respectivement.

Elle ne prend pas de paramètre.

Exemple d'utilisation d'affichage d'une liste en plusieurs pages chaînées:

~rem(
  pays=array(
    "Allemagne",
    "Autriche",
    "Belgique",
    "Bulgarie",
    "Chypre",
    "Danemark",
    "Espagne",
    "Estonie",
    "Finlande",
    "France",
    "Grèce",
    "Hongrie",
    "Irlande",
    "Italie",
    "Lettonie",
    "Lituanie",
    "Luxembourg",
    "Malte",
    "Pays-bas",
    "Pologne",
    "Portugal",
    "République-Tchèque",
    "Roumanie",
    "Royaume-uni",
    "Slovaquie",
    "Slovénie",
    "Suède");

  first=get_filenamevar(1);
  if(first=="",first=0);
  pagesize=10;
)

~array_list(pays,first+1,pagesize,
    "LM",<![LM[<tr><td>~array_fld('key')</td><td>~array_fld('current')</td></tr>]LM]>,
    "LF","<table>",
    "LL","</table>"
)


<table>
<tr>
<td>~prev(first,pagesize,
    <![PREV[<a href="~relative_templeet()~get_dirname()~get_filenamevar(0),~getfirst(),.~get_extension()">
    &lt;=</a>
    ]PREV]>
    ,'pas de page précédente')</td>
<td>~next(first,pagesize,count(pays),
    <![NEXT[
    <a href="~relative_templeet()~get_dirname()~get_filenamevar(0),~getfirst(),.~get_extension()">
    =&gt;</a>
    ]NEXT]>,'pas de page suivante')</td>
</tr>
</table>

Cette fonction est obsolète. Elle est remplacée par list_next().

Cette fonction est obsolète. Elle est remplacée par list_prev().