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 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;
  };
}

Remplacer la confirmation d'annulation

Lorsque vous annulez un document validé, Dokos demande une confirmation générique (« Permanently Cancel … ? »). Un script de formulaire peut la remplacer par son propre avertissement. Définissez pour cela la propriété frm.cancel_warning avec un objet :

La fenêtre a pour titre Avertissement.

Comportement :

• Si frm.cancel_warning n'est pas défini, la confirmation générique habituelle s'affiche.
• Si vous cliquez sur le bouton de confirmation, l'annulation se poursuit sans afficher la confirmation générique. Les événements before_cancel et after_cancel du formulaire sont toujours déclenchés.
• Si vous refusez ou fermez la fenêtre, le document n'est pas annulé et le bouton d'annulation redevient utilisable.
• Si le document a des documents validés liés à annuler, Dokos affiche d'abord sa fenêtre d'annulation groupée, comme d'habitude. Cette vérification a lieu après votre confirmation.

Le formulaire d'un type de document est réutilisé d'un document à l'autre. Définissez donc la propriété dans l'événement refresh, et remettez-la à null quand l'avertissement ne s'applique pas.

Exemple fictif — Maison Verte SARL Une facture de vente envoyée au client ne doit être annulée qu'après vérification de l'avoir à émettre. Le script ci-dessous remplace la confirmation générique par un message adapté, avec des boutons Annuler la facture et Conserver la facture.

frappe.ui.form.on('Sales Invoice', {
  refresh(frm) {
    if (frm.doc.docstatus === 1) {
      frm.cancel_warning = {
        message: "Cette facture a été envoyée au client. Vérifiez qu'un avoir n'est pas plus adapté avant de l'annuler.",
        primary_label: "Annuler la facture",
        secondary_label: "Conserver la facture"
      }
    } else {
      frm.cancel_warning = null
    }
  }
})