1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
[
{
"namespace": "manifest",
"types": [
{
"$extend": "PermissionPrivileged",
"choices": [
{
"type": "string",
"enum": ["urlbar"]
}
]
}
]
},
{
"namespace": "urlbar",
"description": "Use the <code>browser.urlbar</code> API to experiment with new features in the URLBar. Restricted to Mozilla privileged WebExtensions.",
"permissions": ["urlbar"],
"types": [
{
"id": "EngagementState",
"type": "string",
"enum": ["start", "engagement", "abandonment", "discard"],
"description": "The state of an engagement made with the urlbar by the user. <code>start</code>: The user has started an engagement. <code>engagement</code>: The user has completed an engagement by picking a result. <code>abandonment</code>: The user has abandoned their engagement, for example by blurring the urlbar. <code>discard</code>: The engagement ended in a way that should be ignored by listeners."
},
{
"id": "Query",
"type": "object",
"description": "A query performed in the urlbar.",
"properties": {
"isPrivate": {
"type": "boolean",
"description": "Whether the query's browser context is private."
},
"maxResults": {
"type": "integer",
"description": "The maximum number of results shown to the user."
},
"searchString": {
"type": "string",
"description": "The query's search string."
},
"sources": {
"type": "array",
"description": "List of acceptable source types to return.",
"items": {
"$ref": "SourceType"
}
}
}
},
{
"id": "Result",
"type": "object",
"description": "A result of a query. Queries can have many results. Each result is created by a provider.",
"properties": {
"payload": {
"type": "object",
"description": "An object with arbitrary properties depending on the result's type."
},
"source": {
"$ref": "SourceType",
"description": "The result's source."
},
"type": {
"$ref": "ResultType",
"description": "The result's type."
},
"suggestedIndex": {
"type": "integer",
"description": "Suggest a preferred position for this result within the result set.",
"optional": true,
"default": -1
}
}
},
{
"id": "ResultType",
"type": "string",
"enum": ["dynamic", "remote_tab", "search", "tab", "tip", "url"],
"description": "Possible types of results. <code>dynamic</code>: A result whose view and payload are specified by the extension. <code>remote_tab</code>: A synced tab from another device. <code>search</code>: A search suggestion from a search engine. <code>tab</code>: An open tab in the browser. <code>tip</code>: An actionable message to help the user with their query. <code>url</code>: A URL that's not one of the other types."
},
{
"id": "SearchOptions",
"type": "object",
"description": "Options to the <code>search</code> function.",
"properties": {
"focus": {
"type": "boolean",
"optional": true,
"default": true,
"description": "Whether to focus the input field and select its contents."
}
}
},
{
"id": "SourceType",
"type": "string",
"enum": ["bookmarks", "history", "local", "network", "search", "tabs"],
"description": "Possible sources of results. <code>bookmarks</code>: The result comes from the user's bookmarks. <code>history</code>: The result comes from the user's history. <code>local</code>: The result comes from some local source not covered by another source type. <code>network</code>: The result comes from some network source not covered by another source type. <code>search</code>: The result comes from a search engine. <code>tabs</code>: The result is an open tab in the browser or a synced tab from another device."
}
],
"properties": {
"engagementTelemetry": {
"$ref": "types.Setting",
"description": "Enables or disables the engagement telemetry."
}
},
"functions": [
{
"name": "closeView",
"type": "function",
"async": true,
"description": "Closes the urlbar view in the current window.",
"parameters": []
},
{
"name": "focus",
"type": "function",
"async": true,
"description": "Focuses the urlbar in the current window.",
"parameters": [
{
"name": "select",
"type": "boolean",
"optional": true,
"default": false,
"description": "If true, the text in the urlbar will also be selected."
}
]
},
{
"name": "search",
"type": "function",
"async": true,
"description": "Starts a search in the urlbar in the current window.",
"parameters": [
{
"name": "searchString",
"type": "string",
"description": "The search string."
},
{
"name": "options",
"$ref": "SearchOptions",
"optional": true,
"default": {},
"description": "Options for the search."
}
]
}
],
"events": [
{
"name": "onBehaviorRequested",
"type": "function",
"description": "Before a query starts, this event is fired for the given provider. Its purpose is to request the provider's behavior for the query. The listener should return a behavior in response. By default, providers are inactive, so if your provider should always be inactive, you don't need to listen for this event.",
"parameters": [
{
"name": "query",
"$ref": "Query",
"description": "The query for which the behavior is requested."
}
],
"extraParameters": [
{
"name": "providerName",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "The name of the provider whose behavior the listener returns."
}
],
"returns": {
"type": "string",
"enum": ["active", "inactive", "restricting"],
"description": "The behavior of the provider for the query."
}
},
{
"name": "onEngagement",
"type": "function",
"description": "This event is fired when the user starts and ends an engagement with the urlbar.",
"parameters": [
{
"name": "state",
"$ref": "EngagementState",
"description": "The state of the engagement."
}
],
"extraParameters": [
{
"name": "providerName",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "The name of the provider that will listen for engagement events."
}
]
},
{
"name": "onQueryCanceled",
"type": "function",
"description": "This event is fired for the given provider when a query is canceled. The listener should stop any ongoing fetch or creation of results and clean up its resources.",
"parameters": [
{
"name": "query",
"$ref": "Query",
"description": "The query that was canceled."
}
],
"extraParameters": [
{
"name": "providerName",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "The name of the provider that is creating results for the query."
}
]
},
{
"name": "onResultsRequested",
"type": "function",
"description": "When a query starts, this event is fired for the given provider if the provider is active for the query and there are no other providers that are restricting. Its purpose is to request the provider's results for the query. The listener should return a list of results in response.",
"parameters": [
{
"name": "query",
"$ref": "Query",
"description": "The query for which results are requested."
}
],
"extraParameters": [
{
"name": "providerName",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "The name of the provider whose results the listener returns."
}
],
"returns": {
"type": "array",
"items": {
"$ref": "Result"
},
"description": "The results that the provider fetched for the query."
}
},
{
"name": "onResultPicked",
"type": "function",
"description": "Typically, a provider includes a <code>url</code> property in its results' payloads. When the user picks a result with a URL, Firefox automatically loads the URL. URLs don't make sense for every result type, however. When the user picks a result without a URL, this event is fired. The provider should take an appropriate action in response. Currently the only applicable <code>ResultTypes</code> are <code>dynamic</code> and <code>tip</code>.",
"parameters": [
{
"name": "payload",
"type": "object",
"description": "The payload of the result that was picked."
},
{
"name": "elementName",
"type": "string",
"description": "If the result is a dynamic type, this is the name of the element in the result view that was picked. If the result is not a dynamic type, this is an empty string."
}
],
"extraParameters": [
{
"name": "providerName",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "The listener will be called for the results of the provider with this name."
}
]
}
]
}
]
|
