Personnalisation avancée des modèles de documents

Les modèles de documents dans Kafinea permettent une personnalisation poussée grâce à l’utilisation de balises HTML et de styles CSS spécifiques.

---

1. Mise en page multi-colonnes #

Il est possible de diviser le contenu d’un bloc en plusieurs colonnes, ce qui est particulièrement utile pour les listes d’informations ou les sections de bas de page.

Utilisation de la balise <columns> #

Kafinea supporte la balise spécifique <columns> pour créer des mises en page multi-colonnes simples.

Attributs disponibles :

• column-count : Nombre de colonnes souhaité.
• column-gap : Espace entre les colonnes (en mm).

Exemple :

<columns column-count="3" column-gap="10">
    <div>Contenu de la première colonne...</div>
    <div>Contenu de la deuxième colonne...</div>
    <div>Contenu de la troisième colonne...</div>
</columns>

Utilisation des styles CSS #

Vous pouvez également utiliser les propriétés CSS standards sur des éléments <div> :

• column-count
• column-gap
• column-span

Exemple :

<div style="column-count: 2; column-gap: 5mm;">
    <p>Texte qui sera automatiquement réparti sur deux colonnes...</p>
</div>

---

2. Polices de caractères disponibles #

En plus des polices standards, de nouvelles polices modernes sont disponibles pour vos modèles.

Liste des nouvelles polices #

• Montserrat : Une police sans-serif géométrique, moderne et très lisible.
• Pathway Extreme : Une police sans-serif à chasse étroite, idéale pour les mises en page denses.

Comment appliquer une police #

Pour utiliser ces polices, vous devez les déclarer dans le style CSS de votre modèle (généralement dans une balise <style> au début du document ou via l’attribut style d’un élément).

Exemple :

<style>
    body {
        font-family: 'montserrat', sans-serif;
    }
    .titre-important {
        font-family: 'pathwayextreme', sans-serif;
        font-weight: bold;
    }
</style>

Note technique : Les noms de polices à utiliser dans le CSS sont montserrat (minuscules) et pathwayextreme (minuscules, sans espace).

---

3. Conditions et calculs #

Un modèle peut contenir des instructions évaluées au moment de la génération du PDF : afficher un texte ou une colonne selon une valeur du document, calculer un montant, mettre un nombre en forme. Ces instructions sont délimitées par {* et *}. Les accolades simples de vos règles CSS (body { … }) ne sont pas concernées.

Écrire une condition #

<p>{*if '$doc-pricesIncludeTax$' == 'YES'*}Prix TTC{*else*}Prix HT{*/if*}</p>

• Structure : {*if …*}, puis éventuellement {*elseif …*} et {*else*}, et toujours {*/if*} pour fermer.
• Opérateurs : == (égal), != (différent), >, <, >=, <=, && (et), || (ou), et les parenthèses pour grouper.
• Balises dans une instruction : écrivez-les toujours entre apostrophes, par exemple '$item-quantity$'. Kafinea remplace la balise par sa valeur avant d’évaluer l’instruction ; les apostrophes garantissent qu’une valeur contenant des espaces, des apostrophes ou du texte est lue correctement.
• Texte accentué : pour comparer une valeur qui peut contenir des accents, utilisez equalsWithAccents, par exemple {*if '$item-category$'|equalsWithAccents:'Matériel'*}…{*/if*}.

Où placer une condition #

À l’enregistrement, Kafinea nettoie le HTML du modèle pour ne conserver qu’un document valide. Une condition écrite comme du texte n’est conservée que là où du texte est permis :

Une condition en forme directe placée entre deux cellules est retirée à l’enregistrement, et un style qui en contient une est retiré entier. La forme commentée est conservée telle quelle : Kafinea la convertit en condition au moment de la génération.

Exemple : une colonne présente uniquement sur les documents TTC

<tr>
    <th>Désignation</th>
    <th>Prix unitaire HT</th>
    <!-- {*if '$doc-pricesIncludeTax$' == 'YES'*} -->
    <th>Prix unitaire TTC</th>
    <!-- {*/if*} -->
    <th>TVA</th>
</tr>

Les cellules de la ligne d’article suivent le même principe, et une ligne de total qui s’étend sur toutes les colonnes adapte son colspan :

<td colspan="{*if '$doc-pricesIncludeTax$' == 'YES'*}4{*else*}3{*/if*}">Total HT</td>

Exemple : une largeur de colonne différente selon le cas

La condition ne peut pas se trouver dans le style ; écrivez la cellule deux fois :

<!-- {*if '$doc-pricesIncludeTax$' == 'YES'*} -->
<th style="width: 20mm;">Prix unitaire HT</th>
<!-- {*else*} -->
<th style="width: 30mm;">Prix unitaire HT</th>
<!-- {*/if*} -->

Bon à savoir : la forme commentée accepte uniquement if, elseif, else et /if. Les autres instructions se placent dans le texte d’un élément.

Vérifiez après l’enregistrement : rouvrez le modèle et contrôlez que chaque condition est toujours présente, puis générez un aperçu sur un document de chaque cas (par exemple un document TTC et un document HT).

Calculer et mettre en forme un montant #

Les balises de montant existent en deux variantes :

Un calcul utilise toujours la variante brute : la valeur mise en forme contient des séparateurs de milliers et une virgule décimale, qui ne sont pas lus comme un nombre. La quantité ($item-quantity$) est fournie brute.

<td>{*('$item-listPriceUnformatted$' * '$item-quantity$')|number_format:2:",":" "*} €</td>

Avec un prix de 1234.5 et une quantité de 3, la cellule affiche 3 703,50 €.

Les modificateurs s’ajoutent après une barre verticale | :

{*('$item-totalAfterDiscountUnformatted$'|floatval * 1.2)|string_format:"%.2f"|replace:".":","*}

Les balises brutes disponibles pour les lignes sont notamment $item-listPriceUnformatted$, $item-listPriceAfterDiscountUnformatted$, $item-totalUnformatted$, $item-discountAmountUnformatted$, $item-totalAfterDiscountUnformatted$, $item-taxTotalAmountUnformatted$ et $item-totalWithTaxUnformatted$ ; pour les totaux du document, $doc-grandTotalWithoutTaxesUnformatted$, $doc-taxTotalAmountUnformatted$ et $doc-grandTotalUnformatted$.

---

4. Documents dont les prix sont saisis TTC #

Lorsque la saisie des prix TTC est activée, un même modèle peut s’adapter aux documents saisis HT et aux documents saisis TTC grâce aux balises suivantes :

Elles complètent les balises de ligne habituelles : $item-listPrice$ (prix unitaire HT), $item-listPriceAfterDiscount$ (prix unitaire net HT), $item-taxTotalPercent$ (taux de taxe de la ligne), $item-totalAfterDiscount$ (montant HT de la ligne) et $item-totalWithTax$ (montant TTC de la ligne).

Factures et avoirs en France : chaque ligne doit indiquer le prix unitaire hors taxes et le taux de TVA applicable (article 242 nonies A de l’annexe II du Code général des impôts). Une colonne de prix unitaire TTC peut s’ajouter à ces informations ; elle ne remplace pas le prix unitaire HT.

Exemple : cellules d’une ligne d’article conformes pour les deux cas

<td>$item-name$</td>
<td>$item-quantity$</td>
<td>$item-listPriceAfterDiscount$</td>
<!-- {*if '$doc-pricesIncludeTax$' == 'YES'*} -->
<td>$item-listPriceAfterDiscountInclTax$</td>
<!-- {*/if*} -->
<td>$item-taxTotalPercent$ %</td>
<td>$item-totalAfterDiscount$</td>

---

5. Conseils pour le rendu PDF #

Le moteur de rendu PDF (mPDF) interprète le HTML et le CSS. Pour un résultat optimal :

• Utilisez des unités physiques comme mm ou cm pour les marges et les largeurs.
• Privilégiez les tableaux (<table>) pour les données structurées et les grilles complexes.
• Testez toujours votre modèle avec l’aperçu avant de le valider pour la production.