Help

Extensions (plugins)

Overview

The Iberis extension system allows any developer to create add-on modules to enhance the platform's capabilities. Extensions are entirely declarative: a JSON manifest file defines data models, pages, menus, hooks, and widgets.

Extensions are submitted for review by the Iberis team before being published on the marketplace. Once approved, companies can install them in one click from the Integrations page.

Extensions feature a complete system: data models with automatic CRUD, custom fields on existing Iberis entities, PDF generation, approval workflows, and guards to block certain actions under conditions.

Ce que vous pouvez construire

Voici des exemples concrets de plugins réalisables avec le système :

Manifest structure

The JSON manifest defines your entire plugin. Basic information (title, description, icon) is entered via the submission form. The technical manifest contains the following sections:

Exemple complet minimal

{
  "models": {
    "task": {
      "numbering": { "prefix": "TSK", "pattern": "{prefix}-{YYYY}-{sequence}" },
      "fields": {
        "title": { "type": "string", "required": true, "label": { "fr": "Titre", "en": "Title" } },
        "description": { "type": "textarea", "label": { "fr": "Description" } },
        "status": { "type": "integer", "default": 0 },
        "amount": { "type": "decimal", "label": { "fr": "Montant", "en": "Amount" } },
        "due_date": { "type": "date", "label": { "fr": "Échéance", "en": "Due date" } },
        "client_id": { "type": "reference", "references": "contacts", "label": { "fr": "Client" } },
        "attachment": { "type": "file", "label": { "fr": "Pièce jointe" } }
      },
      "statuses": {
        "0": { "fr": "Brouillon", "en": "Draft" },
        "1": { "fr": "En cours", "en": "In Progress" },
        "2": { "fr": "Terminé", "en": "Done" },
        "3": { "fr": "Annulé", "en": "Cancelled" }
      }
    }
  },
  "pages": {
    "task_list": {
      "type": "list",
      "model": "task",
      "columns": ["_number", "title", "client_id", "amount", "status", "due_date"]
    },
    "task_form": {
      "type": "form",
      "model": "task",
      "layout": [
        { "row": [{ "field": "title", "col": 8 }, { "field": "status", "col": 4 }] },
        { "row": [{ "field": "client_id", "col": 6 }, { "field": "amount", "col": 6 }] },
        { "row": [{ "field": "due_date", "col": 6 }, { "field": "attachment", "col": 6 }] },
        { "row": [{ "field": "description", "col": 12 }] }
      ]
    }
  },
  "menus": [
    {
      "section": {
        "title": { "fr": "Gestion de tâches", "en": "Task Management" },
        "icon": "fas fa-tasks",
        "items": [
          { "label": { "fr": "Taches", "en": "Tasks" }, "page": "task_list" }
        ]
      }
    }
  ],
  "widgets": {
    "total_tasks": {
      "type": "stats_card",
      "model": "task",
      "aggregate": "COUNT",
      "label": { "fr": "Total tâches", "en": "Total tasks" },
      "icon": "fas fa-tasks",
      "color": "#667eea"
    },
    "total_amount": {
      "type": "stats_card",
      "model": "task",
      "aggregate": "SUM",
      "field": "amount",
      "filter": { "status": 2 },
      "label": { "fr": "Montant termine", "en": "Completed amount" },
      "icon": "fas fa-coins",
      "color": "#10b981"
    },
    "by_status": {
      "type": "chart",
      "chart_type": "donut",
      "model": "task",
      "group_by": "status",
      "aggregate": "COUNT",
      "label": { "fr": "Par statut", "en": "By status" },
      "color": "#667eea"
    }
  },
  "hooks": {},
  "settings": {},
  "extensions": {},
  "guards": {}
}

Pages

Limites à connaître

Field types

Chaque model définit ses champs avec un type. Le moteur crée automatiquement les colonnes en base et le formulaire adapté.

Tous les types

"fields": {
  "name":        { "type": "string", "required": true, "max": 100, "label": { "fr": "Nom" } },
  "notes":       { "type": "textarea", "label": { "fr": "Notes" } },
  "quantity":    { "type": "integer", "default": 1 },
  "price":       { "type": "decimal", "precision": 15, "scale": 3 },
  "is_active":   { "type": "boolean", "default": true },
  "start_date":  { "type": "date" },
  "created_at":  { "type": "datetime" },
  "document":    { "type": "file", "label": { "fr": "Document" } },
  "photo":       { "type": "image", "label": { "fr": "Photo" } },
  "category": { "type": "string", "max": 40, "label": { "fr": "Catégorie (A, B, C…)" } },
  "client_id": {
    "type": "reference",
    "references": "contacts",
    "label": { "fr": "Client" }
  },
  "related_task_id": {
    "type": "reference",
    "references": "@task",
    "label": { "fr": "Tâche liée" }
  },
  "total_computed": {
    "type": "computed",
    "formula": "quantity * price",
    "label": { "fr": "Total" }
  }
}

"article_id": {
  "type": "reference",
  "references": "items",
  "locked_when": { "field": "status", "equals": 1 }
}

Numérotation

Déclarée via numbering sur un model (voir l'exemple task plus haut). Deux clés : prefix (défaut "PLG") et pattern.

Statuses (badges automatiques)

"statuses": {
  "0": { "fr": "Brouillon", "en": "Draft" },
  "1": { "fr": "En attente", "en": "Pending" },
  "2": { "fr": "Approuvé", "en": "Approved" },
  "3": { "fr": "Terminé", "en": "Completed" },
  "4": { "fr": "Rejeté", "en": "Rejected" }
}

Le champ status (integer) devient un select dans le formulaire et un badge coloré dans la liste. Couleurs : 0=secondary, 1=primary, 2=info, 3=success, 4=danger, 5=dark ; au-delà de 5, secondary. Les trois conditions doivent être réunies : le champ doit s'appeler exactement status, être de type integer, et le model doit déclarer statuses.

Formulas and expressions

Utilisées dans les champs computed, les actions de hooks, et les conditions. Le parseur est un AST récursif sécurisé.

Exemples

// Champ computed - total TTC
"formula": "ROUND(quantity * price * (1 + tax_rate / 100), 3)"

// Condition hook - déclencher si montant > 1000
"conditions": [{ "field": "amount", "greater_than": 1000 }]

// Action hook - créer un record avec formule
"fields": {
  "title": "CONCAT('Commande #', number)",
  "total": "SUM(lines.quantity * lines.price)",
  "days_left": "DATE_DIFF(due_date, TODAY())"
}

// Lookup inter-model
"formula": "LOOKUP(@bom, item_id = id, unit_cost)"

// Lire un paramètre du plugin (voir section Paramètres)
"formula": "SETTING('daily_limit')"

Fonctions disponibles

Hooks and actions

Les hooks réagissent aux événements et exécutent des actions. Exemple : à chaque facture créée, créer automatiquement un suivi dans votre plugin.

Exemple : créer un record à chaque facture

"hooks": {
  "on_invoice_created": {
    "event": "invoice.created",
    "conditions": [
      { "field": "status", "not_equals": 0 }
    ],
    "actions": [
      {
        "type": "create_record",
        "model": "invoice_tracking",
        "fields": {
          "invoice_id": "id",
          "invoice_number": "invoice_number",
          "amount": "total",
          "status": "0",
          "tracked_at": "NOW()"
        }
      }
    ]
  }
}

Opérateurs de condition disponibles

Liste complète — utilisable dans conditions (hooks) et dans les filter de widgets. Une valeur d'opérande peut être une constante ou une formule (ex. "SETTING('seuil')").

Exemple : mouvement de stock + ecriture comptable

"hooks": {
  "on_order_completed": {
    "event": "@order.updated",
    "conditions": [
      { "field": "status", "changed_to": 3 }
    ],
    "actions": [
      {
        "type": "stock_movement",
        "item": "item_id",
        "quantity_formula": "quantity",
        "direction": "out",
        "warehouse": "warehouse_id"
      },
      {
        "type": "journal_entry",
        "debit": "601",
        "credit": "401",
        "amount_formula": "total",
        "label_formula": "CONCAT('Plugin order #', number)",
        "date": "order_date"
      },
      {
        "type": "send_email",
        "to_formula": "LOOKUP(contacts, id = client_id, email)",
        "subject": "Votre commande est prête",
        "body": "Bonjour, votre commande a été traitée."
      }
    ]
  }
}

Exemple : webhook + appel API externe

"hooks": {
  "notify_external": {
    "event": "payment.received",
    "actions": [
      {
        "type": "webhook",
        "url": "https://mon-erp.com/webhooks/iberis",
        "event_name": "payment.received"
      },
      {
        "type": "api_call",
        "url": "https://api.mon-service.com/sync",
        "method": "POST",
        "headers": { "Authorization": "Bearer MY_TOKEN" },
        "body": { "reference": "payment_number", "amount": "total" },
        "response_mapping": { "external_id": "data.id" },
        "target_model": "sync_log"
      }
    ]
  }
}

Exemple : regrouper des enregistrements liés (bulk_create_from_related)

create_record agit sur l'enregistrement qui a déclenché le hook. bulk_create_from_related fait la même chose pour tout un ensemble : il cherche les lignes de source_model qui correspondent à match, puis crée une ligne de target_model par résultat trouvé.

// Reprend le model order / order_line de la section Master-detail :
// à la création d'un récap mensuel, rattacher les commandes du même
// client tombant dans la période.
"hooks": {
  "regenerer_lignes": {
    "event": "@monthly_recap.created",
    "actions": [
      {
        "type": "bulk_create_from_related",
        "source_model": "@order",
        "match": [
          { "field": "client_id", "equals": "client_id" },
          { "field": "date", "greater_or_equal": "period_start" },
          { "field": "date", "less_or_equal": "period_end" }
        ],
        "target_model": "recap_line",
        "fields": {
          "recap_id": "id",
          "order_id": "source.id",
          "amount": "source.total"
        }
      }
    ]
  }
}

Exemple : mettre à jour un autre enregistrement (update_record)

Modifie un enregistrement existant plutôt que d'en créer un — typiquement un record lié à celui qui a déclenché le hook.

"hooks": {
  "on_payment_confirmed": {
    "event": "@payment.updated",
    "conditions": [
      { "field": "status", "changed_to": 1 }
    ],
    "actions": [
      {
        "type": "update_record",
        "model": "invoice_tracking",
        "record_id": "LOOKUP(@invoice_tracking, payment_id = id, id)",
        "fields": {
          "status": "1",
          "paid_at": "NOW()"
        }
      }
    ]
  }
}

Événements disponibles

Pour les événements internes du plugin, préfixez avec @ : @model_name.created, @model_name.updated, @model_name.deleted

Notifications in-app et push

Envoyez des notifications aux utilisateurs depuis vos hooks. Les notifications apparaissent dans la cloche de l'interface, sur l'application mobile (push Firebase), et optionnellement par email.

Exemple : notification à l'approbation

"hooks": {
  "notify_on_approval": {
    "event": "@payment_request.updated",
    "conditions": [
      { "field": "status", "changed_to": 3 }
    ],
    "actions": [
      {
        "type": "send_notification",
        "recipients": "current_user",
        "title": { "fr": "Demande approuvée", "en": "Request approved" },
        "content_formula": "CONCAT('La demande #', number, ' a été approuvée.')",
        "link": {
          "route": "pluginPageRecord",
          "params": {
            "pluginSlug": "mon-plugin",
            "pageName": "request_form",
            "recordId": "hashed_id"
          }
        }
      }
    ]
  }
}

Destinataires

Exemple : notifier tous les managers

{
  "type": "send_notification",
  "recipients": "role",
  "role": "Manager",
  "title": { "fr": "Nouvelle demande de paiement" },
  "content_formula": "CONCAT('Demande #', number, ' - ', total, ' TND')",
  "email": true
}

Shortcodes

Injectez des données plugin dans les PDFs, emails et templates Iberis.

Exemples

// Nombre total de tâches
{{plugin:task-manager:COUNT(task)}}

// Somme des montants des tâches terminées
{{plugin:task-manager:SUM(task.amount)}}

// Champ custom sur une facture (via extensions)
{{plugin:task-manager:project_code}}

// Expression conditionnelle
{{plugin:task-manager:IF(COUNT(task) > 10, "Beaucoup de tâches", "Peu de tâches")}}

Entity extensions

Ajoutez des champs custom aux entités Iberis existantes. Les champs s'affichent automatiquement dans les formulaires de création/edition.

Exemple : ajouter des champs sur les factures et dépenses

"extensions": {
  "invoice": {
    "custom_fields": {
      "project_code": {
        "type": "string",
        "label": { "fr": "Code projet", "en": "Project code" }
      },
      "is_billable": {
        "type": "boolean",
        "label": { "fr": "Facturable", "en": "Billable" },
        "default": true
      },
      "priority": {
        "type": "select",
        "label": { "fr": "Priorite" },
        "options": [
          { "value": "low", "label": { "fr": "Basse", "en": "Low" } },
          { "value": "medium", "label": { "fr": "Moyenne", "en": "Medium" } },
          { "value": "high", "label": { "fr": "Haute", "en": "High" } }
        ]
      }
    }
  },
  "expense": {
    "custom_fields": {
      "department": {
        "type": "string",
        "label": { "fr": "Departement", "en": "Department" }
      },
      "approved_amount": {
        "type": "decimal",
        "label": { "fr": "Montant approuvé", "en": "Approved amount" }
      }
    }
  }
}

Entités extensibles

Dashboard widgets

Les widgets s'affichent en haut de la page liste de votre plugin. Ajoutez "dashboard": true sur un widget pour l'afficher aussi sur le tableau de bord principal de l'entreprise.

Exemple complet

"widgets": {
  "total": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "COUNT",
    "label": { "fr": "Total", "en": "Total" },
    "icon": "fas fa-list",
    "color": "#667eea",
    "dashboard": true
  },
  "completed": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "COUNT",
    "filter": { "status": 2 },
    "label": { "fr": "Terminées", "en": "Completed" },
    "icon": "fas fa-check",
    "color": "#10b981"
  },
  "total_amount": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "SUM",
    "field": "amount",
    "label": { "fr": "Montant total", "en": "Total amount" },
    "icon": "fas fa-coins",
    "color": "#f59e0b"
  },
  "by_status": {
    "type": "chart",
    "chart_type": "donut",
    "model": "task",
    "group_by": "status",
    "aggregate": "COUNT",
    "label": { "fr": "Répartition", "en": "Distribution" },
    "color": "#667eea"
  }
}

Types de graphiques supportés : bar, donut, pie. Agrégations disponibles (widgets stats_card et chart) : COUNT, SUM, AVG, MIN, MAX.

Tabs on existing pages

Ajoutez un onglet dans les pages de synthèse des clients, fournisseurs, articles, ou dans la sidebar des documents (factures, dépenses, etc.). L'onglet affiche les records de votre plugin liés à l'entité.

Exemple : onglet "Deals" sur la fiche client

Le foreign_key doit correspondre à un champ de type reference déclaré dans votre model. C'est ce champ qui fait le lien entre votre record plugin et l'entité Iberis.

// 1. Déclarer le model avec un champ reference vers contacts
"models": {
  "deal": {
    "fields": {
      "title": { "type": "string", "required": true, "label": { "fr": "Titre" } },
      "amount": { "type": "decimal", "label": { "fr": "Montant" } },
      "status": { "type": "integer", "default": 0 },
      "client_id": {
        "type": "reference",
        "references": "contacts",
        "label": { "fr": "Client", "en": "Client" }
      }
    },
    "statuses": {
      "0": { "fr": "Nouveau", "en": "New" },
      "1": { "fr": "En cours", "en": "In progress" },
      "2": { "fr": "Gagné", "en": "Won" }
    }
  }
},

// 2. Déclarer l'onglet qui utilise ce champ comme foreign_key
"tabs": {
  "contact": {
    "label": { "fr": "Deals liés", "en": "Related deals" },
    "model": "deal",
    "foreign_key": "client_id",
    "columns": ["_number", "title", "amount", "status"]
  }
}

Autre exemple : suivi sur les factures

"models": {
  "invoice_tracking": {
    "fields": {
      "invoice_id": { "type": "reference", "references": "invoices" },
      "status": { "type": "integer", "default": 0 },
      "tracked_at": { "type": "date" },
      "notes": { "type": "text" }
    }
  }
},
"tabs": {
  "invoice": {
    "label": { "fr": "Suivi", "en": "Tracking" },
    "model": "invoice_tracking",
    "foreign_key": "invoice_id",
    "columns": ["status", "tracked_at", "notes"]
  }
}

Entités supportées

Settings

Chaque entreprise peut configurer votre plugin via la page Paramètres. Les valeurs sont accessibles dans les hooks et formules.

Exemple

"settings": {
  "api_key": {
    "type": "string",
    "label": { "fr": "Clé API", "en": "API Key" },
    "help": { "fr": "Votre clé d'authentification externe", "en": "Your external auth key" },
    "default": ""
  },
  "mode": {
    "type": "select",
    "label": { "fr": "Mode" },
    "default": "production",
    "options": [
      { "value": "sandbox", "label": { "fr": "Test", "en": "Sandbox" } },
      { "value": "production", "label": { "fr": "Production" } }
    ]
  },
  "auto_sync": {
    "type": "boolean",
    "label": { "fr": "Synchronisation automatique", "en": "Auto sync" },
    "default": true
  },
  "daily_limit": {
    "type": "number",
    "label": { "fr": "Limite journalière", "en": "Daily limit" },
    "default": 100
  },
  "notes": {
    "type": "textarea",
    "label": { "fr": "Notes de configuration", "en": "Config notes" },
    "default": ""
  }
}

Lire un paramètre dans une formule ou une condition

Utilisez SETTING('cle') — la clé entre quotes, comme n'importe quel autre littéral texte du langage de formules. Tant que l'entreprise n'a pas explicitement enregistré de valeur, le default déclaré ci-dessus est utilisé.

// Champ computed
"formula": "IF(quantity > SETTING('daily_limit'), 'Dépassement', 'OK')"

// Condition de hook — le seuil vient du paramètre, pas d'une valeur figée
"conditions": [{ "field": "amount", "greater_than": "SETTING('daily_limit')" }]

Actions on documents

Ajoutez des boutons dans le menu déroulant "Action" des documents Iberis (factures, dépenses, devis, etc.) et dans la page formulaire. Trois types d'actions sont disponibles :

Exemple : bouton "Créer une demande de paiement" sur les dépenses

// 1. Le model avec une référence vers expenses
"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "expense_id": { "type": "reference", "references": "expenses" },
      "amount": { "type": "decimal" },
      "status": { "type": "integer", "default": 0 }
    }
  }
},

// 2. La page formulaire
"pages": {
  "request_form": { "type": "form", "model": "payment_request" }
},

// 3. L'action qui apparaît dans le dropdown de chaque dépense
"actions": {
  "create_payment_request": {
    "entity_type": "expense",
    "label": { "fr": "Créer demande de paiement", "en": "Create payment request" },
    "icon": "fas fa-file-invoice",
    "color": "primary",
    "type": "create_record",
    "target_page": "request_form",
    "prefill": {
      "expense_id": "_id",
      "amount": "total"
    }
  }
}

Exemple : générer un PDF depuis une facture

"actions": {
  "generate_tracking_pdf": {
    "entity_type": "invoice",
    "label": { "fr": "Fiche de suivi PDF", "en": "Tracking sheet PDF" },
    "icon": "fas fa-file-pdf",
    "color": "danger",
    "type": "generate_pdf",
    "pdf_template": "tracking_sheet"
  }
}

Exemple : naviguer vers une page du plugin

"actions": {
  "view_deals": {
    "entity_type": "invoice",
    "label": { "fr": "Voir les deals liés", "en": "View linked deals" },
    "icon": "fas fa-handshake",
    "color": "info",
    "type": "navigate",
    "target_page": "deals_list"
  }
}

Entités supportées

contact n'est pas dans cette liste : rien n'affiche le menu "Action" sur les fiches client/fournisseur, contrairement aux onglets (section précédente) qui eux le supportent. Une action déclarée avec "entity_type": "contact" est acceptée sans erreur mais n'apparaît nulle part.

Couleurs disponibles

Action guards

Guards allow your extension to block Iberis actions if certain conditions are not met. For example, preventing a payment if no approved payment request exists.

Exemple : bloquer un paiement sans demande approuvée

"guards": {
  "require_payment_request": {
    "event": "payment.before_create",
    "conditions": [],
    "check": {
      "type": "require_record",
      "model": "payment_request",
      "where": {
        "expense_id": "hashed_expense_id"
      },
      "status": 3
    },
    "message": {
      "fr": "Un paiement ne peut être effectué sans demande de paiement approuvée.",
      "en": "Payment cannot be made without an approved payment request."
    }
  }
}

Exemple : bloquer la suppression si champ non vide

"guards": {
  "prevent_delete_if_linked": {
    "event": "invoice.before_delete",
    "check": {
      "type": "require_field",
      "field": "external_ref"
    },
    "message": {
      "fr": "Cette facture est liée à un système externe et ne peut pas être supprimée."
    }
  }
}

Exemple : bloquer la validation avec expression

"guards": {
  "min_amount": {
    "event": "expense.before_validate",
    "check": {
      "type": "expression",
      "expression": "total >= 10"
    },
    "message": {
      "fr": "Le montant minimum pour valider une dépense est de 10 TND."
    }
  }
}

Événements guard disponibles

Liste exhaustive — contrairement aux mutators et aux hooks d'événements, les guards ne sont câblés que sur ces 7 points précis. Un guard déclaré sur un autre événement (ex. order.before_validate) est accepté à la soumission mais ne se déclenchera jamais, sans erreur.

PDF templates

Generate custom PDF documents from your model data. Use HTML/CSS with variables and loops to create professional templates.

Exemple : demande de paiement PDF

"pdf_templates": {
  "demande_paiement": {
    "model": "payment_request",
    "format": "A4",
    "orientation": "P",
    "margin_top": 15,
    "margin_bottom": 15,
    "margin_left": 10,
    "margin_right": 10,
    "data": {
      "lines": {
        "model": "@request_line",
        "type": "list",
        "where": { "request_id": "id" },
        "order_by": "created_at"
      },
      "bank": {
        "model": "company_banks",
        "type": "single",
        "where": { "id": "bank_id" }
      }
    },
    "css": "body { font-family: Arial, sans-serif; font-size: 12px; } .header { text-align: center; margin-bottom: 20px; } .title { font-size: 18px; font-weight: bold; } table { width: 100%; border-collapse: collapse; margin: 15px 0; } th, td { border: 1px solid #ddd; padding: 8px; text-align: left; } th { background: #f5f5f5; } .signatures { display: flex; justify-content: space-between; margin-top: 40px; } .sig-block { text-align: center; width: 30%; } .sig-line { border-top: 1px solid #333; margin-top: 50px; padding-top: 5px; }",
    "html": "<div class='header'><div class='title'>DEMANDE DE PAIEMENT</div><div>N: {{number}} - Date: {{date}}</div><div>{{company.title}}</div></div><table><tr><th>#</th><th>Description</th><th>Montant</th></tr>{{#each related.lines}}<tr><td>{{_index}}</td><td>{{item.description}}</td><td>{{item.amount}} TND</td></tr>{{/each}}</table><p><strong>Total: {{total}} TND</strong></p><p>Banque: {{related.bank.title}} - RIB: {{related.bank.rib}}</p><div class='signatures'><div class='sig-block'><div class='sig-line'>Charge des moyens généraux</div></div><div class='sig-block'><div class='sig-line'>Direction Générale</div></div><div class='sig-block'><div class='sig-line'>Direction Financière</div></div></div>"
  }
}

Variables simples

Formatage

// Formater un nombre (3 décimales par défaut)
{{number:amount:2}}         → 1 500.00
{{number:item.price:3}}     → 25.500

// Formater une date (format PHP)
{{date:created_at:d/m/Y}}  → 19/03/2026
{{date:item.due:Y-m-d}}    → 2026-03-19

// Somme d'un champ dans une collection
{{sum:related.lines.amount:2}}   → 4 250.00

// Nombre d'éléments
{{count:related.lines}}          → 5

// Image dynamique (logo, signature)
{{image:company.logo:200}}       → <img> 200px de large
{{image:company.stamp:150:150}}  → <img> 150x150px

Conditions

// Afficher un bloc si la condition est vraie
{{#if status == 3}}
  <div class="badge-success">APPROUVÉ</div>
{{#else}}
  <div class="badge-warning">EN ATTENTE</div>
{{/if}}

// Masquer si la condition est vraie
{{#unless total == 0}}
  <p>Total: {{number:total:3}} TND</p>
{{/unless}}

// Conditions dans les boucles
{{#each related.lines}}
  <tr>
    <td>{{item.description}}</td>
    <td>{{number:item.amount:2}}</td>
    {{#if item.status == 1}}
      <td class="text-success">Payé</td>
    {{#else}}
      <td class="text-danger">Impayé</td>
    {{/if}}
  </tr>
{{/each}}

Boucles

{{#each related.lines}}
  <tr>
    <td>{{_index}}</td>
    <td>{{item.description}}</td>
    <td>{{number:item.quantity:0}}</td>
    <td>{{number:item.unit_price:3}}</td>
    <td>{{number:item.line_total:3}}</td>
  </tr>
{{/each}}

Opérateurs de comparaison

API

// Générer le PDF (retourne le chemin du fichier)
POST /api/private/company/{companyId}/plugins/{slug}/pdf/{templateName}/{recordId}

// Télécharger directement le PDF
GET /api/private/company/{companyId}/plugins/{slug}/pdf/{templateName}/{recordId}/download

Modèles personnalisés (documents Iberis)

À ne pas confondre avec pdf_templates (qui sert à générer des PDF à partir de vos models de plugin), la section custom_templates permet d'installer des modèles HTML/CSS qui s'ajoutent au sélecteur de modèles natif d'Iberis pour les documents du cœur Iberis (factures, devis, livraisons, etc.). C'est le moyen idéal pour vendre des packs de designs premium.

Cycle de vie

Types de documents supportés

La valeur de document_type doit être l'une des suivantes (chaîne ou tableau) :

Structure du manifest

{
  "plugin": {
    "id": "premium-invoice-templates",
    "name": { "fr": "Modèles de Factures Premium" },
    "description": { "fr": "3 modèles de factures conçus professionnellement." },
    "version": "1.0.0",
    "category": "finance",
    "module": "finance"
  },
  "custom_templates": [
    {
      "name": "Tribune",
      "document_type": ["invoice", "estimate", "expense"],
      "css_content": "body { font-family: Helvetica; ... }",
      "html_content": "<div class='wrap'>...</div>",
      "preview_image": null
    },
    {
      "name": "Boutique",
      "document_type": "invoice",
      "css_content": "body { font-family: Arial; ... }",
      "html_content": "<div class='bar'>...</div>"
    }
  ]
}

Champs d'une entrée

Variables disponibles dans le HTML/CSS

Le moteur de rendu utilise un remplacement {{variable.path}} simple (pas de Handlebars complet — pas de {{#each}} ni de {{#if}} dans les custom_templates). Les tableaux dynamiques sont insérés via des macros spéciales.

// Entreprise
{{company.name}}             {{company.address}}        {{company.phone}}
{{company.email}}            {{company.fiscal_id}}      {{company.website}}
{{company.city}}             {{company.postal_code}}    {{company.country}}
{{company.logo}}             // se rend en <img> auto-dimensionné
{{company.stamp}}            // se rend en <img> auto-dimensionné
{{company.pdf_header}}       // en-tête répété sur chaque page (mPDF)
{{company.pdf_footer}}       // pied de page répété sur chaque page (mPDF)

// Document (facture, devis, etc.)
{{document.number}}          {{document.date}}          {{document.due_date}}
{{document.object}}          {{document.reference}}     {{document.currency}}
{{document.subtotal}}        {{document.tax_total}}     {{document.discount}}
{{document.total}}           {{document.paid}}          {{document.balance}}
{{document.credits}}         {{document.withholding}}   {{document.total_words}}
{{document.notes}}           {{document.conditions}}

// Contact (client / fournisseur)
{{contact.name}}             {{contact.organisation}}   {{contact.address}}
{{contact.phone}}            {{contact.email}}          {{contact.fiscal_id}}
{{contact.personal_id}}      {{contact.city}}           {{contact.postal_code}}
{{contact.country}}
{{contact.billing_address}}  {{contact.billing_city}}   {{contact.billing_zip}}
{{contact.delivery_address}} {{contact.delivery_city}}  {{contact.delivery_zip}}

// Banque (depuis la facture)
{{bank.name}}                {{bank.iban}}              {{bank.bic}}
{{bank.rib}}

// Date
{{date.today}}               {{date.year}}

// Tableaux dynamiques (rendus en <table> complet)
{{items.table}}              // lignes du document
{{taxes.table}}              // récapitulatif TVA
{{additional_inputs.table}}  // frais/remises additionnels : libellé et montant,
                             // sans en-tête ni bordure. À placer dans le bloc
                             // des totaux, comme les lignes sous-total et TVA.
{{payment.table}}            // historique des paiements
{{inventory.table}}          // mouvements d'inventaire
{{journal_entry.table}}      // écritures comptables
{{disbursement.table}}       // détails d'un décaissement

// Champs individuels du document courant (ne remplacent le tableau
// ci-dessus que si vous voulez un seul champ isolé, pas la liste complète ;
// chaque groupe n'a de valeur que sur le type de document correspondant :
// paymentSale/paymentPurchase pour payment.*, inventory pour inventory.*,
// entry pour journal_entry.*)
{{payment.method}}           {{payment.bank_fees}}      {{payment.amount}}
{{payment.reference}}
{{inventory.user}}           {{inventory.warehouse}}
{{journal_entry.number}}     {{journal_entry.total}}
{{journal_entry.debit_total}} {{journal_entry.credit_total}}

Masquage automatique des lignes vides

Le moteur de rendu masque automatiquement les lignes ou éléments dont la seule valeur dynamique est vide — aucun besoin de CSS :empty ou de logique conditionnelle. Écrivez simplement votre libellé et sa variable dans la même structure et le moteur fait le ménage.

Exemple complet d'une entrée

Cet exemple utilise un seul document_type en tableau pour cibler facture, devis et facture fournisseur en une seule entrée. Notez l'usage de vraies balises <table> avec des attributs width HTML — mPDF rend les tables natives bien plus fiablement que les divs avec display:table-cell. Aucun CSS :empty n'est nécessaire : les lignes de totaux dont la variable est vide (remise, retenue, crédits…) disparaissent d'elles-mêmes grâce au masquage automatique décrit plus haut.

{
  "name": "Tribune",
  "document_type": ["invoice", "estimate", "expense"],
  "css_content": "body{font-family:Helvetica,Arial,sans-serif;font-size:10pt;color:#0a0a0a} .head{background:#0a0a0a;color:#fff;padding:24px} .num{font-size:32pt;font-weight:bold;letter-spacing:-1px} .row td{padding:8px 0;border-bottom:1px solid #eee} .row .l{color:#737373;text-transform:uppercase;font-size:8pt;letter-spacing:1px;padding-right:14px} .row .v{text-align:right;font-weight:600} .grand td{border-top:2px solid #0a0a0a;font-size:14pt;font-weight:bold}",
  "html_content": "<table width='100%' cellpadding='0' cellspacing='0'><tr><td class='head'><strong>{{company.name}}</strong> &middot; MF {{company.fiscal_id}}<br><span class='num'>{{document.number}}</span></td></tr></table><table width='100%' cellpadding='0' cellspacing='0'><tr><td>Émise à</td><td>{{contact.name}}</td></tr><tr><td>Organisation</td><td>{{contact.organisation}}</td></tr><tr><td>Adresse</td><td>{{contact.address}}</td></tr><tr><td>Date</td><td>{{document.date}}</td></tr><tr><td>Échéance</td><td>{{document.due_date}}</td></tr></table>{{items.table}}{{taxes.table}}<table width='100%' cellpadding='0' cellspacing='0'><tr><td width='50%'></td><td width='50%'><table width='100%' cellpadding='0' cellspacing='0'><tr class='row'><td class='l'>Sous-total HT</td><td class='v'>{{document.subtotal}}</td></tr><tr class='row'><td class='l'>Remise</td><td class='v'>{{document.discount}}</td></tr><tr class='row'><td class='l'>TVA</td><td class='v'>{{document.tax_total}}</td></tr><tr class='row'><td class='l'>Retenue à la source</td><td class='v'>{{document.withholding}}</td></tr><tr class='row'><td class='l'>Avoirs appliqués</td><td class='v'>{{document.credits}}</td></tr><tr class='row grand'><td class='l'>Total TTC</td><td class='v'>{{document.total}}</td></tr></table></td></tr></table><p><em>{{document.total_words}}</em></p><table width='100%' cellpadding='0' cellspacing='0'><tr><td>Banque</td><td>{{bank.name}}</td></tr><tr><td>RIB</td><td>{{bank.rib}}</td></tr></table>{{company.stamp}}"
}

Validation à la soumission

Approval workflows

Add a validation workflow to your models. Define approval steps with specific roles or users. Two modes are available: sequential (strict order) and free (single approval sufficient).

Exemple : circuit DG → DFC

"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "total": { "type": "decimal" },
      "status": { "type": "integer", "default": 0 },
      "expense_id": { "type": "reference", "references": "expenses" }
    },
    "statuses": {
      "0": { "fr": "Brouillon", "en": "Draft" },
      "1": { "fr": "Soumis", "en": "Submitted" },
      "2": { "fr": "Approuvé DG", "en": "CEO Approved" },
      "3": { "fr": "Valide DFC", "en": "CFO Validated" },
      "4": { "fr": "Rejeté", "en": "Rejected" }
    },
    "approval_workflow": {
      "approval_mode": "sequential",
      "steps": [
        {
          "label": { "fr": "Validation Direction Générale", "en": "CEO Approval" },
          "role": "manager"
        },
        {
          "label": { "fr": "Validation Direction Financière", "en": "CFO Approval" },
          "role": "accountant"
        }
      ],
      "on_approve": { "set_status": 3 },
      "on_reject": { "set_status": 4 }
    }
  }
}

Modes d'approbation

API

// Consulter l'état du workflow
GET /api/private/company/{companyId}/plugins/{slug}/{model}/{recordId}/approval

// Approuver (status=1) ou rejeter (status=2) une étape
POST /api/private/company/{companyId}/plugins/{slug}/{model}/{recordId}/approval
Body: { "step_index": 0, "status": 1, "comment": "OK" }

Mutators (data transformation)

Les mutators permettent de modifier automatiquement les données d'un document Iberis avant sa sauvegarde. Contrairement aux guards qui bloquent, les mutators transforment.

Exemple : forcer une valeur par défaut

"mutators": {
  "default_payment_terms": {
    "event": "invoice.before_save",
    "default": {
      "conditions": "Paiement à 30 jours"
    }
  }
}

Exemple : calculer et forcer une valeur

"mutators": {
  "auto_reference": {
    "event": "expense.before_save",
    "conditions": [
      { "field": "status", "equals": 0 }
    ],
    "set": {
      "reference": "CONCAT('REF-', order_number)"
    }
  }
}

Événements disponibles

Dashboard pages

Créez des pages qui affichent des widgets et des tableaux de données de plusieurs models en une seule vue. Idéal pour les tableaux de bord, les rapports, ou les vues d'ensemble.

Exemple

"pages": {
  "crm_dashboard": {
    "type": "dashboard",
    "title": { "fr": "Tableau de bord CRM", "en": "CRM Dashboard" },
    "widgets": ["total_deals", "won_deals", "deals_by_status"],
    "sections": [
      {
        "model": "deal",
        "title": { "fr": "Deals récents", "en": "Recent deals" },
        "columns": ["_number", "title", "amount", "status"],
        "limit": 5,
        "filter": {}
      },
      {
        "model": "activity",
        "title": { "fr": "Dernières activités", "en": "Latest activities" },
        "columns": ["_number", "type", "description", "date"],
        "limit": 10
      }
    ]
  }
}

Structure

Import / export CSV

Export et import CSV sont désactivés par défaut. Chaque modèle qui doit les proposer le déclare explicitement :

{
  "models": {
    "reservation": {
      "export": true,
      "import": true,
      "fields": { ... }
    }
  }
}

Sans export/import sur le modèle, le bouton correspondant n'apparaît pas sur la page liste et l'endpoint renvoie 404 — pas 403, la fonctionnalité n'existe simplement pas pour ce modèle.

Une fois activés, ils utilisent par défaut canRead (export) / canCreate (import). Pour exiger une permission dédiée à la place, déclarez canExport/canImport dans permissions :

"permissions": ["canRead", "canCreate", "canUpdate", "canDelete", "canExport", "canImport"]

Export

Import

API

// Export CSV
GET /api/private/company/{companyId}/plugins/{slug}/{model}/export
→ Retourne un fichier CSV en téléchargement

// Import CSV
POST /api/private/company/{companyId}/plugins/{slug}/{model}/import
Body: FormData avec champ "file" (CSV)
→ Retourne: { imported: 15, errors: ["Line 3: column count mismatch"] }

Master-detail relations

Créez des relations parent-enfant entre vos models. Par exemple, une commande avec des lignes de commande, ou une demande de paiement avec des factures liées. Les lignes enfant sont éditables directement dans le formulaire du parent.

Exemple : commande avec lignes

"models": {
  "order": {
    "numbering": { "prefix": "CMD", "pattern": "{prefix}-{YYYY}-{sequence}" },
    "fields": {
      "title": { "type": "string", "required": true, "label": { "fr": "Titre" } },
      "client_id": { "type": "reference", "references": "contacts", "label": { "fr": "Client" } },
      "date": { "type": "date", "label": { "fr": "Date" } },
      "status": { "type": "integer", "default": 0 },
      "total": {
        "type": "computed",
        "formula": "SUM(order_line.quantity * order_line.unit_price)",
        "label": { "fr": "Total" }
      }
    },
    "statuses": {
      "0": { "fr": "Brouillon" },
      "1": { "fr": "Confirmée" },
      "2": { "fr": "Livrée" }
    }
  },
  "order_line": {
    "label": { "fr": "Lignes de commande", "en": "Order lines" },
    "parent": {
      "model": "order",
      "foreign_key": "order_id"
    },
    "fields": {
      "order_id": { "type": "reference", "references": "@order" },
      "description": { "type": "string", "required": true, "label": { "fr": "Description" } },
      "quantity": { "type": "integer", "default": 1, "label": { "fr": "Quantité" } },
      "unit_price": { "type": "decimal", "label": { "fr": "Prix unitaire" } },
      "line_total": {
        "type": "computed",
        "formula": "quantity * unit_price",
        "label": { "fr": "Total ligne" }
      }
    }
  }
}

Comportement

Déclaration

Autre exemple : demande de paiement avec factures liées

"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "total": { "type": "computed", "formula": "SUM(request_line.amount)" },
      "status": { "type": "integer", "default": 0 }
    }
  },
  "request_line": {
    "label": { "fr": "Factures liées", "en": "Linked invoices" },
    "parent": { "model": "payment_request", "foreign_key": "request_id" },
    "fields": {
      "request_id": { "type": "reference", "references": "@payment_request" },
      "expense_id": { "type": "reference", "references": "expenses", "label": { "fr": "Facture" } },
      "amount": { "type": "decimal", "label": { "fr": "Montant" } },
      "description": { "type": "string", "label": { "fr": "Description" } }
    }
  }
}

Permissions by role

Contrôlez l'accès aux fonctionnalités de votre plugin par rôle d'utilisateur. Par défaut, 4 permissions sont créées automatiquement : canRead, canCreate, canUpdate, canDelete.

Permissions par défaut

Si vous ne déclarez pas de section permissions, les 4 permissions standard sont utilisées. Elles sont automatiquement ajoutées au rôle "Propriétaire" lors de l'installation.

// Implicite (pas besoin de le déclarer) :
"permissions": ["canRead", "canCreate", "canUpdate", "canDelete"]

// Les clés générées seront :
// plugin:mon-plugin:canRead
// plugin:mon-plugin:canCreate
// plugin:mon-plugin:canUpdate
// plugin:mon-plugin:canDelete

Permissions personnalisées

"permissions": [
  "canRead",
  "canCreate",
  "canUpdate",
  "canDelete",
  "canExport",
  "canApprove",
  "canManageSettings"
]

Comportement

Utiliser dans les menus

"menus": [{
  "section": {
    "title": { "fr": "Mon plugin" },
    "items": [
      {
        "label": { "fr": "Liste" },
        "page": "list_page",
        "permission": "canRead"
      },
      {
        "label": { "fr": "Paramètres" },
        "page": "settings_page",
        "permission": "canManageSettings"
      }
    ]
  }
}]

Si permission n'est pas déclaré sur un item de menu, canRead est utilisé par défaut. Pour un item qui pointe vers une page liée à un modèle (list/form), voir ci-dessous : la permission du modèle prend le pas sur celle déclarée ici.

Restreindre un modèle à une permission dédiée

Par défaut, un modèle est couvert par les permissions standards du plugin (canRead/canCreate/canUpdate/canDelete), au même titre que tous les autres modèles. Si un modèle en particulier doit être verrouillé à part — un écran plus sensible que le reste du plugin — déclarez permission directement sur ce modèle :

{
  "models": {
    "statement": {
      "permission": "canValidateStatement",
      "fields": { ... }
    }
  },
  "permissions": ["canRead", "canCreate", "canUpdate", "canDelete", "canValidateStatement"]
}

Une fois déclarée, cette permission remplace canRead/canCreate/canUpdate/canDelete pour toutes les actions sur ce modèle — lecture, création, modification, suppression, export, import, et les étapes d'approbation le cas échéant. Elle ne s'applique qu'à ce modèle : les autres modèles du même plugin continuent d'utiliser les permissions standards, indépendamment. Ce n'est pas plus fin qu'une permission par modèle — il n'y a pas de permission séparée par action au sein d'un même modèle.

Un item de menu qui pointe vers une page liée à ce modèle n'a pas besoin de déclarer sa propre permission : elle est automatiquement dérivée de celle du modèle, pour que le menu ne puisse jamais afficher — ou masquer — une entrée en désaccord avec ce que l'API autorise réellement.

Limits and security

Sécurité