Ci-dessous, les différences entre deux révisions de la page.
Prochaine révision | Révision précédente Prochaine révision Les deux révisions suivantes | ||
local:moodlescript:syntaxspecification [2019/03/26 13:06] admin créée |
local:moodlescript:syntaxspecification [2019/03/26 13:38] admin [Arguments, identifiants et variables] |
||
---|---|---|---|
Ligne 52: | Ligne 52: | ||
IN, FOR, TO, IF EXISTS, IF NOT EXISTS | IN, FOR, TO, IF EXISTS, IF NOT EXISTS | ||
- | ==== Arguments, identifiers and variables ==== | + | ==== Arguments, identifiants et variables ==== |
- | Arguments are usually moodle object identifiers, terminal values or eventually global variables, for finding or setting values. the nature of the argument will vary across the syntax, and refers usually to the most common or trivial object type that is expected in the syntax. | + | Les arguments sont le plus souvent des identifiants d'objets moodle, des valeurs littérales terminales (qui s'expriment telle qu'écrites) ou éventuellement des appels à des variables globales ^permettant d'obtenir des "valeurs". La nature et la signification de la valeur peut varier au fil de l'expression, mais se référera toujours à la donnée la plus "logiquement" attendue à cet endroit de la "phase". |
- | F.E., for en enrolment syntax: | + | Par exemple, pour une instruction d'inscription, l'expression : |
ENROL id:33 IN id:3 AS shortname:student USING manual | ENROL id:33 IN id:3 AS shortname:student USING manual | ||
- | shows 4 attributes that are naturally refering to (successively) a user, a course, a role and an enrol method. | + | montre 4 attributs qui se réfèrent (successivement) à un Utilisateur, un Cours, un Role et une méthode d'inscription. |
- | In case the expression have some possible ambiguity, additional keywords will be used to discriminate possible cases. | + | Dans le cas où une commande viendrait à créer des ambiguités, la syntaxe devra comporter des "adverbes" propres à lever cette ambiguité. |
- | === Identifiers === | + | === Identifiants === |
- | when the syntax requires to identify an existing object, and this object may be identified by several information, we will use an explicit field discriminator and value couple, f.e. for a user, there are usually 4 admitted possible identifiers as primary id, username, idnumber or email. | + | Lorsque l'expression doit identifier un objet déjà existant dans Moodle, et que plusieurs informations permettent d'identifier cet objet, un discriminateur explicite devra être utilisé pour exprimer la valeur, par exemple. pour un utilisateur, il existe actuellement quatre identifiants possibles: l'identifiant numérique primaire de base de données (id), l'identifiant de connexion (username), le numéro d'identification (idnumber) ou l'email. |
- | Thus the following identifiers are usable when searching for a user : | + | Les expressions suivantes sont donc utilisables pour désigner un utilisateur dans moodle : |
id:33 | id:33 | ||
+ | |||
username:johndoe | username:johndoe | ||
+ | |||
idnumber:JD@35465 | idnumber:JD@35465 | ||
- | email:john.doe@gmail.com | ||
- | === Special identifier case : identifier given by a function === | + | email:john.doe@gmail.com |
- | In some applications, we want an identifier being given by a custom or existing function, depending on some current context. the identifier form will accept the 'func' prefix to identifiy some plugin function to call to get an identifier: | + | === Techniques spéciales d'identification : utiliser une fonction pour obtenir un identifiant === |
- | Example: | + | Dans certains usages, nous souhaiterions que l'identifiant soit fourni par une fonction existante (ou nouvelle) dans l'API moodle, qui s'exécutera dans le contexte courant du moteur. L'identifiant fera alors figurer le préfixe supplémentaire 'func', suivi d'un identifiant de fonction localisé dans son plugin comme suit : |
idnumber:func:local_ent_installer@get_teacher_cat_idnumber | idnumber:func:local_ent_installer@get_teacher_cat_idnumber | ||
- | will invoke the function ''local_ent_installer_get_teacher_cat_idnumber()'' in the plugin ''local_ent_installer' ''locallib.php'' (or by default, ''lib.php'') local library to get the expected identifier. the result of the function will be used as idnumber to find ethe primary identifier of the objet. | + | 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 108: | 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 136: | 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 : // |
+ | |||
+ | 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. | ||
==== Special keywords (metas) ==== | ==== Special keywords (metas) ==== |