Ci-dessous, les différences entre deux révisions de la page.
Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente | ||
local:moodlescript:syntaxspecification [2019/03/26 13:21] admin [Arguments, identifiers and variables] |
local:moodlescript:syntaxspecification [2024/04/04 15:52] (Version actuelle) |
||
---|---|---|---|
Ligne 86: | Ligne 86: | ||
L'expression ci-dessus invoquera la fonction ''local_ent_installer_get_teacher_cat_idnumber()'' du plugin local ''local_ent_installer'', en allant la chercher dans le fichier ''locallib.php'' ( ou ''lib.php'' par defaut). La fonction devra retourner l'identifiant attendu. Dans l'exemple ci-dessus, la fonction devra retourner le numéro d'identification de l'objet administrable souhaité. | L'expression ci-dessus invoquera la fonction ''local_ent_installer_get_teacher_cat_idnumber()'' du plugin local ''local_ent_installer'', en allant la chercher dans le fichier ''locallib.php'' ( ou ''lib.php'' par defaut). La fonction devra retourner l'identifiant attendu. Dans l'exemple ci-dessus, la fonction devra retourner le numéro d'identification de l'objet administrable souhaité. | ||
- | You cannot pass any parameters to this call, so the identifier must be fully determined using current environment globals such as $USER, $COURSE, etc. to compute the expected identifier. | + | Vous ne pouvez pas passer de paramètres à cet appel, La fonction invoquée devra donc pouvoir fournir la réponse par la seule connaissance du contexte courant, grâce aux variables globales de moodle telles que $USER, $COURSE, etc. |
- | Here is a sample of an application function that computes the current user's owned category to move a course in: | + | Voici un exemple développé de l'usage d'une telle fonction qui obtient l'identifiant de la catégorie attribuée à un utilisateur lors de la création d'un cours: |
/** | /** | ||
Ligne 109: | Ligne 109: | ||
} | } | ||
- | Called in a moodlescript stack context, it will compute the category idnumber of the current user, so we can write a moodlescript move instruction as follows, moving the current course to the adequate destination: | + | Appelé dans un contexte d'exécution d'un Moodlescript, elle calculera l'identifiant de catégorie pour l'utilisateur "actuellement détenteur" de la session courante, et nous pourrons écrire l'instruction de script suivante qui déplacera le cours "courant" dans la destination souhaitée pour l'utilisateur courant (celui au nom duquel le moteur de script est exécuté): |
MOVE COURSE current TO idnumber:func:local_ent_installer@get_teacher_cat_idnumber | MOVE COURSE current TO idnumber:func:local_ent_installer@get_teacher_cat_idnumber | ||
- | === Literal Argument === | + | Lire plus loin pour la notion de contexte courant et le méta-identifieur "current". |
- | Literal arguments are simple words or strings. There is at the moment a restriction on syntax as strings are not specifically delimited (or only delimited by keywords). So strings should not contain keywords expressions. this is likely why we chose keywords in strict uppercase, to minimize syntactic collision with literal usual strings. | + | === Arguments littéraux === |
+ | |||
+ | Les arguments littéraux sont des mots simples ou des chaines de caractère. Dans la version actuelle du moteur, les chaînes ne sont pas délimitée syntaxiquement autrement que par la survenue d'un mot-clef attendu de l'expression. La conséquence est qu'il faudra éviter d'utiliser des littéraux qui utilisent les mots clefs du Moodlescript. C'est une des raisons principales pour laquelle nous avons décidé de forcer l'expression en majuscules de ces mots clefs, car cela diminue le risque de collision avec du texte usuel. | ||
=== Variables === | === Variables === | ||
- | We may need to inject some environmental values in the script to replace some non terminal placeholders. An execution stack can be fed at launch time with a global context data stub that will be merged with each instruction local context (adding or overriding values). Global context variables can be placed whereever in script statements or attribute lists using the Moodle common SQL named variable form: | + | Nous aurons probablement à injecter dans le script des valeurs provenant de variables contextuelles. Pour cela nous mettrons en place des symboles "non terminaux" qui seront remplacés par leur valeur à l'exécution. La pile d'exécution d'un script peut être chargée au départ avec un contexte global de données qui sera abondé au contexte local qu'utilise une instruction pendant son exécution (le contexte local lui ajoutant ou surchargeant des valeurs). Ces valriables peuvent être placées n'importe où dans la syntaxe, en respectant la forme typique des arguments SQL dans une requête au format Moodle : |
:varname | :varname | ||
- | To be valid, the placeholder expression MUST have at least one space character before it. | + | Pour être reconaissable, l'appel à la variable DOIT être précédée par au moins un espace. |
- | You may obtain a list of the available variables in the stack logger using the following instruction: | + | Une liste complète des variables de contexte disponibles pour les instructions peut être visualisée dans la trace d'exécution par l'instruction spéciale : |
LIST GLOBALS | LIST GLOBALS | ||
- | this will output, e.g. in the admin tool console, giving the console environment preset variables: | + | Ceci affichera, par ex. dans la console Moodlescript des outils d'administration : |
> GLOBAL CONTEXT | > GLOBAL CONTEXT | ||
Ligne 137: | Ligne 139: | ||
> siteshortname: DEV31 | > siteshortname: DEV31 | ||
- | Any local invocation of a MoodleScript stack may run the stack with his own global environment variable set, to serve some specific component scoped scripting needs. | + | //Usage en intégration : // |
- | ==== Special keywords (metas) ==== | + | Toute invocation d'une pile d'exécution MoodleScript peut être chargée avec un contexte d'entrée de départ, permettant à tout plugin d'y injecter le contexte dont il a besoin pour l'exécution de ses propres scriptlets. |
+ | |||
+ | ==== Mots-clefs spéciaux (metas) ==== | ||
==='current'=== | ==='current'=== | ||
- | 'current' is a special keyword in place of an expected identifier that will resolve into the nearest current object in the executing environment. F.e, if the expected object is a user identifier, current will resolve to $USER->id. If 'current' addresses a course identifier, it wil usually resolve as $COURSE->id, unless another course id is given to the execution stack by the global context (for plugin developers). | + | 'current' est un mot-clef spécial qui se substitue en lieu et place d'un identifiant d'objet et qui se résoudra par l'objet du type attendu le plus "proche" dans l'environnement d'exécution. Par exmple, si l'identifiant attendu à cet emplacement est un identifiant d'un utilisateur, alors 'current' désignera le plus souvent $USER->id. Si 'current' désigne un identifiant de cours, alors il se résoudra le plus souvent comme $COURSE->id. En général, l'exécution d'une création d'un objet imposera la valeur courante du "dernier identifiant connu" par la pile d'exécution, afin que les instructions suivantes puissent naturellement le réutiliser. Ce concept du "dernier objet connu" par le contexte sous-tendra toute la programmation interne des commandes du Moodlescript. |
- | The use of current will simplify scripts run within a known context, by using shorten expressions: | + | L'utilisation du mot clef 'current' simplifie la compréhension de scripts qui se déroulent dans un contexte connu, en raccourcissant les instructions : |
ADD ENROL METHOD guest TO current | ADD ENROL METHOD guest TO current | ||
- | For adding an enrolment method to the current course. | + | Pour ajouter la méthode d'inscription autorisant l'accès des invités dans le dernier cours connu par le contexte. |
ENROL current INTO current AS student | ENROL current INTO current AS student | ||
- | For enrolling the current user (the $USER being executing the script) into the current course. | + | Pour inscrire le dernier utilisateur connu (en général l'utilisateur $USER pour lequel le script est exécuté) dans le cours courant. (dernier cours créé, dernier cours mis à jour, etc.) |
- | ==='last' or 'first'=== | + | ==='last' ou 'first'=== |
- | this usually addresses the first available or last available item in the current syntax context. this is used f.e. for blocks location in a region, but might also address any object locaton being sorted with a sortorder attribute. | + | Ceci désignera généralement le premier ou dernier objet connu dans le contexte, lorsque la valeur associée au mot clef désigne un ensemble. Il est actuellement expérimentalement utilisé pour trouver la première zone de blocs disponible dans un format de cours, et sera étendu à d'autre usages où l'intérrogation d'une liste ordonnée d'objets est souhaitable. |
==='runtime'=== | ==='runtime'=== | ||
- | Usually identifiers and variable can be evaluated at parse time or at check time, because they are litterals in the script, or they come from some input or global context. But this is not true in all cases. Lets take an example: | + | Par défaut, les identifiants et les variables sont évaluées au moment de la compilation du script ou sa validation. car les valeurs sont soit statiques (littéraux), soit proviennent de valeurs chargées //a priori// dans le contexte d'exécution. Mais ce n'est pas toujours le cas. Prenons un exemple : |
- | In the following scriptlet: | + | Dans le sriptlet suivant : |
- | ADD CATEGORY "New category" TO idnumber:EXISTINGCAT HAVING | + | ADD CATEGORY "Nouvelle catégorie" TO idnumber:PARENTE HAVING |
- | idnumber: NEWCAT | + | idnumber: NOUVELLE |
- | MOVE COURSE idnumber:SOMECOURSE TO idnumber:NEWCAT | + | MOVE COURSE idnumber:UNCOURS TO idnumber:NOUVELLE |
- | We run into an issue because at parse time or at check time, NEWCAT category is not yet created. Thus we must tell the engine that in the second statement, we need the engine waiting the latest moment to evaulate the identifier to move the course in. | + | Il y a de manière évidente un problème à la compilation ou à la validation, car la catégorie désignée par NOUVELLE n'est pas encore créée. Nous devons donc indiquer à la deuxième instruction qu'il faudra attendre lors de l'exécution pour résoudre l'identifiant de la catégorie où le cours doit être déplacé. |
- | This can be done by the special keywork runtime: and we'll rewrite the scriplet as follows: | + | Ceci peut être fait en ajoutant le préfixe spécial 'runtime:' et nous réécrirons le script comme suit : |
- | ADD CATEGORY "New category" TO idnumber:EXISTINGCAT HAVING | + | ADD CATEGORY "Nouvelle catégorie" TO idnumber:PARENTE HAVING |
idnumber: NEWCAT | idnumber: NEWCAT | ||
- | MOVE COURSE idnumber:SOMECOURSE TO runtime:idnumber:NEWCAT | + | MOVE COURSE idnumber:UNCOURS TO runtime:idnumber:NOUVELLE |
- | Using the runtime: special keyword will prevent the parser to evaluate and resolve the identifier, and will store it's initial definition in the handler class. The handler will also NOT try to resolve it at check time, as check time only checks the conditions of execution of all the statements without executing them. At real execution time, the identifier will be resolved to get it's definitive actual value. | + | En utlisant le mot-clef 'runtime:' nous empêchons l'interpéteur syntaxique de résoudre cette valeur, et stockons sa définition initiale (sa référence à remplacer). The handler will also NOT try to resolve it at check time, as check time only checks the conditions of execution of all the statements without executing them. At real execution time, the identifier will be resolved to get it's definitive actual value. |
Note that 'runtime' variables may raise a real error situation that cannot be recovered or anticipated by the engine and may terminate in a tecnhical failure of the script and the calling process. | Note that 'runtime' variables may raise a real error situation that cannot be recovered or anticipated by the engine and may terminate in a tecnhical failure of the script and the calling process. | ||
[[:local:moodlescript|Revenir à l'index du composant]] | [[:local:moodlescript|Revenir à l'index du composant]] |