JavaScool:DocCreationProglet

Spécification d'une «proglet»

On précise les éléments permettant de définir une proglet, y compris avec processing.

• Tous les fichiers nécessaires au fonctionnement de la proglet sont placés dans un dossier.

• Le nom du dossier correspond à l'identificateur de la proglet.
  L'identificateur (id) de chaque proglet doit être unique. Regarder sur la table des proglets les noms existants.

Le nom doit avoir au plus seize lettres minuscules ou majuscules; pas de chiffre ou de symbole. Il ne doit contenir que des lettres faire au moins quatre caractères et démarrer par une minuscule. Il doit être de la forme «algoDeMaths» pour «algo de maths» c'est à dire, sans espace, commencer par une minucule et les autres mots par une majuscule.

On respecte ici la convention de nommage des packages Java.

• Les fichiers standards de la proglet:
  • proglet.pml : le descripteur de la proglet.
  • help.xml : le fichier de documentation de la proglet.
  • Functions.java : qui définit les fonctions proposées à l'élève (optionnel).
  • Panel.java : qui implémente l'applet graphique de la proglet (optionnel).
  • completion.xml : qui définit les complétions automatiques proposées dans l'éditeur (optionnel).
  • Translator.java : qui implémente la traduction de Jvs en Java spécifique de cette proglet (optionnel).

---

proglet.pml est un fichier texte de trois lignes données sous la forme:

title = "Description en 1 à 2 lignes de la proglet"

author = "Prenom Nom <email@serveur>, Prenom Nom <email@serveur>, .."

icon = "Le nom de fichier de l'image qui décrit la proglet" (optionnel)

---

help.xml est un fichier en XML dont les balises sont définies ici avec une documentation utilisateur.

Il contient des liens vers les autres pages, il peut inclure une vidéo externe au site, qui montre le fonctionnement de la proglet, etc..

---

Functions.java est une classe publique sans parent, qui contient uniquement les fonctions et constantes statiques et publiques, destinées à l'utilisateur. Elle est documentée en français (or in English, but not in Frenglish), à destination de l'élève. Tous les identificateurs utilisés dans cette classes deviennent des mots réservés. Il ne faut rien mettre d'autre dans cette classe.

• Un mécanisme d'assertion aide à débugger le code.

---

Panel.java est une classe publique doit être une instance de java.awt.Component (donc un JPanel, une Applet, etc..).

• Elle peut implémenter la méthode start(), optionelle, appelée pour lancer une démonstration du fonctionnement de la proglet.
• Un mécanisme d'assertion aide à débugger le code.

---

completion.xml est un fichier en XML dont les balises sont définies ici et qui permet de définir le mécanisme de complétion de pour les appels definis dans Functions.java.

---

Translator.java est une classe publique qui a pour parent org.javascool.core.Translator et permet de définir des variantes du langage pour la proglet: se référer à la documentation.

• La traduction de Java simplifié (dit Jvs) en Java se fait à l'aide d'expression régulières appliquées sur tout le texte source.
• La classe permet de spécifier des import Java spécifique de la proglet.

---

• Les autres fichiers d'une proglet:
  • Des fichiers de resources nécessaires au fonctionnement de la proglet, comme par exemple des images, des sons, etc.
  • Des classes java nécessaires au fonctionnement interne de la proglet.
  • Des classes java accessibles à l'élève. Par exemple, on pourrait ajouter une classe 'Image' qui faciliterait l'usage d'images dans Java's Cool
  • Des fichiers .jvs qui servent d'exemple à l'élève. Ces fichiers peuvent être ouverts automatiquement par un lien inclus dans l'aide de la proglet (fichier help.xml).
  • Des fichiers .XML qui seront ouverts par des liens.
    • Les noms de ces fichiers sont utilisés en comme titre des pages, mais ils ne doivent pas contenir d'accents à cause des problèmes inter-plateforme: choisir des noms tels que exercice.xml, tutoriel.xml, description.xml, etc...
  • Des fichiers JAR contenant des classes Java externes (des extensions) qui sont utilisés par les classes Java de la proglet.