From ee44ab4bedb9b39216f38b3e9447d2b1f48c7d70 Mon Sep 17 00:00:00 2001 From: tofulm Date: Thu, 2 Jan 2025 14:12:18 +0100 Subject: [PATCH] doc --- README.md | 201 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 114 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 16a222e..f04893c 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,41 @@ # gamuMail + > formulaire d'envoi de messages configurables + ## Il gere nativement : -* Pour -* Cc en meta : **gamumail/mail_cc** -* Cci en en meta : **gamumail/mail_cci** -* Sujet -* Texte -* Les documents attachés au modèle (cf ci-dessous) -* une liste de pdf (il faut le plugin spipdf) -![interface](doc/interface.png "interface") + +- Pour +- Cc en meta : **gamumail/mail_cc** +- Cci en en meta : **gamumail/mail_cci** +- Cci en globals []: `$GLOBALS['gamuza_mail_cci'] = ['sarl.gamuza@gmail.com'];` +- Sujet +- Texte +- Les documents attachés au modèle (cf ci-dessous) +- une liste de pdf (il faut le plugin spipdf) + ![interface](doc/interface.png "interface") ## Il gere des modèles de contenu pour : -* Sujet -* Texte -* ID documents joints (spip_documents) + +- Sujet +- Texte +- ID documents joints (spip_documents) + --- -* Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre créé / modifié QUE par les webmestres -* Pour gerer ses modèles, il faut se rendre sur la page : `?page=configuration_mails` -![configuration](doc/configuration.png "Exemple de configuration") + +- Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre créé / modifié QUE par les webmestres +- Pour gerer ses modèles, il faut se rendre sur la page : `?page=configuration_mails` + ![configuration](doc/configuration.png "Exemple de configuration") ## Personnalisation du formulaire d'envoi + ### Dans le html -On peut ajouter des documents via un fichier du type : **gamumail/SLUG_fichier.html** SLUG doit etre remplacé par le nom du slug du modèle + +On peut ajouter des documents via un fichier du type : **gamumail/SLUG_fichier.html** SLUG doit etre remplacé par le nom du slug du modèle + > **/!\ Le name doit etre Tid_doc** > -ex de fichier : +> ex de fichier : + ```html

Fichiers attachés au séjour

@@ -43,24 +54,28 @@ ex de fichier : ``` + 3 branchements possibles : -* gamumail/SLUG_debutform.html -> au début du form -* gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes -* gamumail/SLUG_fichiers.html -> à la fin du formulaire + +- gamumail/SLUG_debutform.html -> au début du form +- gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes +- gamumail/SLUG_fichiers.html -> à la fin du formulaire ### aide à la rédaction du contenu: + - le fichier **gamumail/remplacement_slugs.html** s'affiche en bas de la page de configuration des modèles **inclure/gamumail_config.html** -et du formulaire d'envoi **formulaires/gamumail.html** : il permet de lister les remplacements effectués pour **tous les modèles** qui sont : - - les génériques fournis par Gamumail par la fonction `inc_gamumail_remplacements_dist()` du fichier `inc/gamumail_remplacements.php` - - ceux fournis par les plugins via le pipeline **remplacement_slugs** (cf ci-dessous) + et du formulaire d'envoi **formulaires/gamumail.html** : il permet de lister les remplacements effectués pour **tous les modèles** qui sont : - les génériques fournis par Gamumail par la fonction `inc_gamumail_remplacements_dist()` du fichier `inc/gamumail_remplacements.php` - ceux fournis par les plugins via le pipeline **remplacement_slugs** (cf ci-dessous) - pour documenter les remplacements (pied de la page gamumail_config.html), chaque plugin doit renseigner ses remplacements dans l'array global `$GLOBALS['remplacements_gamumail']` -Exemple dans un fichier `prefixe_fonctions.php` : + Exemple dans un fichier `prefixe_fonctions.php` : + ```php $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture'; ``` + - une page de test des slugs est fournie à l'URL **...?page=test_slug&slug=mail_libre&dest=27** ### exemple de page d'envoi de mail en choisissant un slug parmi ceux existant : + ```html [(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)] @@ -76,9 +91,11 @@ $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture'; ``` ### Dans le php + #### 1. Appel du formulaire + > Args du formulaire : -> + ```php /** * formulaire générique pour envoyer des mails avec pieces attachés @@ -99,100 +116,93 @@ $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture'; function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){ } ``` + #### argument $slug "no_gamumail" + Si $slug à pour valeur **no_gamumail** alors l'envoi est annulé Exemple d'option à insérer dans un select sélecteur de slug : + ```html - + ``` #### argument Tclient + l'Argument $Tclient est utilisé pour récupérer des emails dans un ou X autres Objets SPIP #### argument Tpdf : attacher des PDF avec contenu dynamique + - exemple d'appel pour 1 fichier PDF avec son contexte : + ```html -[(#FORMULAIRE_GAMUMAIL{ - #ENV{slug}, - #ENV{email}, - '', - #ARRAY{ - fichier,pdf_guide, - nom,Fiche_guide, - contexte,#ARRAY{ - id_article,#ENV{id_article}, - type_guide,#ENV{type_guide,guide} - } - }, - #ENV{redirect}, - #ARRAY{ - id_auteur,#ENV{id_auteur} - } -})] +[(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ fichier,pdf_guide, +nom,Fiche_guide, contexte,#ARRAY{ id_article,#ENV{id_article}, +type_guide,#ENV{type_guide,guide} } }, #ENV{redirect}, #ARRAY{ +id_auteur,#ENV{id_auteur} } })] ``` + le fichier PDF sera généré par SPIPDF avec l'URL suivante : `...spip.php?page=spipdf&spipdf=pdf_guide&id_article=1838&type_guide=guide` - exemple d'appel pour 2 fichiers PDF générés par le même squelette (pdf_guide.html) mais avec chacun leur contexte : + ```html -[(#FORMULAIRE_GAMUMAIL{ - #ENV{slug}, - #ENV{email}, - '', - #ARRAY{ - 0,#ARRAY{ - fichier,pdf_guide, - nom,Fiche_guide, - contexte,#ARRAY{ - id_article,#ENV{id_article}, - type_guide,guide, - } - }, - 1,#ARRAY{ - fichier,pdf_guide, - nom,Fiche_guide_renfort, - contexte,#ARRAY{ - id_article,#ENV{id_article}, - type_guide,guide_renfort, - } - } - }, - #ENV{redirect}, - #ARRAY{ - id_auteur,#ENV{id_auteur} - } -})] +[(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ 0,#ARRAY{ +fichier,pdf_guide, nom,Fiche_guide, contexte,#ARRAY{ +id_article,#ENV{id_article}, type_guide,guide, } }, 1,#ARRAY{ fichier,pdf_guide, +nom,Fiche_guide_renfort, contexte,#ARRAY{ id_article,#ENV{id_article}, +type_guide,guide_renfort, } } }, #ENV{redirect}, #ARRAY{ +id_auteur,#ENV{id_auteur} } })] ``` + /!\ en cas de plusieurs PDF : - - il faut une *clé unique* pour chaque #ARRAY (0, 1, 2... est une bonne solution) - - dans l'#ARRAY contexte il faut que le dernier élément soit suivi d'une virgule ou d'une accolade fermante + +- il faut une _clé unique_ pour chaque #ARRAY (0, 1, 2... est une bonne solution) +- dans l'#ARRAY contexte il faut que le dernier élément soit suivi d'une virgule ou d'une accolade fermante #### 2. surcharges de chaque étape: charger / vérifier / traiter + Pour chaque étape, on peut modifier l'Array de sortie : -* charger -> $valeurs -* verifier -> $erreurs -* traiter -> $corps (array du message envoyé à facteur) + +- charger -> $valeurs +- verifier -> $erreurs +- traiter -> $corps (array du message envoyé à facteur) Voir **gamumail_fonctions.php** pour les arguments des fonctions de surcharge + exemples Pour cela, il faut creer une fonction du type (qui utilise les memes arg que les fonctions CVT + premier arg l'Array que l'on veut modifier) La surcharge pour tous les slugs (`gamumail_tous_...`) précède celle spécifique par slug : on peut donc utiliser les 2 successivement. Syntaxe : -* pour charger pour tous les slugs : **gamumail/tous_charger.php** (fonction `gamumail_tous_charger()`) -* pour charger spécifique d'un slug : **gamumail/NOM_SLUG_charger.php** avec une fonction : + +- pour charger pour tous les slugs : **gamumail/tous_charger.php** (fonction `gamumail_tous_charger()`) +- pour charger spécifique d'un slug : **gamumail/NOM_SLUG_charger.php** avec une fonction : + ```php function gamumail_NOM_SLUG_charger($valeurs, $options = []){ return $valeurs; } ``` -* pour verifier pour tous les slugs : **gamumail/tous_verifier.php** (fonction `gamumail_tous_verifier()`) -* pour verifier spécifique d'un slug : **gamumail/NOM_SLUG_verifier.php** avec une fonction : + +- pour verifier pour tous les slugs : **gamumail/tous_verifier.php** (fonction `gamumail_tous_verifier()`) +- pour verifier spécifique d'un slug : **gamumail/NOM_SLUG_verifier.php** avec une fonction : + ```php function gamumail_NOM_SLUG_verifier($erreurs, $options = []){ return $erreurs; } ``` -* pour traiter pour tous les slugs : **gamumail/tous_traiter.php** (fonction `gamumail_tous_traiter()`) -* pour traiter spécifique d'un slug : **gamumail/NOM_SLUG_traiter.php** avec une fonction par ex: + +- pour traiter pour tous les slugs : **gamumail/tous_traiter.php** (fonction `gamumail_tous_traiter()`) +- pour traiter spécifique d'un slug : **gamumail/NOM_SLUG_traiter.php** avec une fonction par ex: + ```php function gamumail_NOM_SLUG_traiter($corps, $options = []){ if (array_key_exists('id_article', $options)) { @@ -214,8 +224,11 @@ function gamumail_NOM_SLUG_traiter($corps, $options = []){ return $corps; } ``` + #### 3. Pipeline remplacements_slug pour le traitement du contenu des messages + Pour les remplacements des @@ et tout autre traitement du texte des mails on utilisera le pipeline **remplacements_slug** qui utilise les arguments suivants : + ```php * @param array $flux données du pipeline : * $flux['data'] = $html @@ -250,27 +263,35 @@ Pour les remplacements des @@ et tout autre traitement du texte des mails on uti } ``` + #### 4. Pipeline post_gamumail_ok + Ce pipeline est appelé si le retour de l'envoi du gamumail est OK. Il permet, par exemple, à Paybyurl d'aller modifier le champ date_paybyurl_envoye pour que la date d'envoi soit mise à jour. #### 5. Ajouter un header / footer dans le content html + on peut définir un header / footer pour les messages : -* gamumail/html_header.html => header pour tous les mails -* gamumail/html_footer.html => footer pour tous les mails -* gamumail/SLUG_html_header.html => pour les mails du modele SLUG -* gamumail/SLUG_html_footer.html => pour les mails du modele SLUG + +- gamumail/html_header.html => header pour tous les mails +- gamumail/html_footer.html => footer pour tous les mails +- gamumail/SLUG_html_header.html => pour les mails du modele SLUG +- gamumail/SLUG_html_footer.html => pour les mails du modele SLUG #### 6. Utiliser l'inclure `` pour fermeture de la modale de gamumail + - cet inclure est appelé au début de `formulaire/gamumail.html` : par défaut il est vide - un plugin peut arriver avec son fichier pour le surcharger afin de pouvoir intégrer du JS en fonction du message de retour `message_ok` du traiter de gamumail.php - dans `gamumail.php`, la fonction `gamumail_traiter` ajoute en fin du message de retour OK `message_ok` le suffixe `@@gamumail_ok` - il est donc possible de tester la présence de ce suffixe dans `message_ok` pour afficher du JS qui permet de refermer la modale dans laquelle est chargée gamumail -mais aussi de faire la mise à jour de l'affichage d'un bloc ajax dans la page appelante. -=> voir le code en commentaire dans le fichier `inclure/fermer_modale` + mais aussi de faire la mise à jour de l'affichage d'un bloc ajax dans la page appelante. + => voir le code en commentaire dans le fichier `inclure/fermer_modale` ## API d'envoi de mails utilisant les slugs + ### fonction envoyer_gamumail() + - exemple d'appel : + ```php $fonction = charger_fonction('envoyer_gamumail','inc'); $options = [ @@ -286,7 +307,9 @@ $options = [ ]; $fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $options); ``` + - arguments : + ```php * @param string $slug * @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array @@ -304,11 +327,15 @@ $fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $op ``` ## Outrepasser l'erreur de certificat auto-signé lors de devs en https local + => dans le mes_options.php du site mettre : + ``` define('_DEBUG_AUTORISER', true); ``` -ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans *charger_pdf.php* : + +ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans _charger_pdf.php_ : + ``` // pour une connexion https locale avec certificat auto-signé if (defined('_DEBUG_AUTORISER')) {