doc
This commit is contained in:
parent
27d04e9eee
commit
ee44ab4bed
1 changed files with 114 additions and 87 deletions
199
README.md
199
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)
|
||||
|
||||
|
||||
- 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)
|
||||
|
||||
|
||||
## 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`
|
||||
|
||||
|
||||
- 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`
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
> **/!\ Le name doit etre Tid_doc**
|
||||
>
|
||||
ex de fichier :
|
||||
> ex de fichier :
|
||||
|
||||
```html
|
||||
<B_doc>
|
||||
<h2>Fichiers attachés au séjour</h2>
|
||||
|
|
@ -43,24 +54,28 @@ ex de fichier :
|
|||
</div>
|
||||
</B_doc>
|
||||
```
|
||||
|
||||
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
|
||||
<option value="no_gamumail"[ (#ENV{slug}|=={no_gamumail}|oui) selected="selected"]><:souscriptions:pas_de_mail_auto:></option>
|
||||
<option
|
||||
value="no_gamumail"
|
||||
[
|
||||
(#ENV{slug}|=""
|
||||
="{no_gamumail}|oui)"
|
||||
selected="selected"
|
||||
]
|
||||
>
|
||||
<:souscriptions:pas_de_mail_auto:>
|
||||
</option>
|
||||
```
|
||||
|
||||
#### 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 `<INCLURE{fond=inclure/fermer_modale,env}>` 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')) {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue