diff options
Diffstat (limited to 'files/pt-br/mozilla/add-ons/interface-com-o-repositorio_add-on/index.html')
| -rw-r--r-- | files/pt-br/mozilla/add-ons/interface-com-o-repositorio_add-on/index.html | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/files/pt-br/mozilla/add-ons/interface-com-o-repositorio_add-on/index.html b/files/pt-br/mozilla/add-ons/interface-com-o-repositorio_add-on/index.html new file mode 100644 index 0000000000..8b1970eb97 --- /dev/null +++ b/files/pt-br/mozilla/add-ons/interface-com-o-repositorio_add-on/index.html @@ -0,0 +1,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> |