Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Personnalisations

Scripts Client

Créer un script client qui modifie le comportement d'un formulaire ou d'une liste, avec un exemple qui exige une pièce jointe avant l'enregistrement.

Scripts Client

Un script client est du code JavaScript exécuté dans le navigateur. Il modifie le comportement d'un formulaire ou d'une liste : afficher un message, masquer un champ, bloquer un enregistrement. Pour du code exécuté sur le serveur, utilisez un script Python.

Prérequis

Vous avez le rôle Responsable système.

Créer un script client

  1. Ouvrez la recherche (Ctrl+K) et saisissez « Script client ».
  2. Cliquez sur Créer un·e Script client.
  3. Sélectionnez le Type de document concerné.
  4. Dans Appliquer à, choisissez Formulaire ou Liste.
  5. Saisissez le code dans le champ Script.
  6. Cochez Activé et enregistrez.
  7. Rechargez la page du formulaire pour charger le script.

Un script de formulaire utilise frappe.ui.form.on("<Type de document>", { événement(frm) { … } }). Les événements courants sont refresh, validate, before_save, before_submit, after_delete et le nom d'un champ (déclenché à chaque changement de valeur).

Exemples

Vérifier qu'une pièce jointe a bien été ajoutée à un document de type Note de frais avant son enregistrement ou sa validation

frappe.ui.form.on('Expense Claim', {
  before_save(frm) {
    validate_attachments(frm)
  },

  before_submit(frm) {
    validate_attachments(frm)
  }
})

const validate_attachments = (frm) => {
  // On vérifie que le document a déjà été enregistré, car l'ajout d'une pièce jointe n'est possible qu'après le premier enregistrement
  // On vérifie également si une pièce jointe a déjà été ajoutée au document
  if (!frm.is_new() && !frm.attachments.get_attachments().length) {
    frappe.show_alert({
        message:"Veuillez ajouter des justificatifs pour votre note de frais",
        indicator: "orange"
    })

    // Variante: On peut également afficher un popup au lieu d'une alerte
    // Dans ce cas remplacez frappe.show_alert... par le code ci-dessous
    /*
    const dialog = new frappe.ui.Dialog({
        title: "Justificatifs manquants",
        minimizable: false,
        size: 'large'
    });
    dialog.msg_area = $('<div class="msgprint">').appendTo(dialog.body);
    const msg = "Veuillez ajouter des justificatifs pour votre note de frais";
    dialog.msg_area.append(msg);
    dialog.show()
    */


   // frappe.validated permet d'indiquer au framework que la validation a échoué. Le document ne pourra pas être enregistré
    frappe.validated = false;
  };
}

Choisir la page affichée après une suppression

L'événement after_delete se déclenche quand un document vient d'être supprimé depuis son formulaire. Il se déclenche aussi après la suppression d'un document avec ses documents liés (fenêtre Supprimer tous les documents), si celle-ci est exécutée immédiatement. Il ne se déclenche pas quand la suppression est confiée à une tâche de fond.

Sans script, Dokos revient à la page précédente du navigateur. Si votre gestionnaire after_delete change la route, Dokos ne revient pas en arrière : la page choisie par votre script reste affichée. Dokos compare l'adresse de la page avant et après l'exécution des gestionnaires de l'événement.

Exemple fictif — Maison Verte SARL Le type de document personnalisé « Contrat Client » est toujours ouvert depuis un lien reçu par email, sans page précédente utile. L'administrateur veut afficher la liste après chaque suppression :

frappe.ui.form.on("Contrat Client", {
  after_delete(frm) {
    // Remplace l'entrée d'historique du document supprimé par la liste
    frappe.route_flags.replace_route = true;
    frappe.set_route("List", "Contrat Client");
  }
});

Après la suppression d'un contrat, la liste Contrat Client s'affiche au lieu d'un retour à la page précédente du navigateur.

Le formulaire Format d'impression utilise cet événement : voir Supprimer un format d'impression.