Publipostage

Documentation sur le publipostage.

Définition

Le publipostage consiste à générer un document Word à partir des données d'une page E-ASY et d'un modèle Word défini dans le backend (qui comporte des placeholders). Pour cela le formulaire de la page doit définir un composant de type "bouton d'export".

Création d'un modèle

Dans le backend d'un projet le menu Configuration > Modèles Word permet de créer des modèles Word :

1. On choisit une page.
2. On uploade le modèle Word.
3. On enregistre.
4. On peut facultativement choisir un champ upload pour sauvegarder le document

Un modèle Word est un fichier Word classique qui utilise des placeholders, c'est à dire des variables qui correspondent aux champs du formulaire de la page qui sera générée.

Note: la liste complète des variables disponibles est affichée dans la rubrique Champs disponibles.

Exemple

Sur la page "personnes" d'un projet fictif, on définit le modèle Word suivant :

Bonjour je m'appelle ${prenom} !

Lorsque l'utilisateur se rendra sur le formulaire d'une personne en particulier, et qu'il appuiera sur le bouton d'export correspondant à son modèle, il obtiendra le document suivant :

Bonjour je m'appelle Jean !

Sélection des champs disponibles

Une fois la page sélectionnée dans le formulaire, la liste des champs disponibles pour le publipostage est affichée.
Les champs disponibles sont les champs de la page et ceux des pages liées.

Pour inclure les champs dans le publipostage, il faut se servir de l'alias présent dans la colonne alias sous la forme ${alias}

Utilisation de l'alias date_demande : ${date_demande}

Pour qu'un champ soit utilisable, il faut qu'il soit flagué à actif.

Par défaut, tous les champs de la page sélectionnée sont actifs.

Images

Le publipostage permet aussi le remplacement d'un placeholder du modèle par une ou plusieurs images uploadées par l'utilisateur via le formulaire.

Si un formulaire possède plusieurs images, le placeholder doit se terminer par le numéro de l'image :

Voici l'image 1 : ${mon_champ_upload1}
Voici l'image 2 : ${mon_champ_upload2}
Voici l'image 3 : ${mon_champ_upload3}

Il est possible d'intégrer les images d'un upload multiple sous forme de bloc :

${mon_champ_upload}
${multi_image_block:[largeur]x[hauteur]}
${/mon_champ_upload}

${multi_image_block} sera remplacé par les images du champ upload multiple

Enfin on peut modifier la taille et le ratio de l'image dans le modèle :

${mon_champ_upload:[largeur]:[hauteur]:[ratio]}
${mon_champ_upload:[largeur]x[hauteur]}
${mon_champ_upload:size=[largeur]x[hauteur]}
${mon_champ_upload:width=[largeur]:height=[hauteur]:ratio=false}

• La largeur et la haute de l'image sont des nombres avec une unité de mesure (cm, mm, in, pt, pc, px, %, em).
• Par défaut le ratio de l'image est respecté, pour le désactiver il faut définir l'option à false.

Champ upload

Si on choisit d'associer le modèle à un champ upload, lorsqu'un utilisateur génèrera un document il sera automatiquement envoyé dans le champ upload en plus du téléchargement.

• Champ upload simple : La pièce jointe est écrasée à chaque génération
• Champ upload multiple : La pièce jointe est ajoutée en plus des documents déjà dans le champ.

Mode avancé

Le mode avancé permet de définir une requête SQL personnalisée pour aller chercher des informations supplémentaires. Attention, ce mode est disponible uniquement sur l'administrateur possède la permission.

La requête est systématiquement exécutée avec l'identifiant de l'enregistrement comme paramètre :

SELECT ma_table_jointe.mon_champ AS mon_placeholder FROM ma_table
JOIN ma_table_jointe on ma_table.id = ma_table_jointe.ma_table_id
WHERE ma_table.id = ?

Note :

• les champs récupérés dans le SELECT doivent impérativement être aliasés avec un nom différent du nom en base pour être utilisés dans le modèle.
• Si pas d'alias, les champs ne seront pas pris en compte.
• Les champs de la requête custom s'ajoutent à ceux déjà disponible, ils ne s'y substituent pas.

Retours à la ligne

L'inclusion de champs de type longtext prend maintenant automatiquement en compte les retours à la ligne dans le model.

Retour à la ligne dans les champs perso: le retour à la ligne dans un document Word n'est pas codé par \n mais par </w:t><w:br/><w:t> !

Nom du fichier

Il est possible de définir le nom du fichier généré dans le champ Nom fichier.
Pour la définition du nom de fichier, il est possible d'utiliser les mêmes placeholder que dans le document.

Si le champ nom fichier est laissé vide, le descriptor de la page sera utilisé.

Génération PDF

Il est possible de déterminer le format de génération du fichier :

• Word
• PDF

La sélection du format se fait dans le champ type.

Définition de blocs

Dans le modèle, il est possible de déterminer des parties à dupliquer.
Il existe deux types de blocs :

• Les tableaux
• Les blocs

Il est possible de définir un bloc à partir de deux types de données :

• À partir d'une requête sql
• À partir d'une page liée

Blocs à partir d'une requête sql

Ces blocs sont définis dans un champ de type repeater.

Pour ajouter un bloc, il faut appuyer sur le bouton Ajouter un bloc. Il est possible d'ajouter plusieurs blocs au modèle.

Tableau

Un tableau est défini par un alias utilisé pour sélectionner le tableau et une requête sql permettant de récupérer les résultats. Le tableau présentera autant de ligne que d'enregistrements retournés par la requête sql.

Exemple de configuration :

SELECT ma_table_jointe.mon_champ AS colonne1,ma_table_jointe.mon_champ2 AS colonne2 FROM ma_table
JOIN ma_table_jointe on ma_table.id = ma_table_jointe.ma_table_id
WHERE ma_table.id = ?

Dans l'exemple :

• ma_table correspond à l'alias du tableau
• colonne1 et colonne2 correspondent aux alias de la requête mysql

Bloc

Un bloc correspond à une partie de texte formatée qui sera reproduite avec des valeurs différentes.
Les valeurs d'un bloc sont récupérés à partir d'une requête sql. Il y aura autant de blocs que de résultats dans la requête sql.

Exemple de configuration :

SELECT ma_table_jointe.mon_champ AS valeur1,ma_table_jointe.mon_champ2 AS valeur2 FROM ma_table
JOIN ma_table_jointe on ma_table.id = ma_table_jointe.ma_table_id
WHERE ma_table.id = ?

Un saut de ligne doit suivre la balise ouvrante et un saut de ligne doit précédé la balise fermante.

Blocs à partir d'une page liée

Il est possible d'intégrer un bloc à partir de toutes les pages standards liées à la page du modèle.
Le nombre de blocs dans un modèle n'est pas limité.

Formulaire d'ajout

Pour ajouter un bloc, il faut cliquer sur le bouton Ajouter de la liste des blocs.

Formulaire d'ajout d'un bloc:

Il faut remplir les champs suivant pour configurer un bloc :

• Alias (doit être unique dans le modèle)
• Sélection d'une page
• Choix du type de bloc tableau ou bloc
• Choix des champs à utiliser dans le publipostage

Par soucis de performance, tous les champs disponibles sont inactifs par défaut.

Il est possible de filter les enregistrements d'un bloc à partir d'une requête sql renseignée dans champ Filtre du bloc.

clients.nom = "client1" AND maintenances.date_fin > "2021-01-01"

Il est possible de trier les enregistrements d'un bloc à partir d'une requête sql renseignée dans champ Filtre du bloc.

maintenances.date_fin DESC, clients.nom ASC