• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5[
6  {
7    "namespace": "bookmarks",
8    "description": "Use the <code>chrome.bookmarks</code> API to create, organize, and otherwise manipulate bookmarks. Also see <a href='override'>Override Pages</a>, which you can use to create a custom Bookmark Manager page.",
9    "properties": {
10      "MAX_WRITE_OPERATIONS_PER_HOUR": {
11        "value": 100,
12        "description": "The maximum number of <code>move</code>, <code>update</code>, <code>create</code>, or <code>remove</code> operations that can be performed each hour. Updates that would cause this limit to be exceeded fail."
13      },
14      "MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE": {
15        "value": 2,
16        "description": "The maximum number of <code>move</code>, <code>update</code>, <code>create</code>, or <code>remove</code> operations that can be performed each minute, sustained over 10 minutes. Updates that would cause this limit to be exceeded fail."
17      }
18    },
19    "types": [
20      {
21        "id": "BookmarkTreeNode",
22        "type": "object",
23        "description": "A node (either a bookmark or a folder) in the bookmark tree.  Child nodes are ordered within their parent folder.",
24        "properties": {
25          "id": {
26            "type": "string",
27            "minimum": 0,
28            "description": "The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted."
29          },
30          "parentId": {
31            "type": "string",
32            "minimum": 0,
33            "optional": true,
34            "description": "The <code>id</code> of the parent folder.  Omitted for the root node."
35          },
36          "index": {
37            "type": "integer",
38            "optional": true,
39            "description": "The 0-based position of this node within its parent folder."
40          },
41          "url": {
42            "type": "string",
43            "optional": true,
44            "description": "The URL navigated to when a user clicks the bookmark. Omitted for folders."
45          },
46          "title": {
47            "type": "string",
48            "description": "The text displayed for the node."
49          },
50          "dateAdded": {
51            "type": "number",
52            "optional": true,
53            "description": "When this node was created, in milliseconds since the epoch (<code>new Date(dateAdded)</code>)."
54          },
55          "dateGroupModified": {
56            "type": "number",
57            "optional": true,
58            "description": "When the contents of this folder last changed, in milliseconds since the epoch."
59          },
60          "unmodifiable": {
61            "type": "string",
62            "enum": ["managed"],
63            "optional": true,
64            "description": "Indicates the reason why this node is unmodifiable. The <var>managed</var> value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default)."
65          },
66          "children": {
67            "type": "array",
68            "optional": true,
69            "items": { "$ref": "BookmarkTreeNode" },
70            "description": "An ordered list of children of this node."
71          }
72        }
73      },
74      {
75        "id": "CreateDetails",
76        "description": "Object passed to the create() function.",
77        "inline_doc": true,
78        "type": "object",
79        "properties": {
80          "parentId": {
81            "type": "string",
82            "serialized_type": "int64",
83            "optional": true,
84            "description": "Defaults to the Other Bookmarks folder."
85          },
86          "index": {
87            "type": "integer",
88            "minimum": 0,
89            "optional": true
90          },
91          "title": {
92            "type": "string",
93            "optional": true
94          },
95          "url": {
96            "type": "string",
97            "optional": true
98          }
99        }
100      }
101    ],
102    "functions": [
103      {
104        "name": "get",
105        "type": "function",
106        "description": "Retrieves the specified BookmarkTreeNode(s).",
107        "parameters": [
108          {
109            "name": "idOrIdList",
110            "description": "A single string-valued id, or an array of string-valued ids",
111            "choices": [
112              {
113                "type": "string",
114                "serialized_type": "int64"
115              },
116              {
117                "type": "array",
118                "items": {
119                  "type": "string",
120                  "serialized_type": "int64"
121                },
122                "minItems": 1
123              }
124            ]
125          },
126          {
127            "type": "function",
128            "name": "callback",
129            "parameters": [
130              {
131                "name": "results",
132                "type": "array",
133                "items": { "$ref": "BookmarkTreeNode" }
134              }
135            ]
136          }
137        ]
138      },
139      {
140        "name": "getChildren",
141        "type": "function",
142        "description": "Retrieves the children of the specified BookmarkTreeNode id.",
143        "parameters": [
144          {
145            "type": "string",
146            "serialized_type": "int64",
147            "name": "id"
148          },
149          {
150            "type": "function",
151            "name": "callback",
152            "parameters": [
153              {
154                "name": "results",
155                "type": "array",
156                "items": { "$ref": "BookmarkTreeNode"}
157              }
158            ]
159          }
160        ]
161      },
162      {
163        "name": "getRecent",
164        "type": "function",
165        "description": "Retrieves the recently added bookmarks.",
166        "parameters": [
167          {
168            "type": "integer",
169            "minimum": 1,
170            "name": "numberOfItems",
171            "description": "The maximum number of items to return."
172          },
173          {
174            "type": "function",
175            "name": "callback",
176            "parameters": [
177              {
178                "name": "results",
179                "type": "array",
180                "items": { "$ref": "BookmarkTreeNode" }
181              }
182            ]
183          }
184        ]
185      },
186      {
187        "name": "getTree",
188        "type": "function",
189        "description": "Retrieves the entire Bookmarks hierarchy.",
190        "parameters": [
191          {
192            "type": "function",
193            "name": "callback",
194            "parameters": [
195              {
196                "name": "results",
197                "type": "array",
198                "items": { "$ref": "BookmarkTreeNode" }
199              }
200            ]
201          }
202        ]
203      },
204      {
205        "name": "getSubTree",
206        "type": "function",
207        "description": "Retrieves part of the Bookmarks hierarchy, starting at the specified node.",
208        "parameters": [
209          {
210            "type": "string",
211            "serialized_type": "int64",
212            "name": "id",
213            "description": "The ID of the root of the subtree to retrieve."
214          },
215          {
216            "type": "function",
217            "name": "callback",
218            "parameters": [
219              {
220                "name": "results",
221                "type": "array",
222                "items": { "$ref": "BookmarkTreeNode" }
223              }
224            ]
225          }
226        ]
227      },
228      {
229        "name": "search",
230        "type": "function",
231        "description": "Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.",
232        "parameters": [
233          {
234            "name": "query",
235            "description": "Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties <code>query</code>, <code>url</code>, and <code>title</code> may be specified and bookmarks matching all specified properties will be produced.",
236            "choices": [
237              {
238                "type": "string",
239                "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
240              },
241              {
242                "type": "object",
243                "description": "An object specifying properties and values to match when searching. Produces bookmarks matching all properties.",
244                "properties": {
245                  "query": {
246                    "type": "string",
247                    "optional": true,
248                    "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
249                  },
250                  "url": {
251                    "type": "string",
252                    "optional": true,
253                    "description": "The URL of the bookmark; matches verbatim. Note that folders have no URL."
254                  },
255                  "title": {
256                    "type": "string",
257                    "optional": true,
258                    "description": "The title of the bookmark; matches verbatim."
259                  }
260                }
261              }
262            ]
263          },
264          {
265            "type": "function",
266            "name": "callback",
267            "parameters": [
268              {
269                "name": "results",
270                "type": "array",
271                "items": { "$ref": "BookmarkTreeNode" }
272              }
273            ]
274          }
275        ]
276      },
277      {
278        "name": "create",
279        "type": "function",
280        "description": "Creates a bookmark or folder under the specified parentId.  If url is NULL or missing, it will be a folder.",
281        "parameters": [
282          {
283            "$ref": "CreateDetails",
284            "name": "bookmark"
285          },
286          {
287            "type": "function",
288            "name": "callback",
289            "optional": true,
290            "parameters": [
291              {
292                "name": "result",
293                "$ref": "BookmarkTreeNode"
294              }
295            ]
296          }
297        ]
298      },
299      {
300        "name": "move",
301        "type": "function",
302        "description": "Moves the specified BookmarkTreeNode to the provided location.",
303        "parameters": [
304          {
305            "type": "string",
306            "serialized_type": "int64",
307            "name": "id"
308          },
309          {
310            "type": "object",
311            "name": "destination",
312            "properties": {
313              "parentId": {
314                "type": "string",
315                "optional": true
316              },
317              "index": {
318                "type": "integer",
319                "minimum": 0,
320                "optional": true
321              }
322            }
323          },
324          {
325            "type": "function",
326            "name": "callback",
327            "optional": true,
328            "parameters": [
329              {
330                "name": "result",
331                "$ref": "BookmarkTreeNode"
332              }
333            ]
334          }
335        ]
336      },
337      {
338        "name": "update",
339        "type": "function",
340        "description": "Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged.  <b>Note:</b> Currently, only 'title' and 'url' are supported.",
341        "parameters": [
342          {
343            "type": "string",
344            "serialized_type": "int64",
345            "name": "id"
346          },
347          {
348            "type": "object",
349            "name": "changes",
350            "properties": {
351              "title": {
352                "type": "string",
353                "optional": true
354              },
355              "url": {
356                "type": "string",
357                "optional": true
358              }
359            }
360          },
361          {
362            "type": "function",
363            "name": "callback",
364            "optional": true,
365            "parameters": [
366              {
367                "name": "result",
368                "$ref": "BookmarkTreeNode"
369              }
370            ]
371          }
372        ]
373      },
374      {
375        "name": "remove",
376        "type": "function",
377        "description": "Removes a bookmark or an empty bookmark folder.",
378        "parameters": [
379          {
380            "type": "string",
381            "serialized_type": "int64",
382            "name": "id"
383          },
384          {
385            "type": "function",
386            "name": "callback",
387            "optional": true,
388            "parameters": []
389          }
390        ]
391      },
392      {
393        "name": "removeTree",
394        "type": "function",
395        "description": "Recursively removes a bookmark folder.",
396        "parameters": [
397          {
398            "type": "string",
399            "serialized_type": "int64",
400            "name": "id"
401          },
402          {
403            "type": "function",
404            "name": "callback",
405            "optional": true,
406            "parameters": []
407          }
408        ]
409      },
410      {
411        "name": "import",
412        "type": "function",
413        "description": "Imports bookmarks from a chrome html bookmark file",
414        "nodoc": "true",
415        "parameters": [
416          {
417            "type": "function",
418            "name": "callback",
419            "optional": true,
420            "parameters": []
421          }
422        ]
423      },
424      {
425        "name": "export",
426        "type": "function",
427        "description": "Exports bookmarks to a chrome html bookmark file",
428        "nodoc": "true",
429        "parameters": [
430          {
431            "type": "function",
432            "name": "callback",
433            "optional": true,
434            "parameters": []
435          }
436        ]
437      }
438    ],
439    "events": [
440      {
441        "name": "onCreated",
442        "type": "function",
443        "description": "Fired when a bookmark or folder is created.",
444        "parameters": [
445          {
446            "type": "string",
447            "name": "id"
448          },
449          {
450            "$ref": "BookmarkTreeNode",
451            "name": "bookmark"
452          }
453        ]
454      },
455      {
456        "name": "onRemoved",
457        "type": "function",
458        "description": "Fired when a bookmark or folder is removed.  When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.",
459        "parameters": [
460          {
461            "type": "string",
462            "name": "id"
463          },
464          {
465            "type": "object",
466            "name": "removeInfo",
467            "properties": {
468              "parentId": { "type": "string" },
469              "index": { "type": "integer" }
470            }
471          }
472        ]
473      },
474      {
475        "name": "onChanged",
476        "type": "function",
477        "description": "Fired when a bookmark or folder changes.  <b>Note:</b> Currently, only title and url changes trigger this.",
478        "parameters": [
479          {
480            "type": "string",
481            "name": "id"
482          },
483          {
484            "type": "object",
485            "name": "changeInfo",
486            "properties": {
487              "title": { "type": "string" },
488              "url": {
489                "type": "string",
490                "optional": true
491              }
492            }
493          }
494        ]
495      },
496      {
497        "name": "onMoved",
498        "type": "function",
499        "description": "Fired when a bookmark or folder is moved to a different parent folder.",
500        "parameters": [
501          {
502            "type": "string",
503            "name": "id"
504          },
505          {
506            "type": "object",
507            "name": "moveInfo",
508            "properties": {
509              "parentId": { "type": "string" },
510              "index": { "type": "integer" },
511              "oldParentId": { "type": "string" },
512              "oldIndex": { "type": "integer" }
513            }
514          }
515        ]
516      },
517      {
518        "name": "onChildrenReordered",
519        "type": "function",
520        "description": "Fired when the children of a folder have changed their order due to the order being sorted in the UI.  This is not called as a result of a move().",
521        "parameters": [
522          {
523            "type": "string",
524            "name": "id"
525          },
526          {
527            "type": "object",
528            "name": "reorderInfo",
529            "properties": {
530              "childIds": {
531                "type": "array",
532                "items": { "type": "string" }
533              }
534            }
535          }
536        ]
537      },
538      {
539        "name": "onImportBegan",
540        "type": "function",
541        "description": "Fired when a bookmark import session is begun.  Expensive observers should ignore onCreated updates until onImportEnded is fired.  Observers should still handle other notifications immediately.",
542        "parameters": []
543      },
544      {
545        "name": "onImportEnded",
546        "type": "function",
547        "description": "Fired when a bookmark import session is ended.",
548        "parameters": []
549      }
550    ]
551  }
552]
553