|
1 # API de programmation de widgets # |
|
2 |
|
3 ATTENTION ! |
|
4 Cette documentation se réfère à la v.3 du Metadataplayer, actuellement disponible dans la branche **new-model** du repository |
|
5 http://www.iri.centrepompidou.fr/dev/hg/metadataplayer |
|
6 |
|
7 ## Types et fichiers ## |
|
8 |
|
9 Les widgets sont créés au moment de l’instanciation du Metadataplayer, en lisant la propriété *gui.widgets* des paramètres de configuration. |
|
10 |
|
11 Exemple: |
|
12 |
|
13 var monPlayer = new IriSP.Metadataplayer({ |
|
14 player: {...}, |
|
15 gui: { |
|
16 container: ..., |
|
17 widgets: [ |
|
18 { |
|
19 type: "Slider" |
|
20 }, |
|
21 { |
|
22 type: "Controller" |
|
23 }, |
|
24 { |
|
25 type: "MonWidget", |
|
26 option: "valeur" |
|
27 }, |
|
28 ... |
|
29 ] |
|
30 } |
|
31 }); |
|
32 |
|
33 Le *type* du widget détermine quels fichiers, javascript et CSS, seront appelés et quelle classe d'objet sera instanciée. |
|
34 |
|
35 Par exemple, pour le *type* **MonWidget**, seront appelés **MonWidget.js**, **MonWidget.css** et l’initialisation du widget se fera en appelant la classe **IriSP.Widgets.MonWidget** |
|
36 |
|
37 Le fichier **MonWidget.js** doit donc contenir une implémentation de **IriSP.Widgets.MonWidget** |
|
38 |
|
39 ## Implémentation d’une classe de widget ## |
|
40 |
|
41 La classe de Widget doit hériter de IriSP.Widgets.Widget. Le code permettant l’héritage est le suivant: |
|
42 |
|
43 IriSP.Widgets.MonWidget = function(player, config) { |
|
44 IriSP.Widgets.Widget.call(this, player, config); |
|
45 } |
|
46 |
|
47 IriSP.Widgets.MonWidget.prototype = new IriSP.Widgets.Widget(); |
|
48 |
|
49 ### Paramètres d’appel de l’objet Widget ### |
|
50 |
|
51 Le paramètre **player** correspond à l’objet IriSP.Metadataplayer qui a appelé le widget. |
|
52 |
|
53 Il sera ensuite accessible dans les fonctions du widget par: |
|
54 |
|
55 this.player |
|
56 |
|
57 Le paramètre **config** correspond aux paramètres de configuration du widget. Dans notre exemple, il s’agit d’un objet contenant: |
|
58 |
|
59 { |
|
60 type: "MonWidget", |
|
61 option: "valeur de l’option" |
|
62 } |
|
63 |
|
64 Les options de configuration sont recopiées dans les propriétés de l’objet widget: |
|
65 |
|
66 this.type => "MonWidget" |
|
67 this.option => "valeur de l’option" |
|
68 |
|
69 ### Propriétés accessibles par le widget ### |
|
70 |
|
71 #### Popcorn #### |
|
72 |
|
73 Les fonctions de gestion de la lecture vidéo sont accessibles par la propriété **popcorn** du Metadataplayer. |
|
74 |
|
75 Par exemple: |
|
76 |
|
77 this.player.popcorn.trigger("Evenement"); => déclenche un événement Popcorn de type "Evenement" |
|
78 this.player.popcorn.play(); => met le player en lecture |
|
79 this.player.popcorn.currentTime() => obtient le timecode courant, en secondes |
|
80 |
|
81 #### Source de métadonnées #### |
|
82 |
|
83 La source de métadonnées est accessible par la propriété **source** du Widget. |
|
84 |
|
85 Par exemple: |
|
86 |
|
87 this.source.getAnnotations(); => obtient la liste des annotations |
|
88 this.source.getDuration(); => obtient la durée du média en cours, en millisecondes |
|
89 |
|
90 #### Sélecteur jQuery #### |
|
91 |
|
92 Le contenu du widget est géré par la bibliothèque jQuery. Pour accéder à ce contenu, il suffit d’appeller la propriété **$** du widget |
|
93 |
|
94 Par exemple: |
|
95 |
|
96 this.$.html(); => renvoie le code HTML contenu dans le widget. |
|
97 this.$.find("p").html("Hello, world") => écrit "Hello, world" dans le(s) élément(s) <P> du widget. |
|
98 |
|
99 ### Fonctions facilitatrices du widget ### |
|
100 |
|
101 Quelques fonctions ont été rajoutées pour faciliter quelques tâches courantes: |
|
102 |
|
103 #### getWidgetAnnotations #### |
|
104 |
|
105 Retourne la liste des annotations selon la valeur de la propriété **annotation\_type** du widget: |
|
106 - Chaîne de caractères: prend en compte les types d’annotations dont le titre contient la chaîne. Exemple: "chap" permet notamment d’afficher les annotations dans le type d’annotation "Chapitrage" |
|
107 - Tableau de chaînes: pour prendre en compte plusieurs types d’annotations |
|
108 - false: pour prendre en compte toutes les annotations du projet |
|
109 |
|
110 this.getWidgetAnnotations(); |
|
111 |
|
112 #### functionWrapper #### |
|
113 |
|
114 Gère l’accès au fonctions du widget dans des callbacks. Ceci sert à pallier au fait qu’en Javascript, appeler directement une fonction dans un callback ne l’applique pas à l’objet dans lequel elle a été appelée. |
|
115 |
|
116 **functionWrapper** demande un argument, une chaîne qui est le nom de la fonction à appeler. |
|
117 |
|
118 Par exemple: |
|
119 |
|
120 this.$.click(this.functionWrapper("onClick")); => Appellera this.onClick() lors d’un click sur le widget |
|
121 |
|
122 #### bindPopcorn #### |
|
123 |
|
124 Attache un événement *Popcorn* à une fonction, sur le même mode que *functionWrapper* |
|
125 |
|
126 Par exemple: |
|
127 |
|
128 this.bindPopcorn("timeupdate","onTimeupdate"); => Appellera this.onTimeupdate() lorsque l’événement Popcorn "timeupdate" est déclenché. |
|
129 |
|
130 #### Autres fonctions #### |
|
131 |
|
132 Les fonctions relatives aux gabarits seront explicités dans la section Gabarits |
|
133 |
|
134 ### Implémentation de la fonction draw ### |
|
135 |
|
136 La fonction **draw()** est appelée automatiquement lorsque les métadonnées ont fini d’être chargées. C’est le lieu privilégié pour les fonctions gérant l’apparence du widget. |
|
137 |
|
138 IriSP.Widgets.MonWidget.prototype.draw = function() { |
|
139 this.$.html("Hello, world"); |
|
140 } |
|
141 |
|
142 ## Utilisation des gabarits ## |
|
143 |
|
144 Les gabarits ou *templates* en anglais permettent d’injecter des données dans du code HTML. |
|
145 |
|
146 ### Utilisation de Mustache ### |
|
147 |
|
148 Le Metadataplayer utilise la bibliothèque *Mustache.js* pour réaliser cette opération. |
|
149 |
|
150 Voici un exemple d’utilisation de *Mustache* seul: |
|
151 |
|
152 var gabarit = "<b>{{hello}}</b>, {{world}}"; |
|
153 var donnees = { |
|
154 hello: "Bonjour", |
|
155 world: "monde" |
|
156 } |
|
157 Mustache.to_html(gabarit, donnees); => "<b>Bonjour</b>, monde" |
|
158 |
|
159 ### templateToHtml ### |
|
160 |
|
161 Les gabarits sont souvent utilisés directement avec les propriétés du widget. Un raccourci existe pour injecter directement celles-ci dans un gabarit: |
|
162 |
|
163 this.templateToHtml("<h3>{{type}}</h3><p>{{option}}</p>"); => "<h3>MonWidget</h3><p>valeur de l’option</p>" |
|
164 |
|
165 ### renderTemplate ### |
|
166 |
|
167 Dans les cas les plus fréquents, le gabarit sera implémenté directement dans la propriété *template* du widget, par exemple: |
|
168 |
|
169 IriSP.Widgets.MonWidget.prototype.template = "<h3>{{type}}</h3><p>{{option}}</p>"; |
|
170 |
|
171 De plus, le code généré par le gabarit a pour vocation d’être rajouté directement au contenu du widget, généralement à l’intérieur de la fonction draw(). Ceci peut être réalisé avec la fonction *renderTemplate*. |
|
172 |
|
173 this.renderTemplate(); => ajoute directement "<h3>MonWidget</h3><p>valeur de l’option</p>" dans le code HTML du widget |
|
174 |
|
175 ## Internationalisation du widget ## |
|
176 |
|
177 Le Metadataplayer a été conçu pour être multilingue. Pour ceci, les différents textes de l’interface doivent être séparés du reste du code et des gabarits. |
|
178 |
|
179 ### Définition des textes ### |
|
180 |
|
181 Les textes sont définis dans la propriété **messages** du widget et regroupés par langue, dans un objet dont les clés sont les codes ISO 639-1 de la langue. Chaque langue est elle-même un objet, associant un nom de texte unique à sa traduction. |
|
182 |
|
183 IriSP.Widgets.MonWidget.prototype.message = { |
|
184 en: { |
|
185 hello: "Hello", |
|
186 world: "world" |
|
187 }, |
|
188 fr: { |
|
189 hello: "Bonjour", |
|
190 world: "monde" |
|
191 } |
|
192 } |
|
193 |
|
194 ### Accès aux textes dans la langue de l’interface ### |
|
195 |
|
196 La langue de l’interface est définie par *IriSP.language*. Un accès direct aux messages se fait par la propriété *l10n* (raccourci pour "localization") du widget. |
|
197 |
|
198 this.l10n.hello; => "Hello" si l’interface est en anglais, "Bonjour" si l’interface est en français. |
|
199 |
|
200 ### Accès aux textes dans un gabarit ### |
|
201 |
|
202 Cette propriété *l10n* permet d’accéder directement aux textes dans les gabarits: |
|
203 |
|
204 this.templateToHtml("{{l10n.hello}}, {{l10n.world}}!"); => "Hello, world!" en anglais ou "Bonjour, monde!" en français. |
|
205 |