Title: Référence des fonctions Brindille {{{.nav * [Modules](modules.html) * [Documentation Brindille](brindille.html) * **[Fonctions](brindille_functions.html)** * [Sections](brindille_sections.html) * [Filtres](brindille_modifiers.html) }}} <> # Fonctions généralistes ## assign Permet d'assigner une valeur dans une variable. | Paramètre | Optionnel / obligatoire ? | Fonction | | :- | :- | :- | | `.` | optionnel | Assigner toutes les variables du contexte (section) actuel | | `var` | optionnel | Nom de la variable à créer ou modifier | | `value` | optionnel | Valeur de la variable | | `from` | optionnel | Recopier la valeur depuis la variable ayant le nom fourni dans ce paramètre. | Tous les autres paramètres sont considérés comme des variables à assigner. Exemple : ``` {{:assign blabla="Coucou"}} {{$blabla}} ``` Il est possible d'assigner toutes les variables d'une section dans une variable en utilisant le paramètre point `.` (`.="nom_de_variable"`). Cela permet de capturer le contenu d'une section pour le réutiliser à un autre endroit. ``` {{#pages uri="Informations" limit=1}} {{:assign .="infos"}} {{/pages}} {{$infos.title}} ``` Il est aussi possible de remonter dans les sections parentes en utilisant plusieurs points. Ainsi deux points remonteront à la section parente, trois points à la section parente de la section parente, etc. ``` {{#foreach from=$infos item="info"}} {{#foreach from=$info item="sous_info"}} {{if $sous_info.titre == 'Coucou'}} {{:assign ..="info_importante"}} {{/if}} {{/foreach}} {{/foreach}} {{$info_importante.titre}} ``` En utilisant le paramètre spécial `var`, tous les autres paramètres passés sont ajoutés à la variable donnée en valeur : ``` {{:assign var="tableau" label="Coucou" name="Pif le chien"}} {{$tableau.label}} {{$tableau.name}} ``` De la même manière on peut écraser une variable avec le paramètre spécial `value`: ``` {{:assign var="tableau" value=$infos}} ``` Il est également possible de créer des tableaux avec la syntaxe `.` dans le nom de la variable : ``` {{:assign var="liste.comptes.530" label="Caisse"}} {{:assign var="liste.comptes.512" label="Banque"}} {{#foreach from=$liste.comptes}} {{$key}} = {{$value.label}} {{/foreach}} ``` Il est possible de rajouter des éléments à un tableau simplement en utilisant un point seul : ``` {{:assign var="liste.comptes." label="530 - Caisse"}} {{:assign var="liste.comptes." label="512 - Banque"}} ``` Enfin, il est possible de faire référence à une variable de manière dynamique en utilisant le paramètre spécial `from` : ``` {{:assign var="tableau" a="Coucou" b="Test !"}} {{:assign var="titre" from="tableau.%s"|args:"b"}} {{$titre}} -> Affichera "Test !", soit la valeur de {{$tableau.b}} ``` ## break Interrompt une section. ## continue Passe à l'itération suivante d'une section. Le code situé entre cette instruction et la fin de la section ne sera pas exécuté. ``` {{#foreach from=$list item="event"}} {{if $event.date == '2023-01-01'}} {{:continue}} {{/if}} {{$event.title}} {{/foreach}} ``` Il est possible de passer à l'itération suivante d'une section parente en utilisant un chiffre en paramètre : ``` {{#foreach from=$list item="event"}} {{$event.title}} {{#foreach from=$event.people item="person"}} {{if $person.name == 'bohwaz'}} {{:continue 2}} {{/if}} - {{$person.name}} {{/foreach}} {{/foreach}} ``` ## debug Cette fonction permet d'afficher le contenu d'une ou plusieurs variables : ``` {{:debug test=$title}} ``` Affichera : ``` array(1) { ["test"] => string(6) "coucou" } ``` Si aucun paramètre n'est spécifié, alors toutes les variables définies sont renvoyées. Utile pour découvrir quelles sont les variables accessibles dans une section par exemple. ## error Affiche un message d'erreur et arrête le traitement à cet endroit. | Paramètre | Optionnel / obligatoire ? | Fonction | | :- | :- | :- | | `message` | **obligatoire** | Message d'erreur à afficher | Exemple : ``` {{if $_POST.nombre != 42}} {{:error message="Le nombre indiqué n'est pas 42"}} {{/if}} ``` ## form_errors Affiche les erreurs du formulaire courant (au format HTML). ## http Permet de modifier les entêtes HTTP renvoyés par la page. Cette fonction doit être appelée au tout début du squelette, avant tout autre code ou ligne vide. | Paramètre | Optionnel / obligatoire ? | Fonction | | :- | :- | :- | | `code` | *optionnel* | Modifie le code HTTP renvoyé. [Liste des codes HTTP](https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP) | | `redirect` | *optionnel* | Rediriger vers l'adresse URL indiquée en valeur. | | `type` | *optionnel* | Modifie le type MIME renvoyé | | `download` | *optionnel* | Force la page à être téléchargée sous le nom indiqué. | | `inline` | *optionnel* | Force la page à être affichée, et peut ensuite être téléchargée sous le nom indiqué (utile pour la généraion de PDF : permet d'afficher le PDF dans le navigateur avant de le télécharger). | Note : si le type `application/pdf` est indiqué (ou juste `pdf`), la page sera convertie en PDF à la volée. Il est possible de forcer le téléchargement du fichier en utilisant le paramètre `download`. Exemples : ``` {{:http code=404}} {{:http redirect="/Nos-Activites/"}} {{:http redirect="https://mon-site-web.tld/"}} {{:http type="application/svg+xml"}} {{:http type="pdf" download="liste_membres_ca.pdf"}} ``` ## include Permet d'inclure un autre squelette. Paramètres : | Paramètre | Optionnel / obligatoire ? | Fonction | | :- | :- | :- | | `file` | **obligatoire** | Nom du squelette à inclure | | `keep` | *optionnel* | Liste de noms de variables à conserver | | `capture` | *optionnel* | Si renseigné, au lieu d'afficher le squelette, son contenu sera enregistré dans la variable de ce nom. | | … | *optionnel* | Tout autre paramètre sera utilisé comme variable qui n'existea qu'à l'intérieur du squelette inclus. | ``` {{* Affiche le contenu du squelette "navigation.html" dans le même répertoire que le squelette d'origine *}} {{:include file="./navigation.html"}} ``` Par défaut, les variables du squelette parent sont transmis au squelette inclus, mais les variables définies dans le squelette inclus ne sont pas transmises au squelette parent. Exemple : ``` {{* Squelette page.html *}} {{:assign title="Super titre !"}} {{:include file="./_head.html"}} {{$nav}} ``` ``` {{* Squelette _head.html *}}

{{$title}}

{{:assign nav="Accueil > %s"|args:$title}} ``` Dans ce cas, la dernière ligne du premier squelette (`{{$nav}}`) n'affichera rien, car la variable définie dans le second squelette n'en sortira pas. Pour indiquer qu'une variable doit être transmise au squelette parent, il faut utiliser le paramètre `keep`: ``` {{:include file="./_head.html" keep="nav"}} ``` On peut spécifier plusieurs noms de variables, séparés par des virgules, et utiliser la notation à points : ``` {{:include file="./_head.html" keep="nav,article.title,name"}} {{$nav}} {{$article.title}} {{$name}} ``` On peut aussi capturer le résultat d'un squelette dans une variable : ``` {{:include file="./_test.html" capture="test"}} {{:assign var="test" value=$test|replace:'TITRE':'Ceci est un titre'}} {{$test}} ``` Il est possible d'assigner de nouvelles variables au contexte du include en les déclarant comme paramètres tout comme on le ferait avec `{{:assign}}` : ``` {{:include file="./_head.html" title='%s documentation'|args:$doc.label visitor=$user}} ``` ## captcha Permet de générer une question qui doit être répondue correctement par l'utilisateur pour valider une action. Utile pour empêcher les robots spammeurs d'effectuer une action. L'utilisation simplifiée utilise un de ces deux paramètres : | Paramètre | Fonction | | :- | :- | | `html` | Si `true`, crée un élément de formulaire HTML et le texte demandant à l'utilisateur de répondre à la question | | `verify` | Si `true`, vérifie que l'utilisateur a correctement répondu à la question | L'utilisation avancée utilise d'abord ces deux paramètres : | Paramètre | Fonction | | :- | :- | | `assign_hash` | Nom de la variable où assigner le hash (à mettre dans un ``) | | `assign_number` | Nom de la variable où assigner le nombre de la question (à afficher à l'utilisateur) | Puis on vérifie : | Paramètre | Fonction | | :- | :- | | `verify_hash` | Valeur qui servira comme hash de vérification (valeur du ``) | | `verify_number` | Valeur qui représente la réponse de l'utilisateur | | `assign_error` | Si spécifié, le message d'erreur sera placé dans cette variable, sinon il sera affiché directement. | Exemple : ``` {{if $_POST.send}} {{:captcha verify_hash=$_POST.h verify_number=$_POST.n assign_error="error"}} {{if $error}}

Mauvaise réponse

{{else}} ... {{/if}} {{/if}}
{{:captcha assign_hash="hash" assign_number="number"}}

Merci de recopier le nombre suivant en chiffres : {{$number}}

``` ## mail Permet d'envoyer un e-mail à une ou des adresses indiquées (sous forme de tableau). Restrictions : * le message est toujours envoyé en format texte ; * l'expéditeur est toujours l'adresse de l'association ; * l'envoi est limité à une seule adresse e-mail externe (adresse qui n'est pas celle d'un membre) dans une page ; * l'envoi est limité à maximum 10 adresses e-mails internes (adresses de membres) dans une page ; * un message envoyé à une adresse e-mail externe ne peut pas contenir une adresse web (`https://...`) autre que celle de l'association. Note : il est également conseillé d'utiliser la fonction `captcha` pour empêcher l'envoi de spam. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `to` | **obligatoire** | Adresse email destinataire (seule l'adresse e-mail elle-même est acceptée, pas de nom) | | `subject` | **obligatoire** | Sujet du message | | `body` | **obligatoire** | Corps du message | | `block_urls` | *optionnel* | (`true` ou `false`) Permet de bloquer l'envoi si le message contient une adresse `https://…` | | `attach_file` | *optionnel* | Chemin vers un ou plusieurs documents à joindre au message (situé dans les documents) | | `attach_from` | *optionnel* | Chemin vers un ou plusieurs squelettes à joindre au message (par exemple pour joindre un document généré) | Pour le destinataire, il est possible de spécifier un tableau : ``` {{:assign var="recipients[]" value="membre1@framasoft.net"}} {{:assign var="recipients[]" value="membre2@chatons.org"}} {{:mail to=$recipients subject="Coucou" body="Contenu du message\nNouvelle ligne"}} ``` Exemple de formulaire de contact : ``` {{if !$_POST.email|check_email}}

L'adresse e-mail indiquée est invalide.

{{elseif $_POST.message|trim == ''}}

Le message est vide

{{elseif $_POST.send}} {{:captcha verify=true}} {{:mail to=$config.org_email subject="Formulaire de contact" body="%s a écrit :\n\n%s"|args:$_POST.email:$_POST.message block_urls=true}}

Votre message nous a bien été transmis !

{{/if}}
{{:captcha html=true}}

``` ## redirect Redirige vers une nouvelle page. Avec le paramètre `force`, si la page actuelle est ouverte dans une fenêtre modale (grâce à la cible `_dialog`), alors la fenêtre modale est fermée, et la redirection se passe dans la page parente. Avec le paramètre `to`, si la page actuelle est ouverte dans une fenêtre modal (grâce à la cible `_dialog`), alors la fenêtre modale est fermée, et la page parente est rechargée. Si la page n'est pas ouvertre dans dans une fenêtre modale, la redirection est effectuée. Seules les adresses internes sont acceptées, il n'est pas possible de rediriger vers une adresse extérieure. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `force` | optionnel | Adresse de redirection forcée | | `to` | optionnel | Adresse de redirection si pas dans une fenêtre modale | Si `to=null` est utilisé, alors la fenêtre modale sera fermée. Ou, si la page n'est pas dans une fenêtre modale, la page courante sera rechargée. ## api Permet d'appeler l'API de Paheko, que ça soit sur l'instance locale, en cours, ou une autre instance externe. Voir la [documentation de l'API](https://paheko.cloud/api) pour la liste des fonctions disponibles. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `method` | obligatoire | Méthode de requête : `GET`, `POST`, etc. | | `path` | obligatoire | Chemin de la méthode de l'API à appeler. | | `fail` | optionnel | Booléen. Si `true`, alors une erreur sera affichée si la requête échoue. Si `false`, aucune erreur ne sera affichée. Défaut : `true`. | | `assign` | optionnel | Capturer le résultat dans cette variable. | | `assign_code` | optionnel | Capturer le code de retour dans cette variable. | Par défaut, les requêtes sont réalisées sur la base de données locale, dans ce cas les paramètres suivants sont également disponibles : | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `access` | optionnel | Niveau d'autorisation de l'API (défaut : `admin`). | ``` {{:assign var="users." value=42}} {{:api method="POST" path="accounting/transaction" assign="result" id_year=1 type="revenue" date="01/01/2023" label="Don de Ada Lovelace" reference="DON-0001" payment_reference="Credit Mutuel 00042" amount="51,49" debit="756" credit="512A" linked_users=$users }} L'écriture n°{{$result.id}} a été créée. ``` Mais cette fonction permet également d'appeler une API Paheko distante, dans ce cas les paramètres suivants sont nécessaires : | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `url` | obligatoire | Adresse HTTP de l'instance Paheko distante. | | `user` | obligatoire | Identifiant d'accès à l'API distante. | | `password` | obligatoire | Mot de passe d'accès à l'API distante. | ``` {{:api method="POST" path="sql" sql="SELECT * FROM users;" url="https://mon-asso.paheko.cloud/" user="zmgyfr1qnm" password="OAqFTLFzujJWr6lLn1Mu7w" assign="result" assign_code="code" fail=false }} {{if $code == 200}} Il y a {{$result.count}} résultats. {{else}} La requête a échoué : code {{$code}} — {{$result.error}} {{/if}} ``` # Fonctions relatives aux Modules ## save Enregistre des données, sous la forme d'un document, dans la base de données, pour le module courant. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `key` | optionnel | Clé unique du document | | `id` | optionnel | Numéro unique du document | | `validate_schema` | optionnel | Fichier de schéma JSON à utiliser pour valider les données avant enregistrement | | `validate_only` | optionnel | Liste des paramètres à valider (par exemple pour ne faire qu'une mise à jour partielle), séparés par des virgules. | | `assign_new_id` | optionnel | Si renseigné, le nouveau numéro unique du document sera indiqué dans cette variable. | | … | optionnel | Autres paramètres : traités comme des valeurs à enregistrer dans le document | Si ni `key` ni `id` ne sont indiqués, un nouveau document sera créé avec un nouveau numéro (ID) unique. Si le document indiqué existe déjà, il sera mis à jour. Les valeurs nulles (`NULL`) seront effacées. ``` {{:save key="facture_43" nom="Atelier mobile" montant=250}} ``` Enregistrera dans la base de données le document suivant sous la clé `facture_43` : ``` {"nom": "Atelier mobile", "montant": 250} ``` Exemple de mise à jour : ``` {{:save key="facture_43" montant=300}} ``` Exemple de récupération du nouvel ID : ``` {{:save titre="Coucou !" assign_new_id="id"}} Le document n°{{$id}} a bien été enregistré. ``` ### Validation avec un schéma JSON ``` {{:save titre="Coucou" texte="Très long" validate_schema="./document.schema.json"}} ``` Pour ne valider qu'une partie du schéma, par exemple si on veut faire une mise à jour du document : ``` {{:save key="test" titre="Coucou" validate_schema="./document.schema.json" validate_only="titre"}} ``` ## delete Supprime un document lié au module courant. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `key` | optionnel | Clé unique du document | | `id` | optionnel | Numéro unique du document | Il est possible de spécifier d'autres paramètres, ou une clause `where` et des paramètres dont le nom commence par deux points. * Supprimer le document avec la clé `facture_43` : `{{:delete key="facture_43"}}` * Supprimer le document avec la clé `ABCD` et dont la propriété `type` du document correspond à la valeur `facture` : `{{:delete key="ABCD" type="facture"}}` * Supprimer tous les documents : `{{:delete}}` * Supprimer tous les documents ayant le type `facture` : `{{:delete type="facture"}}` * Supprimer tous les documents de type `devis` ayant une date dans le passé : `{{:delete :type="devis" where="$$.type = :type AND $$.date < datetime()"}}` ## read Lire un fichier stocké dans les fichiers du code du module. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `file` | obligatoire | Chemin du fichier à lire | | `assign` | optionnel | Variable dans laquelle placer le contenu du fichier. | Si le paramètre `assign` n'est pas utilisé, le contenu du fichier sera affiché directement. Exemple pour lire un fichier JSON : ``` {{#read file="baremes.json" assign="baremes"}} {{:assign baremes=$baremes|json_decode}} Barème kilométrique pour une voiture de 3 CV : {{$baremes.voiture.3cv}} ``` Exemple pour lire un fichier CSV : ``` {{#read file="baremes.csv" assign="baremes"}} {{:assign baremes=$baremes|trim|explode:"\n"}} {{#foreach from=$baremes item="line"}} {{:assign bareme=$line|str_getcsv}} Nom du barème : {{$bareme.0}} Calcul : {{$bareme.1}} {{/foreach}} ``` ## admin_header Affiche l'entête de l'administration de l'association. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `title` | *optionnel* | Titre de la page | | `layout` | *optionnel* | Aspect de la page. Peut être `public` pour une page publique simple (sans le menu), ou `raw` pour une page vierge (sans aucun menu ni autre élément). Défaut : vide (affichage du menu) | | `current` | *optionnel* | Indique quel élément dans le menu de gauche doit être marqué comme sélectionné | | `custom_css` | *optionnel* | Fichier CSS supplémentaire à appeler dans le `` | ``` {{:admin_header title="Gestion des dons" current="acc"}} ``` Liste des choix possibles pour `current` : * `home` : menu Accueil * `users` : menu Membres * `users/new` : sous-menu "Ajouter" de Membres * `users/services` : sous-menu "Activités et cotisations" de Membres * `users/mailing` : sous-menu "Message collectif" de Membres * `acc` : menu Comptabilité * `acc/new` : sous-menu "Saisie" de Comptabilité * `acc/accounts` : sous-menu "Comptes" * `acc/simple` : sous-menu "Suivi des écritures" * `acc/years` : sous-menu "Exercices et rapports" * `docs` : menu Documents * `web` : menu Site web * `config` : menu Configuration * `me` : menu "Mes infos personnelles" * `me/services` : sous-menu "Mes activités et cotisations" Exemple d'utilisation de `custom_css` depuis un module : ``` {{:admin_header title="Mon module" custom_css="./style.css"}} ``` ## admin_footer Affiche le pied de page de l'administration de l'association. ``` {{:admin_footer}} ``` ## delete_form Affiche un formulaire demandant la confirmation de suppression d'un élément. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `legend` | **obligatoire** | Libellé de l'élément `` du formulaire | | `warning` | **obligatoire** | Libellé de la question de suppression (en gros en rouge) | | `alert` | *optionnel* | Message d'alerte supplémentaire (bloc jaune) | | `info` | *optionnel* | Informations liées à la suppression (expliquant ce qui va être impacté par la suppression) | | `confirm` | *optionnel* | Libellé de la case à cocher pour la suppression, si ce paramètre est absent ou `NULL`, la case à cocher ne sera pas affichée. | Le formulaire envoie un `POST` avec le bouton ayant le nom `delete`. Si le paramètre `confirm` est renseigné, alors la case à cochée aura le nom `confirm_delete`. Exemple : ``` {{#load id=$_GET.id assign="invoice"}} {{else}} {{:error message="Facture introuvable"}} {{/load}} {{#form on="delete"}} {{if !$_POST.confirm_delete}} {{:error message="Merci de cocher la case"}} {{/if}} {{:delete id=$invoice.id}} {{/form}} {{:form_errors}} {{:delete_form legend="Suppression d'une facture" warning="Supprimer la facture n°%d ?"|args:$invoice.id info="Le devis lié sera également supprimé" alert="La facture sera définitivement perdue !" confirm="Cocher cette case pour confirmer la suppression de la facture" }} ``` ## input Crée un champ de formulaire HTML. Cette fonction est une extension à la balise `` en HTML, mais permet plus de choses. | Paramètre | Obligatoire ou optionnel ? | Fonction | | :- | :- | :- | | `name` | **obligatoire** | Nom du champ | | `type` | **obligatoire** | Type de champ | | `required` | *optionnel* | Mettre à `true` si le champ est obligatoire | | `label` | *optionnel* | Libellé du champ | | `help` | *optionnel* | Texte d'aide, affiché sous le champ | | `default` | *optionnel* | Valeur du champ par défaut, si le formulaire n'a pas été envoyé, et que la valeur dans `source` est vide | | `source` | *optionnel* | Source de pré-remplissage du champ. Si le nom du champ est `montant`, alors la valeur de `[source].montant` sera affichée si présente. | Si `label` ou `help` sont spécifiés, le champ sera intégré à une balise HTML `
`, et le libellé sera intégré à une balise `
`. Dans ce cas il faut donc que le champ soit dans une liste `
`. Si ces deux paramètres ne sont pas spécifiés, le champ sera le seul tag HTML. ```
{{:input name="amount" type="money" label="Montant" required=true}}
``` Note : le champ aura comme `id` la valeur `f_[name]`. Ainsi un champ avec `amount` comme `name` aura `id="f_amount"`. ### Valeur du champ La valeur du champ est remplie avec : * la valeur dans `$_POST` qui correspond au `name` ; * sinon la valeur dans `source` (tableau) avec le même nom (exemple : `$source[name]`) ; * sinon la valeur de `default` est utilisée. Note : le paramètre `value` n'est pas supporté sauf pour checkbox et radio. ### Types de champs supportés * les types classiques de `input` en HTML : text, search, email, url, file, date, checkbox, radio, password, etc. * Note : pour checkbox et radio, il faut utiliser le paramètre `value` en plus pour spécifier la valeur. * `textarea` * `money` créera un champ qui attend une valeur de monnaie au format décimal * `datetime` créera un champ date et un champ texte pour entrer l'heure au format `HH:MM` * `radio-btn` créera un champ de type radio mais sous la forme d'un gros bouton * `select` crée un sélecteur de type ``, mais avec des ``. Dans ce cas il convient d'indiquer un tableau associatif à deux niveaux dans le paramètre `options`. * `list` crée un champ permettant de sélectionner un ou des éléments (selon si le paramètre `multiple` est `true` ou `false`) dans un formulaire externe. Le paramètre `can_delete` indique si l'utilisateur peut supprimer l'élément déjà sélectionné (si `multiple=false`). La sélection se fait à partir d'un formulaire dont l'URL doit être spécifiée dans le paramètre `target`. Les formulaires actuellement supportés sont : * `!acc/charts/accounts/selector.php?targets=X` pour sélectionner un compte du plan comptable, où X est une liste de types de comptes qu'il faut permettre de choisir (séparés par des `:`) * `!users/selector.php` pour sélectionner un membre ## button Affiche un bouton, similaire à `