Format XML du fichier de contenu de l'introduction

Version 3.1.0

Le présent document décrit la structure du fichier de contenu de l'introduction sous la forme d'une série de fragments DTD.

introContent


<!ELEMENT introContent (page+ , group* , extensionContent*)>

L'élément introContent définit le corps du fichier de contenu de l'introduction. Ce fichier de contenu se compose de pages, de groupes partagés qui peuvent être inclus dans plusieurs pages et d'extensions de points d'ancrage définies dans d'autres configurations.



page


<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | title? | anchor* | contentProvider*)>

<!ATTLIST page

url           CDATA #IMPLIED

id           CDATA #REQUIRED

style          CDATA #IMPLIED

alt-style     CDATA #IMPLIED

filteredFrom (swt|html)

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED>

Cet élément permet de décrire la page à afficher. L'introduction peut afficher des pages dynamiques et statiques.

Le contenu des pages dynamiques est généré à partir des sous-éléments de la page, comme indiqué ci-après. Le style ou le style de remplacement (alt-style) est appliqué en fonction de la présentation. Les styles peuvent être optimisés en référençant l'attribut id ou class-id.

Les pages statiques permettent de réutiliser des documents HTML existants au sein d'une introduction et peuvent être liées à partir de n'importe quelle page statique ou dynamique. Les pages statiques ne sont pas définies dans un élément de type page. Il s'agit simplement de fichiers HTML qui peuvent liées par d'autres pages.

La page d'accueil, dont l'ID est défini dans l'élément "presentation" du point d'extension de configuration de l'introduction, peut posséder une adresse URL indiquant qu'il s'agit d'une page statique. Si vous n'indiquez pas d'adresse URL, le programme suppose que la page d'accueil est une page dynamique. Toutes les autres pages décrites à l'aide de l'élément "page" sont des pages dynamiques.
Lorsque la présentation SWT est utilisée et qu'une page statique doit s'afficher, un navigateur externe est lancé et la page en cours reste visible.

Les sous-éléments utilisés dans une page dynamique sont les suivants : Un sous-élément group est utilisé pour regrouper les contenus connexes et appliquer un style à l'ensemble du contenu regroupé. Un sous-élément link définit un lien qui peut être utilisé pour accéder à une page statique ou dynamique et exécuter une action/commande d'introduction. Un lien est généralement défini au niveau de la page pour accéder aux pages principales au lieu de créer plusieurs liens au sein d'une même page. Un sous-élément text définit le contenu textuel au niveau de la page. Un sous-élément head est applicable uniquement à la présentation Web et permet d'ajouter des données HTML à la section HTML head. Cet élément est utile pour ajouter des scripts Java ou des feuilles de style supplémentaires. Un sous-élément img définit le contenu de l'image au niveau de la page. Un sous-élément include permet de réutiliser n'importe quel élément autre qu'une page. Un sous-élément html est applicable uniquement à la présentation Web et permet l'intégration ou l'ajout de données HTML dans le contenu de la page. L'intégration permet d'intégrer un fichier HTML clairement défini au sein d'un élément HTML object en référençant le fichier HTML. L'inclusion permet d'inclure un fragment HTML directement à partir d'un fichier HTML. Un sous-élément title définit le titre de la page. Un sous-élément anchor définit un point dans lequel des contributions externes peuvent être insérées à l'aide d'un élément <extensionContent>.


group


<!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor*)>

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Permet de regrouper des contenus connexes, des contenus auxquels un style commun doit être appliqué ou des contenus qui doivent être inclus dans d'autres pages.


link


<!ELEMENT link (text? , img?)>

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Permet de créer un lien vers un fichier HTML statique, un site Web externe ou peut exécuter une action URL d'introduction.




Les actions prédéfinies sont décrites en utilisant le format suivant :

action name - Description de l'action
action parameter1 : Description du paramètre.
action parameter2 (facultatif) : Description du paramètre.
action parameter3 (facultatif) = ("true" | "false") "false" : Description du paramètre avec l'utilisation des options "true" ou "false". "False" correspond à la valeur par défaut.


Les actions prédéfinies suivantes sont incluses dans la structure d'introduction :

close : Ferme la partie d'introduction.
Aucun paramètre requis.

navigate : Permet de se déplacer dans les pages d'introduction dans un sens donné ou de revenir à la page d'accueil.
direction = ("backward" | "forward" | "home") : Indique le sens du déplacement.

openBrowser - Ouvre l'adresse URL dans un navigateur externe. Depuis la version 3.1, cette action repose sur la prise en charge du navigateur du plan de travail. Cela signifie que toutes les préférences utilisateur définies pour le navigateur seront honorées.
url : Adresse URL valide permettant d'accéder à un site Web externe ou à un fichier HTML statique.
pluginId (facultatif) : Requis uniquement si un fichier HTML statique est indiqué. Il s'agit de l'ID du plug-in contenant le fichier.

openURL - Ouvre l'URL intégrée à la page d'accueil. Dans le cas de la présentation SWT, l'URL est affiché dans un navigateur externe (identique à l'action openBrowser ci-dessus). Depuis la version 3.1
url - adresse URL valide permettant d'accéder à un site Web externe ou à un fichier HTML local
pluginId (facultatif) - si l'adresse url est relative, cela spécifie alors l'ID du plug-in contenant le fichier.

runAction : Exécute l'action indiquée.
class - nom complet d'une classe implémentant org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction ou org.eclipse.ui.IActionDelegate
pluginId : ID du plug-in contenant la classe.
standby (facultatif) = ("true" | "false") "false" : Indique si l'introduction doit passer en mode Pause à l'issue de l'exécution de l'action.
Paramètres supplémentaires : Paramètres supplémentaires transmis aux actions implémentant org.eclipse.ui.intro.config.IIntroAction

setStandbyMode : Définit l'état de la partie d'introduction.
standby = ("true" | "false") - true pour placer la partie d'introduction en mode pause partiellement visible et false pour la rendre complètement visible

showHelp : Affiche le système d'aide.
Aucun paramètre requis.

showHelpTopic : Ouvre une rubrique d'aide.
id : Adresse URL de la ressource d'aide. (Reportez-vous à Javadoc et recherchezorg.eclipse.ui.help.WorkbenchHelp.displayHelpResource
embed (optional) = ("true" | "false") "true" - indique que la ressource d'aide doit être affichée au sein des pages d'accueil. La valeur par défaut est false. Cet indicateur est simplement ignoré dans le cas d'une présentation SWT. Depuis la version 3.1
embedTarget (facultatif) - le chemin vers une div dans la page d'accueil en cours détenant le contenu de la rubrique d'aide. Si il est spécifié, alors embed a la valeur true par défaut et l'URL imbriquée est insérée à l'intérieur de la div avec le chemin spécifié. Le chemin étant relatif à la page, il ne doit pas commencé par l'ID de la page. Les enfants de la div sont remplacés par le contenu de l'adresse URL. Seule une div par page peut être utilisée comme une cible incorporée. Cet indicateur est simplement ignoré dans le cas d'une présentation SWT. De même, il n'est pas pris en charge lors de l'utilisation du format XHTML comme contenu d'introduction. Depuis la version 3.1


showMessage : Présente un message à l'utilisateur à l'aide d'une fenêtre standard.
message : Message présenté à l'utilisateur.

showStandby : Place la partie d'introduction en mode Pause et affiche l'élément standbyContentPart avec l'entrée indiquée.
partId : ID de l'élément standbyContentPart à afficher.
input : Entrée à définir pour l'élément standbyContentPart.

showPage : Affiche la page d'introduction associée à l'ID indiqué.
id : ID de la page d'introduction à afficher.
standby (facultatif) = ("true" | "false") "false" : Indique si l'introduction doit passer en mode Pause à l'issue de l'affichage de la page.

Si l'un des paramètres transmis à ces actions possèdent des caractères spéciaux (par exemple : caractères non conformes pour une adresse URL), ils doivent alors être encodés en utilisant l'encodage de l'URL UTF-8. Pour recevoir ces paramètres dans leur état décodé, un paramètre spécial, decode = ("true" "false") peut être utilisé pour forcer le décodage de ces paramètres lorsque la structure d'introduction les traite.
Par exemple, l'URL d'introduction suivante :
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message
traitera le paramètre de message sous la forme "This+is+a+message"
tandis que
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message&amp;decode=true
traitera le paramètre de message sous la forme "This is a message".


  • style-id - Attribut permettant de classer ce lien dans une catégorie donnée afin qu'un style commun soit appliqué.
  • filteredFrom : Attribut facultatif permettant de filtrer un élément donné d'une implémentation spécifique. Par exemple, si un groupe est associé à filteredFrom = swt, ce groupe n'apparaît pas sous la forme d'un contenu dans une implémentation SWT.
  • html


    <!ELEMENT html (img | text)>

    <!ATTLIST html

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    type         (inline|embed)

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    encoding     CDATA #IMPLIED

    Données HTML à inclure directement dans la page en imbriquant l'ensemble du document ou en intégrant un fragment de données HTML à l'emplacement défini. Une image ou un texte de remplacement doit être défini pour l'affichage d'une présentation SWT de substitution.
    L'imbrication permet d'intégrer un fichier HTML clairement défini au sein du contenu de la page dynamique. Un objet HTML is créé pour référencer le fichier HTML.
    L'inclusion permet d'inclure directement un fragment HTML dans une page HTML dynamique à partir d'un fichier.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Fragment de texte qui peut éventuellement contenir des balises d'échappement HTML. Il est uniquement utilisé sous forme de titre de page et une page doit donc comporter un seul élément title.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Fragment de texte qui peut éventuellement contenir des balises d'échappement HTML. Il peut comporter les balises b et li. Il peut également inclure des ancres pour les adresses URL. Si plusieurs paragraphes sont nécessaires, le texte peut être divisé en plusieurs parties commençant et finissant chacune par la balise p.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    développe un élément défini par le chemin indiqué et des attributs configId facultatifs. Le chemin doit définir de manière unique un élément au sein de la configuration indiquée. Il peut pointer vers un groupe partagé défini au niveau de la configuration ou vers n'importe quel élément d'une page.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    Données HTML à inclure directement dans la zone de contenu HEAD d'une page. Il permet d'ajouter des données HTML à la section HTML head. Cet élément est utile pour ajouter des scripts Java ou des feuilles de style supplémentaires. Ce marquage est utilisé uniquement avec l'implémentation d'une introduction reposant sur les données HTML. Il est simplement ignoré lors d'une implémentation de formulaires au sein de l'interface graphique. Une page peut comporter plusieurs éléments head. Une implémentation ne peut comporter qu'un seul élément head (qui est partagé dans toutes les pages).


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Image représentant le contenu d'une introduction et non la présentation (par opposition aux images de décoration définies dans les styles).


    extensionContent


    <!ELEMENT extensionContent (text | group | link | html | include)>

    <!ATTLIST extensionContent

    style       CDATA #IMPLIED

    alt-style  CDATA #IMPLIED

    path      CDATA #REQUIRED>

    Contenu à ajouter à l'ancre cible. Un seul contenu extensionContent est autorisé dans une extension configExtension donnée car si cette extension ne peut pas être résolue (si la configuration ou l'élément cible est introuvable), les pages et/ou les groupes de l'extension doivent être ignorés.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Une ancre est un élément utilisé pour déclarer l'extensibilité. Elle représente un emplacement défini dans la configuration pour permettre l'ajout de contributions externes. Seules les ancres sont les valeurs cibles autorisées pour l'attribut path d'un contenu extensionContent.


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    Proxy d'un fournisseur de contenu d'introduction permettant à une page d'introduction d'extraire des données provenant de différentes sources (Web, Eclipse, etc) et de fournir du contenu lors d'une exécution basée sur ces données dynamiques. Si la classe IIntroContentProvider spécifiée dans l'attribut de classe ne peut pas être chargée, alors le contenu de l'élément texte sera renvoyé à la place. C'est une version dynamique de la balise d'introduction html. Alors que la balise html permet l'intégration ou la mise en ligne d'un contenu html statique dans une page d'introduction html générée, la balise contentProvider permet une création dynamique de ce contenu lors de l'exécution. Une autre différence entre les balises est que la balise html n'est prise en charge que pour la présentation HTML, alors que cette balise contentProvider est prise en charge à la fois pour les présentations HTML et SWT. Depuis la version 3.0.1