|
1 # API d’accès aux métadonnées # |
|
2 |
|
3 ATTENTION ! |
|
4 Cette documentation se réfère à la dernière version du Metadataplayer, disponible dans la branche **default** du repository |
|
5 http://www.iri.centrepompidou.fr/dev/hg/metadataplayer |
|
6 |
|
7 ## Élément de base ## |
|
8 |
|
9 IriSP.Model.Element |
|
10 |
|
11 ### Rôle ### |
|
12 |
|
13 Classe de base dont héritent les différents types d’objets utilisés dans le Metadataplayer: annotations, types d’annotations, médias, etc. |
|
14 |
|
15 ### Instanciation ### |
|
16 |
|
17 **Element** fonctionne comme une classe abstraite est n’est jamais instancié directement. |
|
18 |
|
19 Néanmoins, tous les objets en héritant seront instanciés de la manière suivante : |
|
20 |
|
21 var myElement = new IriSP.Model.Element(id, source); |
|
22 |
|
23 - **id** est l’identifiant unique de l’élément. S’il est à *false*, un identifiant unique sera généré. |
|
24 - **source** identifie la source de données dont provient l’élément (cf. Source de Données, *IriSP.Model.Source*, plus bas). |
|
25 |
|
26 ### Propriétés ### |
|
27 |
|
28 #### type #### |
|
29 |
|
30 Type d’élément, surchargé par les classes qui héritent de l’élément de base: |
|
31 |
|
32 - **element** pour IriSP.Model.Element |
|
33 - **media** pour IriSP.Model.Media |
|
34 - **annotationType** pour IriSP.Model.AnnotationType |
|
35 - **tag** pour IriSP.Model.Tag |
|
36 - **annotation** pour IriSP.Model.Annotation |
|
37 - **mashup** pour IriSP.Model.Mashup |
|
38 - **mashedAnnotation** pour IriSP.Model.MashedAnnotation |
|
39 |
|
40 #### id #### |
|
41 |
|
42 Identifiant unique de l’élément |
|
43 |
|
44 #### title #### |
|
45 |
|
46 Titre de l’élément, par défaut une chaîne vide ("") |
|
47 |
|
48 #### description #### |
|
49 |
|
50 Description de l’élément, par défaut une chaîne vide ("") |
|
51 |
|
52 ## Media ## |
|
53 |
|
54 IriSP.Model.Media |
|
55 |
|
56 ### Rôle ### |
|
57 |
|
58 Représente un média (vidéo ou audio). |
|
59 |
|
60 Hérite de l’Élément de base |
|
61 |
|
62 ### Propriétés ### |
|
63 |
|
64 #### video #### |
|
65 |
|
66 Il s’agit de l’URL de la vidéo à charger |
|
67 |
|
68 #### duration #### |
|
69 |
|
70 Il s’agit de la durée du média (telle que renseignée dans les métadonnées -- peut ne pas être égale à la durée telle que lue dans la fenêtre vidéo). |
|
71 |
|
72 Il s’agit d’un objet durée (cf. *IriSP.Model.Time* plus bas) |
|
73 |
|
74 ### Méthodes ### |
|
75 |
|
76 #### getDuration #### |
|
77 |
|
78 Permet de spécifier la durée du média, en millisecondes |
|
79 |
|
80 #### getAnnotations #### |
|
81 |
|
82 Retourne la liste des annotations associées au média |
|
83 |
|
84 #### getAnnotationsByTypeTitle #### |
|
85 |
|
86 Retourne la liste des annotations associées au média et dont le type d’annotation (ou découpage, ou ligne, c.f. Type d’Annotation plus bas) correspond à l’argument de la fonction |
|
87 |
|
88 ## Type d’Annotation ## |
|
89 |
|
90 IriSP.Model.AnnotationType |
|
91 |
|
92 ### Rôle ### |
|
93 |
|
94 Représente un type d’annotation, correspondant également à ce qui peut être nommé découpage ou ligne dans *Lignes de Temps* |
|
95 |
|
96 Hérite de l’Élément de base. |
|
97 |
|
98 ### Méthodes ### |
|
99 |
|
100 #### getAnnotations #### |
|
101 |
|
102 Retourne la liste des annotations associées au type d’annotation |
|
103 |
|
104 ## Annotation ## |
|
105 |
|
106 IriSP.Model.Annotation |
|
107 |
|
108 ### Rôle ### |
|
109 |
|
110 Représente une annotation, correspondant à un segment temporel (dont la durée peut être nulle) d’un média |
|
111 |
|
112 Hérite de l’Élément de base. |
|
113 |
|
114 ### Propriétés ### |
|
115 |
|
116 #### begin #### |
|
117 |
|
118 Timecode de fin de l’annotation. Est un objet de type durée (cf. plus bas) |
|
119 |
|
120 #### begin #### |
|
121 |
|
122 Timecode de début de l’annotation. Est un objet de type durée (cf. plus bas) |
|
123 |
|
124 ### Méthodes ### |
|
125 |
|
126 #### getMedia #### |
|
127 |
|
128 Retourne l’objet **Média** (*IriSP.Model.Media*) auquel se réfère l’annotation |
|
129 |
|
130 #### getAnnotationType #### |
|
131 |
|
132 Retourne l’objet **Type d’Annotation** (*IriSP.Model.AnnotationType*) auquel se réfère l’annotation |
|
133 |
|
134 #### getTags #### |
|
135 |
|
136 Retourne la liste (cf. Liste d’éléments *IriSP.Model.List*) des tags associés à l’annotation. |
|
137 |
|
138 #### getTagTexts #### |
|
139 |
|
140 ## Mashup ## |
|
141 |
|
142 IriSP.Model.Mashup |
|
143 |
|
144 ### Rôle ### |
|
145 |
|
146 Il s’agit d’un bout à bout, composé d’une liste de segments (définis par des annotations de durée non nulle) accolés les uns après les autres. |
|
147 |
|
148 ### Méthodes ### |
|
149 |
|
150 **À compléter** |
|
151 |
|
152 ## Liste d’éléments ## |
|
153 |
|
154 IriSP.Model.List |
|
155 |
|
156 ### Rôle ### |
|
157 |
|
158 Etend les fonctionnalités des tableaux javascript (*Array*) pour lister des éléments (cf. types d’éléments ci-dessus). |
|
159 |
|
160 ### Instanciation ### |
|
161 |
|
162 var myList = new IriSP.Model.List(directory); |
|
163 |
|
164 - **directory** est le répertoire de données auxquelles la liste permet d’accéder (cf. plus bas) |
|
165 |
|
166 ### Méthodes ### |
|
167 |
|
168 #### Méthodes de parcours de liste #### |
|
169 |
|
170 Ces méthodes sont fournies grâce à la bibliothèque extérieure *underscore.js* et sont documentées sur http://documentcloud.github.com/underscore/ |
|
171 |
|
172 Il s’agit de: |
|
173 |
|
174 - **map**: Renvoie un tableau (*Array*) dont les éléments correspondent aux éléments de la liste, via une fonction passée en argument de map |
|
175 - **forEach**: Itère une fonction sur la liste. |
|
176 - **filter**: Ne renvoie que les éléments de la liste dont la valeur correspond au résultat d’une fonction. |
|
177 - **sortBy**: Fonction de tri, par ordre croissant de la valeur retournée par la fonction passée en argument. |
|
178 |
|
179 #### searchByTitle, searchByDescription, searchByTextFields #### |
|
180 |
|
181 Méthodes retournant une nouvelle liste d’éléments, contenant les éléments de la liste dont respectivement le titre, la description ou les deux correspondent à l’argument de la méthode. |
|
182 |
|
183 myList.searchByTitle("texte"); // => un *IriSP.Model.List* contenant les éléments de myList dont le titre contient "texte" |
|
184 |
|
185 ## Durée ## |
|
186 |
|
187 IriSP.Model.Time |
|
188 |
|
189 ### Rôle ### |
|
190 |
|
191 Facilite la gestion des durées en millisecondes utilisées dans le Metadataplayer |
|
192 |
|
193 ### Instanciation ### |
|
194 |
|
195 var myTime = new IriSP.Model.Time(ms); |
|
196 |
|
197 - **ms** est une durée en millisecondes |
|
198 |
|
199 ### Méthodes ### |
|
200 |
|
201 #### getSeconds #### |
|
202 |
|
203 Renvoie la durée convertie en secondes |
|
204 |
|
205 #### toString #### |
|
206 |
|
207 Renvoie la durée au format (hh:)mm:ss |
|
208 |
|
209 #### setSeconds #### |
|
210 |
|
211 Permet d’affecter une durée en secondes |
|
212 |
|
213 myTime.setSeconds(12); // 12000 millisecondes |
|
214 |
|
215 ## Source de données ## |
|
216 |
|
217 IriSP.Model.Source |
|
218 |
|
219 et |
|
220 IriSP.Model.RemoteSource |
|
221 |
|
222 ### Rôle ### |
|
223 |
|
224 Gère une source de données : fichier externe JSON, XML, etc. pour *IriSP.Model.RemoteSource*, projet créé à la volée pour *IriSP.Model.Source*. |
|
225 |
|
226 *IriSP.Model.RemoteSource* hérite de *IriSP.Model.Source* et ne diffère que par son implémentation de la méthode *get*. |
|
227 |
|
228 Sur la plateforme *Lignes de Temps*, il existe plusieurs API qui sont utilisées comme sources : |
|
229 |
|
230 - L’API projet, qui renvoie un fichier JSON contenant un projet LDT complet. |
|
231 - L’API segment, qui renvoie toutes les annotations d’un média situées entre deux timecodes fournis en argument. |
|
232 - L’API de publication d’annotation, qui demande l’envoi (par la méthode HTTP PUT) d’une liste d’annotation et renvoie celle-ci en retour, avec les identifiants des annotations en base de données. |
|
233 |
|
234 ### Instanciation ### |
|
235 |
|
236 var config = { directory: myDirectory }; |
|
237 var mySource = new IriSP.Model.Source(config); |
|
238 |
|
239 - **config** est un objet contenant les options de configuration: |
|
240 - Il doit nécessairement contenir une propriété **directory**, désignant le répertoire de données (cf. plus bas). |
|
241 - La propriété **serializer** doit désigner le *Sérialiseur* utilisé pour désérialiser les données importées ou sérialiser l’export. |
|
242 - un *IriSP.Model.RemoteSource* doit également être appelé avec une propriété **url**, désignant l’URL de la source. |
|
243 |
|
244 Une Source ne doit pas être instanciée directement, ce rôle est donné aux répertoires de données, ce qui permet notamment d’éviter des accès multiples à une même URL. |
|
245 |
|
246 ### Propriétés ### |
|
247 |
|
248 #### currentMedia #### |
|
249 |
|
250 *TODO: transférer dans un objet "Project"* |
|
251 |
|
252 Donne accès au média en cours du projet. Peut désigner un vrai média ou un mashup. |
|
253 |
|
254 ### Méthodes ### |
|
255 |
|
256 #### get #### |
|
257 |
|
258 Permet de récupérer ou de rafraîchir, via Ajax, les données de la source. Pour un *IriSP.Model.Source* de base, n’a aucun effet. |
|
259 |
|
260 #### onLoad #### |
|
261 |
|
262 Permet d’exécuter une fonction, passée en argument, au chargement de la source. |
|
263 |
|
264 #### serialize, deSerialize #### |
|
265 |
|
266 Transforme les données de la source en données sérialisées, au format du sérialiseur associées à la source, et inversement. |
|
267 |
|
268 #### getAnnotations, getAnnotationTypes, getMedias, getTags, getMashups #### |
|
269 |
|
270 Retourne les listes respectives d’annotations, types d’annotations, médias, tags et mashups de la source. |
|
271 |
|
272 #### getAnnotationsByTypeTitle #### |
|
273 |
|
274 Retourne la liste des annotations dont le type d’annotation correspond à l’argument de la fonction. |
|
275 |
|
276 ## Répertoire de données ## |
|
277 |
|
278 IriSP.Model.Directory |
|
279 |
|
280 ### Rôle ### |
|
281 |
|
282 Gère l’instanciation des sources de données et la mise en cache de ces sources lorsque plusieurs appels à la même URLs sont faits. |
|
283 |
|
284 Permet également aux objets de plusieurs sources d’interagir entre eux. |
|
285 |
|
286 ### Instanciation ### |
|
287 |
|
288 var myDirectory = new IriSP.Model.Directory |
|
289 |
|
290 ### Méthodes ### |
|
291 |
|
292 #### newLocalSource #### |
|
293 |
|
294 Crée une nouvelle source non attachée à une URL. S’il faut exporter des données, un sérialiseur doit être passé en paramètres. |
|
295 |
|
296 var myConfig = { serializer: IriSP.serializers.ldt }; |
|
297 var myLocalSource = myDirectory.newLocalSource(myConfig); |
|
298 |
|
299 #### remoteSource #### |
|
300 |
|
301 Crée ou récupère (si celle-ci existe déjà) une source attachée à une URL. Le sérialiseur est obligatoire. |
|
302 |
|
303 var myConfig = { url: "source-data.json", serializer: IriSP.serializers.ldt }; |
|
304 var myLocalSource = myDirectory.remoteSource(myConfig); |