`$script.call`¶

Description¶

Évalue un script externe et retourne un map contenant les objets (variables, fonctions, etc.) exportés par le script.

Syntaxe¶

$script.call( name [ , parameters [ , options ] ] )

Paramètres¶

name string

Nom du script à exécuter. Le nom peut être passé avec ou sans l'extension.

Si le nom de fichier commence par /, il est traité de comme un chemin absolu par rapport au dossier de scripts. Dans le cas contraire, il est traité de façon relative au dossier du script courant.

Ainsi, si le script courant est à la racine du dossier de scripts et souhaite appeler un script foo.ewts présent dans un sous-dossier subdir, alors il faudra noter subdir/foo (ou éventuellement /subdir/foo), comme cela se fait pour l'instruction import.

À l'inverse, si un script présent dans un sous-dossier souhaite appeler un script bar.ewts présent au niveau supérieur, il faudra noter soit ../bar ou /bar.

Il n'est pas possible d'exécuter un script présent en-dehors du dossier de scripts de l'application ou de ses sous-dossiers.

parameters any

Paramètres à passer au script. Habituellement on passe les paramètres sous la forme d'un map, mais en réalité n'importe quel type d'objet est autorisé. L'objet passé via parameters sera disponible via la la variable $$ dans le script appelé.

options map

Option d'exécution du script. Les options supportées sont:

context string / map

Contexte sur lequel évaluer le script. Si défini, le contexte doit être passé sous forme de string ou de map.

Si non spécifié, le script est évalué dans le contexte courant.

Le contexte courant est rétabli après l'exécution du script.

Attention, il y a une différence entre le fait de ne pas spécifier le contexte et le fait de spécifier un contexte null ou vide. Comme indiqué ci-dessus, le moteur se rabat sur le contexte courant lorsque la propriété n'est pas spécifiée. Par contre, si elle est définie à une valeur null ou vide (string vide ou map sans modelName) cela signifie que l'on souhaite expressément exécuter le script en-dehors de tout contexte, ou dit autrement, sur un contexte "hors dossier".

L'exemple n°3 ci-dessous illustre ce comportement.

async boolean

Valeur true/false indiquant si on souhaite exécuter le script de manière asynchrone. La valeur par défaut est false.

Lorsqu'un script est exécuté de manière asynchrone, la méthode retourne l'identifiant de thread. Celui-ci peut être passé à la méthode $script.getStatus pour obtenir un état de fonctionnement du script.

Le mode asynchrone est décrit dans le chapitre Exécution asynchrone de la doc de référence.

onprogress function

Fonction de callback à invoquer lorsque le script annonce une progression et lorsque le traitement est terminé. Le prototype de la fonction de callback doit être function(status) où status va recevoir un map indiquant l'état d'avancement au moyen des propriétés loaded, total, progress et target.

Voir également $script.setProgress.

oncomplete function

Fonction de callback invoquée lorsque l'exécution du script se termine. La fonction de callback doit avoir le prototype suivant: function(result) où result contient le résultat standard d'exécution du script (valeur équivalente au return de la fonction $script.call)

exceptionBehaviour string

Valeur indiquant comment la méthode doit traiter une exception non prise en charge par le script invoqué. La propriété peut prendre l'une des trois valeurs suivantes :

propagate: L'exception générée par le script invoqué et non traitée est propagée au code appelant. Cela signifie que si l'appel
$script.call est réalisé à l'intérieur d'un bloc try / catch, l'exception générée au sein du script invoqué peut être interceptée par le catch du script courant.
local: L'exception n'est pas propagée et il est attendu qu'elle soit traitée en interne dans le script invoqué. L'exécution du script parent continue même si une exception non traitée est déclenchée dans le script invoqué. L'exemple 4 ci-dessous illustre ce scenario.
default: Le mode default est analogue à propagate, si ce n'est qu'une ligne d'erreur est affichée dans le log pour signaler l'erreur.

En mode synchrone, la valeur par défaut est default. En mode asynchrone, la valeur par défaut est local.

Retour¶

Retourne un objet de type EwtTypeMap contenant les différents objets exportés par le script.

Exemple¶

1. Exemple de base¶

$script.call("toolboxVendeur", { action : "recherche-doublons" });

2. Fonction de callback¶

Exemple d'appel synchrone avec fonction de callback pour afficher l'avancement. Dans l'exemple suivant, le script s'appelle sample.ewts et il s'appelle lui-même pour déclencher le test.

if ($$.test == null) {
    $script.call("sample", { test: 1 }, {
        onprogress: function(x) {
            $logger.info("progress: ${x}");
        },
        oncomplete: function(x) {
            $logger.warn("C'est terminé !");
            $logger.warn(x);
        }
    });
}
else {
    for (var i = 0; i < 100; i += 5) {
        $script.setProgress(i / 100);
        $script.sleep(100);
    }
    $script.setProgress(1);

    export var res = "success";
}

Le script ci-dessus génère les traces suivantes:

progress: {"loaded": 0.0, "total": 1.0, "progress": 0.0, "target": sample}
progress: {"loaded": 0.05, "total": 1.0, "progress": 0.05, "target": sample}
progress: {"loaded": 0.1, "total": 1.0, "progress": 0.1, "target": sample}
progress: {"loaded": 0.15, "total": 1.0, "progress": 0.15, "target": sample}
progress: {"loaded": 0.2, "total": 1.0, "progress": 0.2, "target": sample}
progress: {"loaded": 0.25, "total": 1.0, "progress": 0.25, "target": sample}
progress: {"loaded": 0.3, "total": 1.0, "progress": 0.3, "target": sample}
progress: {"loaded": 0.35, "total": 1.0, "progress": 0.35, "target": sample}
progress: {"loaded": 0.4, "total": 1.0, "progress": 0.4, "target": sample}
progress: {"loaded": 0.45, "total": 1.0, "progress": 0.45, "target": sample}
progress: {"loaded": 0.5, "total": 1.0, "progress": 0.5, "target": sample}
progress: {"loaded": 0.55, "total": 1.0, "progress": 0.55, "target": sample}
progress: {"loaded": 0.6, "total": 1.0, "progress": 0.6, "target": sample}
progress: {"loaded": 0.65, "total": 1.0, "progress": 0.65, "target": sample}
progress: {"loaded": 0.7, "total": 1.0, "progress": 0.7, "target": sample}
progress: {"loaded": 0.75, "total": 1.0, "progress": 0.75, "target": sample}
progress: {"loaded": 0.8, "total": 1.0, "progress": 0.8, "target": sample}
progress: {"loaded": 0.85, "total": 1.0, "progress": 0.85, "target": sample}
progress: {"loaded": 0.9, "total": 1.0, "progress": 0.9, "target": sample}
progress: {"loaded": 0.95, "total": 1.0, "progress": 0.95, "target": sample}
progress: {"loaded": 1.0, "total": 1.0, "progress": 1.0, "target": sample}
C'est terminé !
{"res": success}

3. Invalidation de contexte¶

Cet exemple cherche à montrer le comportement de la méthode en fonction du contexte passé en option. Commençons par le cas standard où l'on ne passe pas de contexte.

foo.ewtsbar.ewts

$logger.info("foo: " & $script.getContext());
$doc.open({ modelName: 'personne', docId: 'some-valid-id' });
$logger.info("foo: " & $script.getContext());
$script.call("bar");
$logger.info("foo: " & $script.getContext());

$logger.info("bar: " & $script.getContext());

L'appel du script foo ci-dessus provoque les traces suivantes. La ligne 3 confirme que le script bar est exécuté dans le contexte du dossier ouvert par foo.

foo: {}
foo: {"modelName": personne, "docId": some-valid-id}
bar: {"modelName": personne, "docId": some-valid-id}
foo: {"modelName": personne, "docId": some-valid-id}

Modifions à présent la 4e ligne du script foo pour forcer un contexte vide lors de l'appel à la méthode $script.call. Ici, on passe le contexte vide sous la forme d'un string vide "", mais on obtient le même résultat en passant un map vide {}, voire n'importe quel map du moment qu'il ne contient pas la propriété modelName. Le script bar reste quant à lui inchangé.

foo.ewts

$logger.info("foo: " & $script.getContext());
$doc.open({ modelName: 'personne', docId: 'some-valid-id' });
$logger.info("foo: " & $script.getContext());
$script.call("bar", null, { context: "" });
$logger.info("foo: " & $script.getContext());

L'appel du script foo.ewts ci-dessus provoque les traces suivantes.

foo: {}
foo: {"modelName": personne, "docId": some-valid-id}
bar: {}
foo: {"modelName": personne, "docId": some-valid-id}

La 3e ligne de log confirme que le script bar est exécuté en-dehors du contexte du dossier ouvert par foo.

4. Exemple de gestion d'exception¶

Le code ci-dessous active la gestion d'exception propagate.

if ($$.param == 1) {
    $logger.info("déclenchement d'exception");
    throw "Exception test";
}
else {
    $logger.info("traitement principal");
    try {
        $script.call("testExceptionOnCall",
                     { param: 1 },
                     { exceptionBehaviour: "propagate" });
        $logger.info("après call");
    }
    catch (e) {
        $logger.info(e.message);
    }
}

L'exécution du script génère les traces suivantes:

INFO  testExceptionOnCall.ewts:6:18 - traitement principal
INFO  testExceptionOnCall.ewts:2:18 - déclenchement d'exception
INFO  testExceptionOnCall.ewts:14:22 - Exception test

Si on change la gestion d'exception avec exceptionBehaviour: "local", les traces après exécution sont les suivantes. En outre, un message d'erreur est généré par le moteur pour signaler qu'une exception non gérée a été déclenchée durant l'exécution :

INFO  testExceptionOnCall.ewts:6:18 - traitement principal
INFO  testExceptionOnCall.ewts:2:18 - déclenchement d'exception
ERROR ch.epilogic.ewt.scripts.EwtScriptManager.exec():655 - testExceptionOnCall.ewts:3:11 - Script 
      testExceptionOnCall.ewts encountered following uncaught exception: Exception test
INFO  testExceptionOnCall.ewts:11:22 - après call

$script.call¶