canmove, Confirmed users
737
edits
Jetpack/Release Notes/1.0: Difference between revisions
→Known Issues
(→About) |
|||
| (41 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
== About == | == About == | ||
| Line 7: | Line 4: | ||
This is the first stable release of the Add-on SDK. | This is the first stable release of the Add-on SDK. | ||
The Add-on SDK makes it easy to develop add-ons | The Add-on SDK makes it easy to develop Firefox add-ons using JavaScript, HTML, and CSS. This means you no longer need to understand how to work with the [https://developer.mozilla.org/en/xul XUL] or [https://developer.mozilla.org/en/xpcom XPCOM] to write add-ons. | ||
Add-ons developed with the SDK are: | Add-ons developed with the SDK are: | ||
| Line 13: | Line 10: | ||
* '''[https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions restartless]''': so users can try them out without interrupting their browsing | * '''[https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions restartless]''': so users can try them out without interrupting their browsing | ||
* '''forward-compatible''': will continue to work as new versions of Firefox are released. In particular they are already structured to work with [https://wiki.mozilla.org/Electrolysis Electrolysis], the forthcoming architecture in which Firefox uses separate | * '''forward-compatible''': will continue to work as new versions of Firefox are released. In particular they are already structured to work with [https://wiki.mozilla.org/Electrolysis Electrolysis], the forthcoming architecture in which Firefox uses separate processes to display the browser UI, handle web content and execute add-ons. | ||
To learn more about the SDK, you can browse the [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/ documentation]. | |||
== Major Features == | |||
The SDK provides two things: | |||
* a set of JavaScript APIs which you can use to create your user interface, and to interact with web content and the browser | |||
* a command-line tool called <code>cfx</code> which takes care of packaging your code into an add-on, leaving you free to concentrate on the code itself | |||
=== JavaScript APIs === | |||
For an overview of the APIs check out the [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/dev-guide/addon-development/api-modules.html API introduction] in the online documentation. | |||
In 1.0 we've defined a limited set of supported APIs which cover the following categories: | |||
* '''building a UI''': defining dialogs, widgets, context menu items, and notification alerts | |||
* '''interacting with the web''': fetching, examining, and modifying web pages | |||
* '''interacting with the browser''': accessing the clipboard, getting information about the set of open windows and tabs, and handling private browsing | |||
* some basic utility functions like persistent storage | |||
There are additional APIs which you can use, but we don't yet consider them stable, so we might change them in incompatible ways in future releases. | |||
The SDK is extensible by design: so it's possible for you to create your own APIs that expose additional functionality, and make them available to other developers. [https://wiki.mozilla.org/Labs/Jetpack/Modules Here's a list] of some of these third party modules. | |||
=== cfx === | |||
<code>cfx</code> is the command-line tool the SDK supplies for: | |||
* '''initializing your add-on''': creating its skeleton structure | |||
* '''running your add-on''' to smoke test it without needing to going through the packaging/installation cycle | |||
* '''unit testing''' | |||
* '''packaging''' your add-on as an [https://developer.mozilla.org/en/XPI installable XPI file] | |||
== Installation == | == Installation == | ||
To use the SDK you download and install it locally. You'll need [http://python.org Python] version 2.5 or 2.6, and Firefox version 4 or higher. | |||
Obtain the SDK in your favorite compression format: | Obtain the SDK in your favorite compression format: | ||
* [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1. | * [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0.tar.gz addon-sdk-1.0.tar.gz] | ||
* [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1. | * [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0.zip addon-sdk-1.0.zip] | ||
Then unpack the archive, open the <tt>addon-sdk-1.0/README.txt</tt> file, and follow its instructions. | |||
== Getting Help == | |||
If you can't find the answer to your question in the documentation: | |||
* see if your question is answered in the [https://wiki.mozilla.org/Labs/Jetpack/FAQ FAQ] | |||
* SDK users and project team members discuss problems and proposals on the [http://groups.google.com/group/mozilla-labs-jetpack/topics project mailing list]. Someone else may have had the same problem you do, so try searching the list. You're welcome to post a question, too. | |||
* ask other SDK users and developers in [http://mibbit.com/?channel=%23jetpack&server=irc.mozilla.org #jetpack] on [http://irc.mozilla.org/ Mozilla's IRC network] | |||
== Known Issues == | |||
See the [https://bugzilla.mozilla.org/buglist.cgi?order=Bug%20Number&bug_status=__open__&product=Add-on%20SDK complete list of known issues and requests for enhancement]. We've listed some of the more important issues separately below. | |||
'''[https://bugzilla.mozilla.org/show_bug.cgi?id=636268 Bug 636268]''' | |||
If your add-on has a long name, and the path to your Firefox profile is long enough, then the XPI installation process will try to create an intermediate file with a name longer than the maximum supported length on some Windows systems. If that happens you may get an error like: | |||
<pre> | |||
"<your add-on> could not be installed because Firefox cannot modify the needed file" | |||
</pre> | |||
The main fix for this will be [https://bugzilla.mozilla.org/show_bug.cgi?id=638742 bug 638742], which is to stop unpacking the XPI completely. When that is done, none of the pathnames will matter: they'll all stay safely trapped inside the zipfile. At that point, the name of the XPI file and the length of the profile directory will be the only issues. | |||
Until then, the best advice is to use shorter package names or install Firefox higher up the directory tree so the profile directory's absolute path is shorter. | |||
'''[https://bugzilla.mozilla.org/show_bug.cgi?id=663480 Bug 663480]''' | |||
The SDK automatically includes a dependency on the packages supplied with the SDK such as [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/packages/addon-kit/addon-kit.html <code>addon-kit</code>] and [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/packages/api-utils/api-utils.html <code>api-utils</code>]. This means that you can <code>require()</code> modules in the SDK such as [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/packages/addon-kit/docs/widget.html <code>widget</code>] without having to specify <code>addon-kit</code> as a dependency. | |||
You can also use modules from other packages, such as the packages listed [https://wiki.mozilla.org/Jetpack/Modules here], by including a reference to the package in your [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/dev-guide/addon-development/package-spec.html <code>package.json</code>] file. | |||
However, if you do add any dependencies to <code>package.json</code>, then the SDK will no longer add <code>addon-kit</code> or <code>api-utils</code> automatically, and you must add them manually if you want to include their modules. | |||
'''[https://bugzilla.mozilla.org/show_bug.cgi?id=663048 Bug 663048]''' | |||
The SDK will give an error if your package name contains spaces or Unicode characters. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=627432 Bug 627432] ''' | |||
If your add-on stores data using the [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/packages/addon-kit/docs/simple-storage.html simple-storage] API, the data is not cleaned up when your add-on is uninstalled. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=656037 Bug 656037] ''' | |||
Some core JavaScript functions, such as [https://developer.mozilla.org/en/DOM/window.btoa <code>btoa()</code>], are not available to add-on code. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=581982 Bug 581982] ''' | |||
<code>selection.text</code> returns null instead of the selected text when the selection is in a text box or text area. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=571049 Bug 571049] ''' | |||
If an add-on is uninstalled while it's disabled, it's not notified of uninstall. If the add-on needs to do some special cleanup on uninstall, like removing persistent storage such as a file, this won't be possible if it has been disabled. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=571843 Bug 571843] ''' | |||
<code>bin\activate</code> fails to find 64-bit Python on 64-bit Windows environments, as it assumes Python is 32-bit. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=574563 Bug 574563] ''' | |||
On Windows, <code>bin\activate</code> sometimes gives the following error: | |||
"Error: The system was unable to find the specified registry key or value" | |||
This does not seem to affect the functioning of the SDK. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=660862 Bug 660862] ''' | |||
By default, widgets are placed on the add-on bar, and given a height to match the height of that bar. If the user moves the widget to a different toolbar, and that toolbar has a different height, the widget's height is not updated accordingly. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=660857 Bug 660857] ''' | |||
A widget containing HTML content gets no icon in the [http://support.mozilla.com/en-US/kb/how-do-i-customize-toolbars Customize Toolbar Window]. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=660860 Bug 660860] ''' | |||
When a user removes a widget from the toolbar its <code>detach</code> event does not get sent. | |||
''' [https://bugzilla.mozilla.org/show_bug.cgi?id=661884 Bug 661884] ''' | |||
Selection events for a page are not sent if the page did not fully load (for example, because the user stopped the page loading). | |||
== Notable Changes Since 1.0b5 == | |||
=== [https://bugzilla.mozilla.org/show_bug.cgi?id=601295 Bug 601295]: Content script access to the DOM is now proxied === | |||
We've changed the way content scripts interact with web pages, in order to improve security. | |||
Previously, content scripts that accessed DOM objects in the page would frequently access the same objects as those being accessed by the page. This gives rise to two problems: | |||
# many changes to the page would be visible to the page, making it obvious to the page that an add-on was modifying it. | |||
# a malicious page might redefine functions and properties of them so they don't do what the add-on expects. For example, if a content script calls <code>document.getElementById()</code> to retrieve a DOM element, then a malicious page could redefine its behavior to return something unexpected. | |||
To deal with these problems, DOM objects like the global window object are now implemented in a way that ensures that content scripts that access those objects will get the native implementations of their properties and methods. | |||
Content scripts that modify those DOM objects will modify a proxy object instead of the real object. | |||
Finally: sometimes add-ons need access to custom, document-defined JavaScript objects. For example, GMail provides a custom JavaScript API which would not be accessible using the proxy. To meet use cases like this, in [https://bugzilla.mozilla.org/show_bug.cgi?id=660780 bug 660780] we've provided access to the unwrapped window via a global <code>unsafeWindow</code> object in content scripts. But note that this is experimental and may change or be removed completely in future releases. | |||
=== Cross-site XmlHttpRequests are no longer permitted in content scripts in Firefox 5 === | |||
Firefox 4 allowed content scripts to make cross-site requests using <code>XmlHttpRequest</code>. So, for example, if you injected a content script into http://www.mozilla.org/, the content script would be allowed to send a request to http://www.google.com/ using <code>XmlHttpRequest</code>. | |||
It was always the intention that cross-site requests should '''not''' be possible in a content script, and in Firefox 5 this is no longer possible. | |||
=== [https://github.com/mozilla/addon-sdk/commit/658fb89ca4d3dc4a8cfb9616ae873e979a7f3955 Changes to linker search behavior] === | |||
This changes the way the SDK's linker resolves <code>require()</code> statements, making it more compatible with [http://www.commonjs.org/ CommonJS] and [http://npmjs.org/ NPM]. | |||
It's documented in the [https://github.com/mozilla/addon-sdk/commit/658fb89ca4d3dc4a8cfb9616ae873e979a7f3955 GitHub commit] and in the [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/dev-guide/addon-development/module-search.html Module Search] guide in the SDK. | |||
=== [https://bugzilla.mozilla.org/show_bug.cgi?id=653256 Bug 653256]: Make smaller XPIs by only including modules that are actually used === | |||
Previously, if you used any modules in a package, then your XPI would include all modules in the package. With this change only modules you actually use get included. | |||
Note that this is behavior is not currently the default: to enable it you need to pass the experimental <code>--strip-xpi</code> option to <code>cfx</code>. | |||
=== [https://bugzilla.mozilla.org/show_bug.cgi?id=615921 <code>timers</code>] and [https://bugzilla.mozilla.org/show_bug.cgi?id=615244 <code>self</code>] modules are moved from api-utils to addon-kit === | |||
This should not affect anyone currently using either module, but reflects the fact that both of these modules are heavily used by people writing add-ons. | |||
== Feedback and Bug Reports == | == Feedback and Bug Reports == | ||
We'd love to hear any feedback you have regarding this release! You can post it to the [http://groups.google.com/group/mozilla-labs-jetpack discussion group] or [https://bugzilla.mozilla.org/enter_bug.cgi?product=Add-on%20SDK&version=1. | We'd love to hear any feedback you have regarding this release! You can post it to the [http://groups.google.com/group/mozilla-labs-jetpack discussion group] or [https://bugzilla.mozilla.org/enter_bug.cgi?product=Add-on%20SDK&version=1.0 report a bug]. | ||