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
|
---
title: Interface com o Repositório de Complementos
slug: Mozilla/Add-ons/Interface-com-o-Repositorio_Add-on
translation_of: Mozilla/JavaScript_code_modules/Interfacing_with_the_Add-on_Repository
---
<p>{{ gecko_minversion_header("2.0") }}</p>
<p>The <a href="/en/Addons/Add-on_Repository" title="en/Addons/Add-on Repository">Add-on Repository</a> JavaScript code module makes it easy for your extension to interface with the AMO repository. You an use the code module to get lists of add-ons and even install new add-ons. This article provides some sample code that queries the recommended add-ons list on AMO and lets the user click a button to install an add-on from the list.</p>
<h2 id="Importando_o_módulo_de_código_do_repositório">Importando o módulo de código do repositório</h2>
<p>Before you can use the Add-on Repository API, you need to import the code module:</p>
<pre>Components.utils.import("resource://gre/modules/AddonRepository.jsm");
</pre>
<p>Having done this, you can then access the API through the resulting <code>AddonRepository</code> object.</p>
<h2 id="Habilitando_as_características_recomendadas">Habilitando as características recomendadas</h2>
<p>In current builds of Firefox 4, the recommendation API doesn't work because the preference for the URL to query to get recommended add-ons is not included by default; see {{ bug(628785) }}. To make the service work for the time being, you can use code like this when your extension starts up:</p>
<pre class="brush: js">var prefsService = Components.classes["@mozilla.org/preferences-service;1"]
.getService(Components.interfaces.nsIPrefService);
var prefBranch = prefsService.getBranch("extensions.");
var recUrl = "";
try {
recUrl = prefBranch.getCharPref("getAddons.recommended.url");
} catch(e) {
recurl = "";
}
if (recUrl == "") {
prefBranch.setCharPref("getAddons.recommended.url",
"https://services.addons.mozilla.org/%LOCALE%/%APP%/api/%API_VERSION%/list/recommended/all/%MAX_RESULTS%/%OS%/%VERSION%?src=firefox");
prefsService.savePrefFile(null);
}
</pre>
<p>This fetches the value of the <code>extensions.getAddons.recommended.url</code> preference, and, if the preference doesn't exist or has no value, sets the value of the preference to the correct one for the AMO site.</p>
<h2 id="Iniciando_uma_requisição">Iniciando uma requisição</h2>
<p>To start a search of the repository, you can use either of the following methods:</p>
<dl>
<dt>
<code>searchAddons()</code></dt>
<dd>
Queries the add-on repository for add-ons matching given search criteria.</dd>
<dt>
<code>retrieveRecommendedAddons()</code></dt>
<dd>
Retrieves a list of recommended add-ons, as determined by the AMO site administrators.</dd>
</dl>
<p>This example will use the latter, in order to randomly select a recommended add-on and offer to install it. However, the code to perform a search term based query would be very similar.</p>
<p>When the user clicks a toolbar button to initiate the query, the following code gets run to start the request:</p>
<pre>AddonRepository.retrieveRecommendedAddons(10, this);
</pre>
<p>This asks the repository to fetch up to 10 add-ons, using the object <code>this</code> as the target for callbacks. The callback object needs to implement the <a href="/en/Addons/Add-on_Repository/SearchCallback" title="en/Addons/Add-on Repository/SearchCallback"><code>SearchCallback</code></a> interface, providing the methods that get called when a search either fails or completes successfully.</p>
<h2 id="Manipulando_falsas_requisições">Manipulando falsas requisições</h2>
<p>The callback object must have a <a href="/en/Addons/Add-on_Repository/SearchCallback#searchFailed()" title="en/Addons/Add-on Repository/SearchCallback#searchFailed()"><code>searchFailed()</code></a> method; this gets called when a repository search fails to execute. The most common cause of failure (other than the search URL preference being incorrect) is if there is already a pending request, since only one request can be in progress at a time. For example:</p>
<pre class="brush: js">searchFailed: function() {
this.showNotification("I have no recommendations for you right now!",
"Oh noes!", null);
},
</pre>
<p>Here, we call a <code>showNotification()</code> method with some parameters that we'll look at shortly when we get to our <code>showNotification()</code> method below. The important thing to note is that this will handle the failure case.</p>
<h2 id="Manipulando_requisições_de_sucesso">Manipulando requisições de sucesso</h2>
<p>The callback object's searchSucceeded() method gets called when a search completes successfully. It receives a list of the matching addons, the number of add-ons returned, and the total number of add-ons that matched the query (in case the returned number is smaller than the requested number, for example).</p>
<p>For example:</p>
<pre class="brush: js">searchSucceeded: function(addons, addonCount, totalResults) {
var num = Math.floor(Math.random() * addonCount);
this.showNotification("Would you like to try the " + addons[num].name + " addon?",
"Install", addons[num].install);
},
</pre>
<p>This routine randomly selects one of the returned add-ons, then calls the previously mentioned <code>showNotification()</code> routine, passing in as parameters a prompt including the name of the returned add-on, a label for the button to show in the notification ("Install"), and the <a href="/en/Addons/Add-on_Manager/AddonInstall" title="en/Addons/Add-on Manager/AddonInstall"><code>AddonInstall</code></a> object that can be used with the Add-on Manager API to install the add-on.</p>
<h2 id="Instalando_Extensões">Instalando Extensões</h2>
<p>The <code>showNotification()</code> routine displays a notification box offering to install the recommended add-on, if one was found, or reports an error if the search failed:</p>
<pre class="brush: js">showNotification: function(prompt, button, installObj) {
this.install = installObj;
var box = PopupNotifications.show(gBrowser.selectedBrowser, "sample-popup",
prompt,
null, /* anchor ID */
{
label: button,
accessKey: "I",
callback: function() {
if (popupnotifications.install) {
popupnotifications.install.install();
} else {
PopupNotifications.remove(box);
}
}
},
null /* secondary action */
);
}
</pre>
<p>The code here starts by stashing the passed-in <a href="/en/Addons/Add-on_Manager/AddonInstall" title="en/Addons/Add-on Manager/AddonInstall"><code>AddonInstall</code></a> object for later use, then creates and displays the <a href="/en/JavaScript_code_modules/PopupNotifications.jsm" title="en/JavaScript code modules/PopupNotifications.jsm">pop-up notification</a> box with the text and button label passed into the method.</p>
<p><img alt="popup.png" class="internal default" src="/@api/deki/files/4918/=popup.png"></p>
<p>The pop-up callback function that gets called when the user clicks the button looks to see if there's a non-null <a href="/en/Addons/Add-on_Manager/AddonInstall" title="en/Addons/Add-on Manager/AddonInstall"><code>AddonInstall</code></a> object reference; if it's <code>null</code>, then the pop-up is displaying an error notification, so clicking the button simply dismisses the pop-up. Otherwise, the <a href="/en/Addons/Add-on_Manager/AddonInstall" title="en/Addons/Add-on Manager/AddonInstall"><code>AddonInstall</code></a> object's <a href="/en/Addons/Add-on_Manager/AddonInstall#install()" title="en/Addons/Add-on Manager/AddonInstall#install()"><code>install()</code></a> method is called to install the add-on.</p>
<p>This doesn't display any UI showing that the install is taking place; however, if you go to the Add-on Manager panel, you'll see the pending install listed among your add-ons.</p>
<p><img alt="install.png" class="internal default" src="/@api/deki/files/4919/=install.png"></p>
|
