@@ -4,166 +4,166 @@ annotator.storage package
4
4
=========================
5
5
6
6
.. function :: annotator.storage.debug()
7
-
7
+
8
8
A storage component that can be used to print details of the annotation
9
9
persistence processes to the console when developing other parts of
10
10
Annotator.
11
-
12
- Use as a plugin module::
13
-
11
+
12
+ Use as an extension module::
13
+
14
14
app.include(annotator.storage.debug);
15
15
16
16
17
17
.. function :: annotator.storage.noop()
18
-
18
+
19
19
A no-op storage component. It swallows all calls and does the bare minimum
20
20
needed. Needless to say, it does not provide any real persistence.
21
-
22
- Use as a plugin module::
23
-
21
+
22
+ Use as a extension module::
23
+
24
24
app.include(annotator.storage.noop);
25
25
26
26
27
27
.. function :: annotator.storage.http([options])
28
-
29
- A module that configures an instance of
28
+
29
+ A module which configures an instance of
30
30
:class: `annotator.storage.HttpStorage ` as the storage component.
31
-
31
+
32
32
:param Object options:
33
33
Configuration options. For available options see
34
34
:attr: `~annotator.storage.HttpStorage.options `.
35
35
36
36
37
37
.. class :: annotator.storage.HttpStorage([options])
38
-
38
+
39
39
HttpStorage is a storage component that talks to a remote JSON + HTTP API
40
40
that should be relatively easy to implement with any web application
41
41
framework.
42
-
42
+
43
43
:param Object options: See :attr: `~annotator.storage.HttpStorage.options `.
44
44
45
45
46
46
.. function :: annotator.storage.HttpStorage.prototype.create(annotation)
47
-
47
+
48
48
Create an annotation.
49
-
49
+
50
50
**Examples **::
51
-
51
+
52
52
store.create({text: "my new annotation comment"})
53
53
// => Results in an HTTP POST request to the server containing the
54
54
// annotation as serialised JSON.
55
-
55
+
56
56
:param Object annotation: An annotation.
57
57
:returns: The request object.
58
58
:rtype: Promise
59
59
60
60
61
61
.. function :: annotator.storage.HttpStorage.prototype.update(annotation)
62
-
62
+
63
63
Update an annotation.
64
-
64
+
65
65
**Examples **::
66
-
66
+
67
67
store.update({id: "blah", text: "updated annotation comment"})
68
68
// => Results in an HTTP PUT request to the server containing the
69
69
// annotation as serialised JSON.
70
-
70
+
71
71
:param Object annotation: An annotation. Must contain an `id `.
72
72
:returns: The request object.
73
73
:rtype: Promise
74
74
75
75
76
76
.. function :: annotator.storage.HttpStorage.prototype.delete(annotation)
77
-
77
+
78
78
Delete an annotation.
79
-
79
+
80
80
**Examples **::
81
-
81
+
82
82
store.delete({id: "blah"})
83
83
// => Results in an HTTP DELETE request to the server.
84
-
84
+
85
85
:param Object annotation: An annotation. Must contain an `id `.
86
86
:returns: The request object.
87
87
:rtype: Promise
88
88
89
89
90
90
.. function :: annotator.storage.HttpStorage.prototype.query(queryObj)
91
-
91
+
92
92
Searches for annotations matching the specified query.
93
-
93
+
94
94
:param Object queryObj: An object describing the query.
95
95
:returns:
96
96
A promise, resolves to an object containing query `results ` and `meta `.
97
97
:rtype: Promise
98
98
99
99
100
100
.. function :: annotator.storage.HttpStorage.prototype.setHeader(name, value)
101
-
101
+
102
102
Set a custom HTTP header to be sent with every request.
103
-
103
+
104
104
**Examples **::
105
-
105
+
106
106
store.setHeader('X-My-Custom-Header', 'MyCustomValue')
107
-
107
+
108
108
:param string name: The header name.
109
109
:param string value: The header value.
110
110
111
111
112
112
.. attribute :: annotator.storage.HttpStorage.options
113
-
113
+
114
114
Available configuration options for HttpStorage. See below.
115
115
116
116
117
117
.. attribute :: annotator.storage.HttpStorage.options.emulateHTTP
118
-
119
- Should the plugin emulate HTTP methods like PUT and DELETE for
118
+
119
+ Should the storage emulate HTTP methods like PUT and DELETE for
120
120
interaction with legacy web servers? Setting this to `true ` will fake
121
121
HTTP `PUT ` and `DELETE ` requests with an HTTP `POST `, and will set the
122
122
request header `X-HTTP-Method-Override ` with the name of the desired
123
123
method.
124
-
124
+
125
125
**Default **: ``false ``
126
126
127
127
128
128
.. attribute :: annotator.storage.HttpStorage.options.emulateJSON
129
-
130
- Should the plugin emulate JSON POST/PUT payloads by sending its requests
129
+
130
+ Should the storage emulate JSON POST/PUT payloads by sending its requests
131
131
as application/x-www-form-urlencoded with a single key, "json"
132
-
132
+
133
133
**Default **: ``false ``
134
134
135
135
136
136
.. attribute :: annotator.storage.HttpStorage.options.headers
137
-
137
+
138
138
A set of custom headers that will be sent with every request. See also
139
139
the setHeader method.
140
-
140
+
141
141
**Default **: ``{} ``
142
142
143
143
144
144
.. attribute :: annotator.storage.HttpStorage.options.onError
145
-
145
+
146
146
Callback, called if a remote request throws an error.
147
147
148
148
149
149
.. attribute :: annotator.storage.HttpStorage.options.prefix
150
-
150
+
151
151
This is the API endpoint. If the server supports Cross Origin Resource
152
152
Sharing (CORS) a full URL can be used here.
153
-
153
+
154
154
**Default **: ``'/store' ``
155
155
156
156
157
157
.. attribute :: annotator.storage.HttpStorage.options.urls
158
-
158
+
159
159
The server URLs for each available action. These URLs can be anything but
160
160
must respond to the appropriate HTTP method. The URLs are Level 1 URI
161
161
Templates as defined in RFC6570:
162
-
162
+
163
163
http://tools.ietf.org/html/rfc6570#section-1.2
164
-
164
+
165
165
**Default **::
166
-
166
+
167
167
{
168
168
create: '/annotations',
169
169
update: '/annotations/{id}',
@@ -173,97 +173,99 @@ annotator.storage package
173
173
174
174
175
175
.. class :: annotator.storage.StorageAdapter(store, runHook)
176
-
176
+
177
177
StorageAdapter wraps a concrete implementation of the Storage interface, and
178
178
ensures that the appropriate hooks are fired when annotations are created,
179
179
updated, deleted, etc.
180
-
181
- :param store: The Store implementation that manages persistence
182
- :param Function runHook: A function that can be used to run lifecycle hooks
180
+
181
+ :param store: The Store implementation which manages persistence
182
+ :param Function runHook: A function which can be used to run lifecycle hooks
183
183
184
184
185
185
.. function :: annotator.storage.StorageAdapter.prototype.create(obj)
186
-
186
+
187
187
Creates and returns a new annotation object.
188
-
188
+
189
189
Runs the 'beforeAnnotationCreated' hook to allow the new annotation to be
190
190
initialized or its creation prevented.
191
-
191
+
192
192
Runs the 'annotationCreated' hook when the new annotation has been created
193
193
by the store.
194
-
194
+
195
195
**Examples **:
196
-
196
+
197
197
::
198
-
198
+
199
199
registry.on('beforeAnnotationCreated', function (annotation) {
200
200
annotation.myProperty = 'This is a custom property';
201
201
});
202
202
registry.create({}); // Resolves to {myProperty: "This is a…"}
203
-
204
-
205
- :param Object annotation: An object from that to create an annotation.
203
+
204
+
205
+ :param Object annotation: An object from which to create an annotation.
206
206
:returns Promise: Resolves to annotation object when stored.
207
207
208
208
209
209
.. function :: annotator.storage.StorageAdapter.prototype.update(obj)
210
-
210
+
211
211
Updates an annotation.
212
-
212
+
213
213
Runs the 'beforeAnnotationUpdated' hook to allow an annotation to be
214
214
modified before being passed to the store, or for an update to be prevented.
215
-
215
+
216
216
Runs the 'annotationUpdated' hook when the annotation has been updated by
217
217
the store.
218
-
218
+
219
219
**Examples **:
220
-
220
+
221
221
::
222
-
222
+
223
223
annotation = {tags: 'apples oranges pears'};
224
224
registry.on('beforeAnnotationUpdated', function (annotation) {
225
225
// validate or modify a property.
226
226
annotation.tags = annotation.tags.split(' ')
227
227
});
228
228
registry.update(annotation)
229
229
// => Resolves to {tags: ["apples", "oranges", "pears"]}
230
-
230
+
231
231
:param Object annotation: An annotation object to update.
232
232
:returns Promise: Resolves to annotation object when stored.
233
233
234
234
235
235
.. function :: annotator.storage.StorageAdapter.prototype.delete(obj)
236
-
236
+
237
237
Deletes the annotation.
238
-
238
+
239
239
Runs the 'beforeAnnotationDeleted' hook to allow an annotation to be
240
240
modified before being passed to the store, or for the a deletion to be
241
241
prevented.
242
-
242
+
243
243
Runs the 'annotationDeleted' hook when the annotation has been deleted by
244
244
the store.
245
-
245
+
246
246
:param Object annotation: An annotation object to delete.
247
247
:returns Promise: Resolves to annotation object when deleted.
248
248
249
249
250
250
.. function :: annotator.storage.StorageAdapter.prototype.query(query)
251
-
251
+
252
252
Queries the store
253
-
253
+
254
254
:param Object query:
255
255
A query. This may be interpreted differently by different stores.
256
-
256
+
257
257
:returns Promise: Resolves to the store return value.
258
258
259
259
260
260
.. function :: annotator.storage.StorageAdapter.prototype.load(query)
261
-
261
+
262
262
Load and draw annotations from a given query.
263
-
264
- Runs the 'load' hook to allow plugins to respond to annotations being loaded.
265
-
263
+
264
+ Runs the 'load' hook to allow modules to respond to annotations being loaded.
265
+
266
266
:param Object query:
267
267
A query. This may be interpreted differently by different stores.
268
-
268
+
269
269
:returns Promise: Resolves when loading is complete.
270
+
271
+
0 commit comments