documentation

README.md

@@ -1,5 +1,5 @@
 # gamuMail
-> P.O.C pour généraliser un formulaire d'envoi de message
+> formulaire d'envoi de messages configurables
 ## Il gere nativement :
 * Pour
 * Cc en meta : **gamumail/mail_cc**
@@ -13,9 +13,10 @@
 ## Il gere des modèles de contenu pour :
 * Sujet
 * Texte
+* ID documents joints (spip_documents)
 ---
 
-* Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre creer / modifié QUE par les webmestres
+* 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 inclure dans une page :
 ```html
 <INCLURE{fond=inclure/gamumail_config,env}>
@@ -48,8 +49,29 @@ ex de fichier :
 * gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes
 * gamumail/SLUG_fichier.html -> à la fin du formulaire
 
+### aide à la rédaction du contenu:
+- le fichier **gamumail/remplacement_slugs.html** (surchargeable donc) 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** 
+(= ceux fournis par le pipeline **remplacement_slugs**, cf ci-dessous)
+- 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)]
+
+<BOUCLE_dest(AUTEURS){id_auteur=#ENV{dest}}{tout}>
+	<div class="inner">
+		<div class="ajax mbl">
+			<h1>Envoyer un mail à [(#PRENOM|ucfirst) ][(#NOM|ucfirst)]</h1>
+
+			<INCLURE{fond=inclure/envoyer_gamumail, env, id_destinataire=#ID_AUTEUR}>
+		</div>
+	</div>
+</BOUCLE_dest>
+```
+
 ### Dans le php
-#### 1. Appel du formualire
+#### 1. Appel du formulaire
 > Args du formulaire :
 >
 ```php
@@ -79,6 +101,8 @@ Pour chaque étape, on peut modifier l'Array de sortie :
 * 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):
 * pour charger : **gamumail/charger.php** pour tous les formulaires ou
 * pour charger : **gamumail/SLUG_charger.php** avec une fonction :
@@ -94,7 +118,6 @@ function gamumail_SLUG_verifier($erreurs, $options = []){
 	return $erreurs;
 }
 ```
-* pour traiter : **gamumail/traiter.php** pour tous les formulaires ou
 * pour traiter : **gamumail/SLUG_traiter.php** avec une fonction ex:
 ```php
 function gamumail_contrat_resa_traiter($corps, $options = []){
@@ -117,11 +140,38 @@ function gamumail_contrat_resa_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
+ * 		$flux['args']['slug'] = $slug
+ *		$flux['args']['destinataires'] = $destinataires
+ *		$flux['args']['options'] = $options
+ * @return array $flux données du pipeline
+```
 
-#### 3. Ajouter un header / footer dans notre content html
+#### 4. 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
 
+
+## API d'envoi de mails utilisant les slugs
+### fonction envoyer_gamumail()
+- exemple d'appel : 
+```php
+$fonction = charger_fonction('envoyer_gamumail','inc');
+$fonction(lire_config('souscriptions/slug_souscription_creation'), $Tdest, ['debug' => false, 'nb_parts' => intval(_request('nombre'))]);
+```
+- arguments :
+```php
+ * @param string $slug
+ * @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array
+ * 		si un des destinataire est au format numérique, on considère que c'est un id_auteur et on va choper son mail dans spip_auteurs
+ * @param array $options :
+ * 		$options['debug' => true] pour afficher le $corps final sans envoyer le mail
+ * 		$options['cci' => true] pour passer tous les destinataires en cci si il y en a plus qu'un
+```

inclure/envoyer_gamumail.html

@@ -35,6 +35,7 @@
 	<div class="bloc_slug" id="bloc_slug">
 		<INCLURE{fond=inclure/vue_slug, env, ajax=vue_slug}>
 	</div>
+	<INCLURE{fond=gamumail/remplacements_slugs}>
 </div>
 <script type="text/javascript">
 	jQuery(function() {