Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Tutorial rework #347

Closed
wants to merge 74 commits into from

5 participants

@wbamberg
Owner

This branch includes structural changes to the SDK documentation as well as lots of new tutorial content. Because there's a lot to look at, I'll ask for review of the various pieces in separate bugs.

wbamberg added some commits
@wbamberg wbamberg start at reworking tutes eca2ba8
@wbamberg wbamberg Merge branch 'master' into tutorial-rework 0d90b64
@wbamberg wbamberg ... 0afcba6
@wbamberg wbamberg ... b9f549a
@wbamberg wbamberg ... f9f9c54
@wbamberg wbamberg ... 86fe870
@wbamberg wbamberg Merge branch 'master' into tutorial-rework b73d852
@wbamberg wbamberg clean up tutorials sidebar 4dbe6d0
@wbamberg wbamberg updated links in tutorials page 53e3065
@wbamberg wbamberg edits to main welcome page to point at Tutorials 0ad0b2b
@wbamberg wbamberg Merge branch 'master' into tutorial-rework 5edec8f
@wbamberg wbamberg ... b6ebe12
@wbamberg wbamberg Merge remote-tracking branch 'origin/tutorial-rework' into tutorial-r…
…ework
640dc47
@wbamberg wbamberg added two-column layout for tutorial list 2950ab7
@wbamberg wbamberg Merge remote-tracking branch 'origin/master' into tutorial-rework f65fe13
@wbamberg wbamberg fix merge conflicts 24410f9
@wbamberg wbamberg some style changes 0524059
@wbamberg wbamberg cange background colour 5b7d0bf
@wbamberg wbamberg add 2 missing tutorial files 5f797cc
@wbamberg wbamberg Merge branch 'master' into tutorial-rework 36bdcf1
@wbamberg wbamberg start toolbar tutorial e658663
@wbamberg wbamberg style changes 438607d
@wbamberg wbamberg Merge remote-tracking branch 'main/master' into tutorial-rework af31c0a
@wbamberg wbamberg ... 048c563
@wbamberg wbamberg ... 6f6a831
@wbamberg wbamberg added a bunch more mini-tutorials 21bf854
@wbamberg wbamberg added links for 'dev techniques'; more style updates c3fc979
@wbamberg wbamberg fix merge conflict e88b78f
@wbamberg wbamberg added logging tutorial; added padding to code snippets to match <pre>…
… formatting
3003e53
@wbamberg wbamberg made prerequisites an aside 744827e
@wbamberg wbamberg ... 3e78983
@wbamberg wbamberg added reusable modules tute 9d9f6f6
@wbamberg wbamberg Merge remote branch 'origin/tutorial-rework' into tutorial-rework fda8f7f
@wbamberg wbamberg finished(?) tutorial page, reorged guide page b6b8715
@wbamberg wbamberg update main page cd51011
@wbamberg wbamberg add dividers between packages 7d5b917
@wbamberg wbamberg ... 7d97d4a
@wbamberg wbamberg ... bd33405
@wbamberg wbamberg ... 3e7cc53
@wbamberg wbamberg Merge remote-tracking branch 'main/master' into tutorial-rework d1d7f46
@wbamberg wbamberg ... 51862ac
@wbamberg wbamberg ... c1ebc44
@wbamberg wbamberg ... a2b87c0
@wbamberg wbamberg ... 55f5c72
@wbamberg wbamberg get cfx testcfx to work 0055ef9
@wbamberg wbamberg ... e041ea5
@wbamberg wbamberg ... 674f5d1
@wbamberg wbamberg reposition image for widget tutorial eb8439c
@wbamberg wbamberg expunge reference to wikipanel cca18f2
@wbamberg wbamberg fix merge conflicts 3661b4a
@wbamberg wbamberg added mobile doc fd59437
@wbamberg wbamberg remove some tutorials we don't want to add 7394f10
doc/dev-guide-source/addon-development/commonjs.md
((62 lines not shown))
+likely to use these if you are building your own modules that
+implement new APIs, thus extending the SDK itself.
+
+* privileged modules that expose powerful low-level capabilities
+such as [tab-browser](packages/api-utils/docs/tab-browser.html),
+[xhr](packages/api-utils/docs/xhr.html), and
+[xpcom](packages/api-utils/docs/xpcom.html). You can use these
+modules in your add-on if you need to, but should be aware that
+the cost of privileged access is the need to take more elaborate
+security precautions. In many cases these modules have simpler,
+more restricted analogs in the high-level addon-kit package (for
+example, [tabs](packages/addon-kit/docs/tabs.html) or
+[request](packages/addon-kit/docs/request.html)).
+
+These modules are still in active development, and we expect to
+make incompatible changes to them in future releases.
@warner Owner
warner added a note

you might expand this a bit, something like ".. which means, if you use these modules from your code, you may need to rewrite your code for future versions of the SDK", but with better words :)

@ochameau Owner
ochameau added a note

+1 and may be highlight this paragraph with some bold or yellow or anything that would ensure developers reading this part :)

(Same note here, do not forget modifying low-level-apis.md)

@Gozala Owner
Gozala added a note
  • 1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
doc/dev-guide-source/addon-development/commonjs.md
((28 lines not shown))
+
+So the modules which implement the SDK's APIs are
+collected into three packages, `addon-kit`, `api-utils` and `test-harness`.
+
+### <a name="addon-kit">addon-kit</a> ###
+
+Modules in the `addon-kit` package implement high-level APIs for
+building add-ons:
+
+* creating user interfaces
+* interacting with the web
+* interacting with the browser
+
+These modules are "supported": meaning that they are relatively
+stable, and that we'll avoid making incompatible changes to them
+unless absolutely necessary.
@ochameau Owner
ochameau added a note

We should be able to say stable instead of relatively stable?
As we really want them to be stable!

(Do not forget to update high-level-apis.md if you modify this)

@Gozala Owner
Gozala added a note

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
doc/dev-guide-source/addon-development/commonjs.md
((48 lines not shown))
+### <a name="api-utils">api-utils</a> ###
+
+Modules in the `api-utils` package implement low-level APIs. These
+modules fall roughly into three categories:
+
+* fundamental utilities such as
+[collection](packages/api-utils/docs/collection.html) and
+[url](packages/api-utils/docs/url.html). Many add-ons are likely to
+want to use modules from this category.
+
+* building blocks for higher level modules, such as
+[events](packages/api-utils/docs/events.html),
+[worker](packages/api-utils/docs/content/worker.html), and
+[api-utils](packages/api-utils/docs/api-utils.html). You're more
+likely to use these if you are building your own modules that
+implement new APIs, thus extending the SDK itself.
@ochameau Owner
ochameau added a note

Irakli is currently working on refactoring all APIs in order to use Base and Namespace instead of api-utils, traits, light-traits, ...
So that we should mention api-utils anymore.
I'd say Base, NameSpace and Events are the top three API to look into, if you want to build a module "like in the SDK".
Or if you want to learn how SDK works. If you start looking at future code (after irakli's rewrite), you will have to understand these two modules.

Note that events module is going to be replace by two new ones calles events/core and events/target. (Still living in a pull request).

@Gozala Owner
Gozala added a note

I think @ochameau outlined it correctly. I would also remove api-utils from the list and hopefully from code base sometime soon & would put namespace and event/target to the top. Not sure about event/core though maybe also worth mentioning. Before events was used for both
emitting events and listening events and now it's event/target for listening and event/core for emitting.

P.S.: Those APIs have already landed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
doc/dev-guide-source/addon-development/commonjs.md
((59 lines not shown))
+[events](packages/api-utils/docs/events.html),
+[worker](packages/api-utils/docs/content/worker.html), and
+[api-utils](packages/api-utils/docs/api-utils.html). You're more
+likely to use these if you are building your own modules that
+implement new APIs, thus extending the SDK itself.
+
+* privileged modules that expose powerful low-level capabilities
+such as [tab-browser](packages/api-utils/docs/tab-browser.html),
+[xhr](packages/api-utils/docs/xhr.html), and
+[xpcom](packages/api-utils/docs/xpcom.html). You can use these
+modules in your add-on if you need to, but should be aware that
+the cost of privileged access is the need to take more elaborate
+security precautions. In many cases these modules have simpler,
+more restricted analogs in the high-level addon-kit package (for
+example, [tabs](packages/addon-kit/docs/tabs.html) or
+[request](packages/addon-kit/docs/request.html)).
@ochameau Owner
ochameau added a note

I think that multiple people are searching for window-utils and tab-browser when they want to get access to chrome DOM nodes, because high-level API doesn't expose them, nor implement a modifier for what they want to achieve (UI listener or modification). We may give some extra-visiblity to these ones. They fit in this "expose low-level access and comes with longer review". But we might be able to help some developers to find those easily.

@wbamberg Owner
wbamberg added a note

To highlight these important low-level modules, I'd like to have a task-based tutorial, like "Displaying a Popup" and all the other here, that describes some of the things people need to use these modules for. For example, maybe, "Listening to chrome events" or something.

In this new structure I no longer split the tutorials into "Developer" and "Internal": they are all together, and I'll flag each tutorial if it uses low-level modules.

So if you can think of important things people want to do, that need tutorials and require low-level modules, go ahead and raise a bug for it.

@Gozala Owner
Gozala added a note

I would in fact don't publicize window-utils and tab-browser even further specially the later one. There lot's of staff we wanted to deprecate for ages and tab-browser was left over for test, so I would not like to increase audience for these modules.

Also I think future we want to be at may be relevant here: #353 (comment)

@ochameau Owner
ochameau added a note

@gozala, you are right about tab-browser it isn't necessary relevant as we really want to drop this one. It just sounds like we let them wander until we come up with nice low-level modules.
That's ok to let some fuzzyness for tabs and so avoid talking about tab-browser. But I won't say the same thing about window-utils and its WindowTracker class which has been proven to be usefull and working good for most addons that used it!

@wbamberg if you want some examples, you can do whatever you like with browser UI by using WindowTracker. Here is a set of real-life examples:

@wbamberg Owner
wbamberg added a note
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ev-guide-source/addon-development/third-party-apis.md
@@ -0,0 +1,3 @@
+# Third-Party APIs #
+
+This section lists modules which you've downloaded and added to your SDK installation.
@ochameau Owner
ochameau added a note

I don't see any link to this file, is this accessible somewhere?

@wbamberg Owner
wbamberg added a note

It only becomes visible if you actually install a third-party package.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...de-source/addon-development/tutorials/adding-menus.md
@@ -66,7 +45,8 @@ Dependencies api-utils, vold-utils
</pre>
This tells us that we need to install the `vold-utils` package,
-which we can do by downloading it from [its source repository](https://github.com/erikvold/vold-utils-jplib)
+which we can do by downloading it from
+[its source repository](https://github.com/erikvold/vold-utils-jplib)
@ochameau Owner
ochameau added a note

Shouldn't we do the same than menuitems-jplib and give a link to a precise tarball revision, instead of project home on github?
It feels safier and easier for people not used to git/github.

@wbamberg Owner
wbamberg added a note

Yes!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((25 lines not shown))
+ const widgets = require("widget");
+ const tabs = require("tabs");
+
+ var widget = widgets.Widget({
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: "http://www.mozilla.org/favicon.ico",
+ onClick: function() {
+ tabs.open("http://www.mozilla.org/");
+ }
+ });
+
+The widget is added to the "Add-on Bar" at the bottom of the browser window:
+
+<img class="image-right" src="static-files/media/screenshots/widget-mozilla.png"
+alt="Mozilla icon widget" />
@ochameau Owner
ochameau added a note

This image looks buggy as it is displayed at the same level than Specifying the Icon header.
This image shouldn't be part of the next part, so that Specifying the Icon paragraph will be really distinct from the introduction paragraph.
I should look better if you move the <img> before The widget is added to the "Add-on Bar" at the bottom of the browser window:, and if put <div style="clear:both"></div> before ## Specifying the Icon ##

You might be able to fix it overall documentation by adding clear: both; or clear: right; to header's class

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((69 lines not shown))
+
+## Responding To the User ##
+
+You can listen for `click`, `mouseover`, and `mouseout` events by assigning
+functions to the corresponding widget properties. The widget example above
+assigns a listener to the `click` event using the `onClick` option, and
+there are similar `onMouseover` and `onMouseout` options.
+
+To handle user interaction in more detail, you can attach a content
+script to the widget. Your add-on script and the content script can't
+directly access each other's variables or call each other's functions, but
+they can send each other messages.
+
+Here's an example. The widget's built-in `onClick` property does not
+distinguish between left and right mouse clicks, so to do this we need
+to use a script. The script looks like this:
@ochameau Owner
ochameau added a note

we need to use a script. -> we need to use a content script.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((65 lines not shown))
+ });
+
+You can change the icon at any time by setting the widget's `contentURL`
+property.
+
+## Responding To the User ##
+
+You can listen for `click`, `mouseover`, and `mouseout` events by assigning
+functions to the corresponding widget properties. The widget example above
+assigns a listener to the `click` event using the `onClick` option, and
+there are similar `onMouseover` and `onMouseout` options.
+
+To handle user interaction in more detail, you can attach a content
+script to the widget. Your add-on script and the content script can't
+directly access each other's variables or call each other's functions, but
+they can send each other messages.
@ochameau Owner
ochameau added a note

It may be usefull to display an aside note that provide a link to content script page?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((78 lines not shown))
+script to the widget. Your add-on script and the content script can't
+directly access each other's variables or call each other's functions, but
+they can send each other messages.
+
+Here's an example. The widget's built-in `onClick` property does not
+distinguish between left and right mouse clicks, so to do this we need
+to use a script. The script looks like this:
+
+ this.addEventListener('click', function(event) {
+ if(event.button == 0 && event.shiftKey == false)
+ self.port.emit('left-click');
+
+ if(event.button == 2 || (event.button == 0 && event.shiftKey == true))
+ self.port.emit('right-click');
+ event.preventDefault();
+ }, true);
@ochameau Owner
ochameau added a note

this sounds very magical. window looks more common.

@Gozala Owner
Gozala added a note

I agree window would be better.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((120 lines not shown))
+ });
+
+ widget.port.on("left-click", function(){
+ console.log("left-click");
+ });
+
+ widget.port.on("right-click", function(){
+ console.log("right-click");
+ });
+
+Now execute `cfx run` again, and try right- and left-clicking on the button.
+You should see the corresponding string written to the command shell.
+
+(You'll also see the standard add-on bar context menu appear when you
+right-click: this is a
+[bug in the SDK](https://bugzilla.mozilla.org/show_bug.cgi?id=626326).)
@ochameau Owner
ochameau added a note

Oh I fixed this bug without landing it ... I'll land it right after I end up this review, so that you should be able to remove this, right?

@wbamberg Owner
wbamberg added a note

Very pleased to see this bug fixed!

@ochameau Owner
ochameau added a note

RESOLVED FIXED!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((11 lines not shown))
+[basics of `cfx`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html).
+</span>
+
+To add a button to the toolbar, use the
+[`widget`](packages/addon-kit/docs/widget.html) module.
+
+The default add-on created by `cfx init`
+uses a widget, so we'll start with that as an example. If you haven't already
+followed the tutorial introducing
+[`cfx init`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html#cfx-init),
+do that now, then come back here.
+
+The `lib/main.js` file looks like this:
+
+ const widgets = require("widget");
+ const tabs = require("tabs");
@ochameau Owner
ochameau added a note

Have we decided to use const in documentation? I'm not really against it, I just want to ensure that it is expected.

@wbamberg Owner
wbamberg added a note

Yes, we have. But this refers to the sample code created by cfx init, which uses "const". Probably it should also use "var", except that there's a bug saying the cfx init should not create any sample code at all: https://bugzilla.mozilla.org/show_bug.cgi?id=616640, which I think would be better.

@Gozala Owner
Gozala added a note

I would prefer to use var for all the high level code examples.

@ochameau Owner
ochameau added a note

Patch submitted for bug 616640!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((153 lines not shown))
+ width:215,
+ height:160,
+ contentURL: data.url("clock.html")
+ });
+
+ require("widget").Widget({
+ id: "open-clock-btn",
+ label: "Clock",
+ contentURL: data.url("History.png"),
+ panel: clockPanel
+ });
+
+## Learning More ##
+
+To learn more about the widget module, see its
+[API reference documentation](packages/addon-kit/docs/widget.html).
@ochameau Owner
ochameau added a note

I'm wondering if we should talk about id attribute in this turorial? (mandatory, used to save widget position, should not change over version because of this)
In anycase, if you think we should, wa can do this later on!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...addon-development/tutorials/adding-toolbar-content.md
@@ -0,0 +1,127 @@
+<!-- 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/. -->
+
+# Create a New Toolbar #
@ochameau Owner
ochameau added a note

Hum, I don't know how to phrase it otherwise, but a toolbar sounds like a 100% width toolbar where you can add buttons inside of it.

  • Create a complex/advanced/HTML toolbar item
  • Display an HTML document in toolbar
  • Display content in toolbar
  • ???
@ochameau Owner
ochameau added a note

Speaking about this, I'm wondering if we should implement bug 726487 and offer a way to group all addon's widget into the same group in order to implement such feature.
In any case, this page will always be usefull. It describe how to use a document inside of a widget.

@wbamberg Owner
wbamberg added a note

Hmm. The title is important, and the choice of "toolbar" was intentional.

The idea of this restructure, mostly, is to present tutorials by task rather than by technology. So, for example, one tutorial is called "display a popup" rather than "using panel". Because people coming into the SDK don't know or care about panel, they just want a popup. Similarly, I don't think people come in asking "I want to display an HTML document in the toolbar", they come in wanting to create a somewhat complex UI in the toolbar - or more likely, wanting to create a toolbar. That's why I chose this name.

It's true that what you can do using widget isn't quite the same as creating a toolbar, but (it seems to me) this is the best option for someone wanting to use the supported APIs. In this example you create an array of buttons, and - I'd say - that's pretty close to being a toolbar for most people.

Having said that - it is important that the tutorial explains the limitations of this approach, compared with a full-blown toolbar. If you think the differences between a "real" toolbar and an HTML widget are too great, and it will totally confuse people by referring to an HTML widget as a kind of limited toolbar, then I should rename this tutorial. But otherwise, I think we should keep the name the same, and in the tutorial describe the limitations (and maybe point to low-level APIs you could use to get around them).

Does that sound reasonable? If so, what would you say are the limitations, compared to a real toolbar?

@Gozala Owner
Gozala added a note

I know @ZER0 talked with folks from UX who are really into limiting width of widgets and have some special UI for toolbars, so it might be useful to sync with them before encouraging something like this. @ZER0 knows more about it so he should be able to provide a better feedback here.

@ZER0 Owner
ZER0 added a note

Yes, I think we should be careful about that. So, basically any widget into the Add-on bar in future shouldn't be bigger than the size of the download button (22x42px if I remember correctly). So you can still have your canvas to draw whatever you want, but in a very limited space.

On the other hand, a widget could have it's own real toolbar – in the same way now a widget can have a panel – under the regular one, that became visible when the widget is clicked. Only one toolbar at time can be displayed (so if you have a player's widget that display the current track and all controls, and you click on "memory usage" widget, the new toolbar takes place of the previous one).

If it's not clear, feel free to ask! I'm still waiting for the final mocks from UX, but that's seems pretty finalized.

@ochameau Owner
ochameau added a note

I think that everyone associate the term toolbar with yahoo, ask, google, bing, whatever toolbars, that is 100% width widget in the chrome UI 100% dedicated to your addon. Current "mini-toolbars" created using Widget looks like a little toy compared to these "real toolbars" :p I get your point and I really don't know how to call it otherwise, but it looks like developers may just be disappointed by what we propose regarding what they were expecting.

@wbamberg Owner
wbamberg added a note

Hm. So from what @ZER0 said, it sounds like I should definitely scrap this tutorial, actually. Since it doesn't respect that guideline. I'd like to suggest, instead, to raise another bug where I'll think of (or steal :) an example which uses HTML content in the widget, but not in this way. @Gozala, @ochameau, what do you think?

@Gozala Owner
Gozala added a note

I think that's a good idea!

@ochameau Owner
ochameau added a note

All examples (widget with html content) I can think about are all large:
https://addons.mozilla.org/en-US/firefox/addon/memchaser/
https://addons.mozilla.org/en-US/firefox/addon/memory-meter/
+all mini-toolbar examples (js framework detector, grooveshark plugin ...)
Looks like all usage would go against UX discussions/plans.

@Gozala Owner
Gozala added a note

@ochameau @ZER0 those might be a good examples to be discussed with UX. Anyway I think this discussion better taken to a different place.

@ZER0 Owner
ZER0 added a note

I already bring these examples to UX – I used all the examples provided by @ochameau in this mopad: https://jetpack.etherpad.mozilla.org/widget-in-navigation-bar

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...addon-development/tutorials/adding-toolbar-content.md
((3 lines not shown))
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+# Create a New Toolbar #
+
+<span class="aside">
+To follow this tutorial you'll need to have
+[installed the SDK](dev-guide/addon-development/installation.html)
+and learned the
+[basics of `cfx`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html).
+</span>
+
+You can use the [`widget`](packages/addon-kit/docs/widget.html)
+module to add a button to the
+[Add-on bar](http://support.mozilla.org/en-US/kb/what-add-bar).
+But because the widget can host HTML as well as just an image, and
+because you can attach scripts to the HTML, you can include anything
@ochameau Owner
ochameau added a note

Did you meant content scripts instead of scripts?
If not, I'd simplify the whole sentence with something like:
But because the widget can host HTML, you can specify anything in a widget that you can specify using dynamic HTML.
Or:
But because the widget can host HTML, you can specify any dynamic HTML content (Remote documents, Multiple images, Canvas and even WebGL!).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...addon-development/tutorials/adding-toolbar-content.md
((106 lines not shown))
+
+ // Listen for messages from the script
+ // using the "on()" function of the widget's
+ // "port" property
+
+ player.port.on("play", function() {
+ console.log("playing");
+ });
+
+ player.port.on("pause", function() {
+ console.log("pausing");
+ });
+
+ player.port.on("stop", function() {
+ console.log("stopping");
+ });
@ochameau Owner
ochameau added a note

Are you able to display a title to source code sections?
If yes, it would be really cool to put files path+name!
You wouldn't even have to read stuff between code in order to guess how the whole think works, especially, what is the file layout.

@wbamberg Owner
wbamberg added a note

Sorry, I'm not sure I understand this.

@Gozala Owner
Gozala added a note

I think what @ochameau suggested is to have file path for this snippet of code be displayed somewhere on top of it.

@ochameau Owner
ochameau added a note

Yes, something like /lib/main.js and /data/content-script.js, ...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...source/addon-development/tutorials/display-a-popup.md
@@ -0,0 +1,141 @@
+<!-- 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/. -->
+
+# Display a Popup #
+
+<span class="aside">
+To follow this tutorial you'll need to have
+[installed the SDK](dev-guide/addon-development/installation.html)
+and learned the
+[basics of `cfx`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html).
+</span>
+
+<img class="image-right" src="static-files/media/screenshots/text-entry-panel.png"
+alt="Text entry panel">
@ochameau Owner
ochameau added a note

This image ends up being between the following text and the previous side note.
The text end up being really thin. Is there a way to force this image to be after the side note?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...source/addon-development/tutorials/display-a-popup.md
((81 lines not shown))
+ // Set the focus to the text area so the user can
+ // just start typing.
+ var textArea = document.getElementById("edit-box");
+ textArea.focus();
+ // When the user hits return, send the "text-entered"
+ // message to main.js.
+ // The message payload is the contents of the edit box.
+ textArea.onkeyup = function(event) {
+ if (event.keyCode == 13) {
+ // Remove the newline.
+ text = textArea.value.replace(/(\r\n|\n|\r)/gm,"");
+ self.port.emit("text-entered", text);
+ textArea.value = '';
+ }
+ };
+ });
@ochameau Owner
ochameau added a note

This script is not perfect, but feel free to keep it as-is if it is easier to explain!
Here, we register a keyup listener each time a showevent is dispatched.
We end up registering only one at a time, as we overload the previous one with a new one.
It would be better to register this listener only once, outside of the show event listener.

@wbamberg Owner
wbamberg added a note

Nope, the examples should be as good as possible, even if it takes a bit more time to explain. People will copy these (I hope). I'll try to fix it and ask for a re-review.

@Gozala Owner
Gozala added a note

Yes that's a good point! I think panel should have: contentScriptWhen: 'ready' set so it's content script is executed once document's elements are accessible and then it can register keyup listener:

var textArea = document.getElementById("edit-box");
textArea.addEventListener('keyup', function onkeyup(event) {
 // same code as in original listener
}, false);
self.port.on("show", function onShow() { textArea.focus(); });
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...source/addon-development/tutorials/display-a-popup.md
@@ -0,0 +1,141 @@
+<!-- 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/. -->
+
+# Display a Popup #
+
+<span class="aside">
+To follow this tutorial you'll need to have
+[installed the SDK](dev-guide/addon-development/installation.html)
+and learned the
+[basics of `cfx`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html).
+</span>
@ochameau Owner
ochameau added a note

It may be usefull to add a link to the main Widget tutorial, as we explain there the whole content script/event story?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((148 lines not shown))
+alt="Panel attached to a widget">
+
+ data = require("self").data
+
+ var clockPanel = require("panel").Panel({
+ width:215,
+ height:160,
+ contentURL: data.url("clock.html")
+ });
+
+ require("widget").Widget({
+ id: "open-clock-btn",
+ label: "Clock",
+ contentURL: data.url("History.png"),
+ panel: clockPanel
+ });
@ochameau Owner
ochameau added a note

It would be usefull to add a link to display-a-popup.md, as it show a complex usage of this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...don-development/tutorials/getting-started-with-cfx.md
@@ -0,0 +1,169 @@
+<!-- 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/. -->
+
+<span class="aside">This tutorial assumes that you've read and followed the instructions in
+the [installation guide](dev-guide/addon-development/installation.html), to
+install and activate the SDK. If you haven't, go back and do that now, then
+come back here.</span>
@ochameau Owner
ochameau added a note

The last sentence sounds harsh? I'm not the best judge regarding my english level ...
I'm wondering if it is usefull, isn't the first sentence informative enough?

@wbamberg Owner
wbamberg added a note

I wasn't supposed to be! But yes, you're right, it's at best redundant.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...don-development/tutorials/getting-started-with-cfx.md
((70 lines not shown))
+<pre>
+cfx run
+</pre>
+
+The first time you do this, you'll see a message like this:
+
+<pre>
+No 'id' in package.json: creating a new ID for you.
+package.json modified: please re-run 'cfx run'
+</pre>
+
+<img class="image-right" src="static-files/media/screenshots/widget-mozilla.png"
+alt="Mozilla icon widget" />
+
+Run `cfx run` again, and it will run an instance of Firefox. In the
+bottom-left corner of the browser you'll see an icon with the Firefox
@ochameau Owner
ochameau added a note

bottom-left-> bottom-right

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...don-development/tutorials/getting-started-with-cfx.md
((113 lines not shown))
+and the URL that gets loaded:
+
+ const widgets = require("widget");
+ const tabs = require("tabs");
+
+ var widget = widgets.Widget({
+ id: "jquery-link",
+ label: "jQuery website",
+ contentURL: "http://www.jquery.com/favicon.ico",
+ onClick: function() {
+ tabs.open("http://www.jquery.com/");
+ }
+ });
+
+<img class="image-right" src="static-files/media/screenshots/widget-jquery.png"
+alt="jQuery icon widget" />
@ochameau Owner
ochameau added a note

Same comment than here:
https://github.com/mozilla/addon-sdk/pull/347/files#r518701
This image overlap cfx xpi header and looks bad.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((25 lines not shown))
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: "http://www.mozilla.org/favicon.ico",
+ onClick: function() {
+ tabs.activeTab.attach({
+ contentScript:
+ 'document.body.style.border = "5px solid red";'
+ })
+ }
+ });
+
+This add-on creates a widget which contains the Mozilla favicon as an icon.
+It has a click handler which fetches the active tab and loads a
+script into the page hosted by the active tab. The script is specified using
+`contentScript` option, and just draws
+a red border round the page. Try it out:
@ochameau Owner
ochameau added a note

round -> around ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((38 lines not shown))
+script into the page hosted by the active tab. The script is specified using
+`contentScript` option, and just draws
+a red border round the page. Try it out:
+
+* create a new directory and navigate to it
+* run `cfx init`
+* open the `lib/main.js` file, and replace its contents with the code above
+* run `cfx run`, then run `cfx run` again
+
+You should see the Mozilla icon appear in the bottom-right corner of the
+browser:
+
+<img class="image-center" src="static-files/media/screenshots/widget-mozilla.png"
+alt="Mozilla icon widget" />
+
+Next open any web page in the browser window that opens, and click the
@ochameau Owner
ochameau added a note

Next open -> Then open ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((69 lines not shown))
+
+We can load this script by changing the add-on code like this:
+
+ var widgets = require("widget");
+ var tabs = require("tabs");
+ var self = require("self");
+
+ var widget = widgets.Widget({
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: "http://www.mozilla.org/favicon.ico",
+ onClick: function() {
+ tabs.activeTab.attach({
+ contentScriptFile: self.data.url("my-script.js")
+ })
+ }
@ochameau Owner
ochameau added a note

The indentation is wrong for onClick and attach ending brace.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((18 lines not shown))
+
+Here's a simple example:
+
+ var widgets = require("widget");
+ var tabs = require("tabs");
+
+ var widget = widgets.Widget({
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: "http://www.mozilla.org/favicon.ico",
+ onClick: function() {
+ tabs.activeTab.attach({
+ contentScript:
+ 'document.body.style.border = "5px solid red";'
+ })
+ }
@ochameau Owner
ochameau added a note

The indentation is wrong for onClick and attach ending brace.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((115 lines not shown))
+using the object returned from `attach()`:
+
+ var widgets = require("widget");
+ var tabs = require("tabs");
+ var self = require("self");
+
+ var widget = widgets.Widget({
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: "http://www.mozilla.org/favicon.ico",
+ onClick: function() {
+ worker = tabs.activeTab.attach({
+ contentScriptFile: self.data.url("my-script.js")
+ })
+ worker.port.emit("drawBorder", "red");
+ }
@ochameau Owner
ochameau added a note

The indentation is wrong for onClick and attach ending brace.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-tab.md
((96 lines not shown))
+
+To send a
+message from one side to the other, the sender calls `port.emit()` and
+the receiver listens using `port.on()`.
+
+* In the content script, `port` is a property of the global `self` object.
+* In the add-on script, `tab-attach()` returns an object containing the
+`port` property you use to send messages to the content script.
+
+Let's rewrite the example above to pass a message from the add-on to
+the content script. The content script now needs to look like this:
+
+ // "self" is a global object in content scripts
+ // Listen for a "drawBorder"
+ self.port.on("drawBorder", function(color) {
+ document.body.style.border = "5px solid" + color;
@ochameau Owner
ochameau added a note

We need a space between solid and the color:
document.body.style.border = "5px solid " + color;

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-url.md
((97 lines not shown))
+ // Import the self API
+ var self = require("self");
+
+ // Create a page mod
+ // It will run a script whenever a ".org" URL is loaded
+ // The script replaces the page contents with a message
+ pageMod.PageMod({
+ include: "*.org",
+ contentScriptFile: self.data.url("jquery-1.7.min.js"),
+ contentScript: '$("body").html("<h1>Page matches ruleset</h1>");'
+ });
+
+Note, though, that you can't load a script from a web site. The script
+must be loaded from `data`.
+
+### Communicating With the Content Script ###
@ochameau Owner
ochameau added a note

Shouldn't this be level 2 header instead of level 3?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ddon-development/tutorials/modifying-web-pages-url.md
((95 lines not shown))
+ // Import the page-mod API
+ var pageMod = require("page-mod");
+ // Import the self API
+ var self = require("self");
+
+ // Create a page mod
+ // It will run a script whenever a ".org" URL is loaded
+ // The script replaces the page contents with a message
+ pageMod.PageMod({
+ include: "*.org",
+ contentScriptFile: self.data.url("jquery-1.7.min.js"),
+ contentScript: '$("body").html("<h1>Page matches ruleset</h1>");'
+ });
+
+Note, though, that you can't load a script from a web site. The script
+must be loaded from `data`.
@ochameau Owner
ochameau added a note

It may be worth it to specify that contentScriptFile (and contentScript) accept Arrays.
In this whole page, there is no mention of that, whereas you expose in this paragraph that we can load multiple scripts,
but without "real example" (i.e. real addons should not use contentScript, but only an array for contentScriptFile instead.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Gozala Gozala commented on the diff
doc/dev-guide-source/addon-development/commonjs.md
((36 lines not shown))
+
+* creating user interfaces
+* interacting with the web
+* interacting with the browser
+
+These modules are "supported": meaning that they are relatively
+stable, and that we'll avoid making incompatible changes to them
+unless absolutely necessary.
+
+They are documented in the "High-Level APIs" section
+of the sidebar.
+
+### <a name="api-utils">api-utils</a> ###
+
+Modules in the `api-utils` package implement low-level APIs. These
+modules fall roughly into three categories:
@Gozala Owner
Gozala added a note

I think we should mention that they are not stable and may change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...dev-guide-source/addon-development/high-level-apis.md
@@ -0,0 +1,12 @@
+# High-Level APIs #
+
+Modules in this section implement high-level APIs for
+building add-ons:
+
+* creating user interfaces
+* interacting with the web
+* interacting with the browser
+
+These modules are "supported": meaning that they are relatively
+stable, and that we'll avoid making incompatible changes to them
@Gozala Owner
Gozala added a note

I would just say stable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
doc/dev-guide-source/addon-development/low-level-apis.md
((4 lines not shown))
+modules fall roughly into three categories:
+
+* fundamental utilities such as
+[collection](packages/api-utils/docs/collection.html) and
+[url](packages/api-utils/docs/url.html). Many add-ons are likely to
+want to use modules from this category.
+
+* building blocks for higher level modules, such as
+[events](packages/api-utils/docs/events.html),
+[worker](packages/api-utils/docs/content/worker.html), and
+[api-utils](packages/api-utils/docs/api-utils.html). You're more
+likely to use these if you are building your own modules that
+implement new APIs, thus extending the SDK itself.
+
+* privileged modules that expose powerful low-level capabilities
+such as [tab-browser](packages/api-utils/docs/tab-browser.html),
@Gozala Owner
Gozala added a note

I would remove tab-browser from here as we have left it just because of some test that rely on it. We probably will be removing it at some point in a future.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../addon-development/tutorials/adding-toolbar-button.md
((58 lines not shown))
+ var widget = widgets.Widget({
+ id: "mozilla-link",
+ label: "Mozilla website",
+ contentURL: self.data.url("my-icon.png"),
+ onClick: function() {
+ tabs.open("http://www.mozilla.org/");
+ }
+ });
+
+You can change the icon at any time by setting the widget's `contentURL`
+property.
+
+## Responding To the User ##
+
+You can listen for `click`, `mouseover`, and `mouseout` events by assigning
+functions to the corresponding widget properties. The widget example above
@Gozala Owner
Gozala added a note

I would say by passing corresponding widget options, cause reading this left me under impression that I could:

mywidget.click = funciton() { } 
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...addon-development/tutorials/adding-toolbar-content.md
((17 lines not shown))
+But because the widget can host HTML as well as just an image, and
+because you can attach scripts to the HTML, you can include anything
+in a widget that you can specify using dynamic HTML.
+
+This means you can use a widget to create your own toolbar inside the
+Add-on bar. The main restrictions are:
+
+* although you can set the width of the toolbar, you can't set its height:
+it must fit inside the Add-on bar
+
+* you can only place the toolbar in the Add-on bar, although the user can
+relocate it using toolbar customization (but when
+[bug 695913](https://bugzilla.mozilla.org/show_bug.cgi?id=695913) is fixed,
+widgets will be placed in the navigation bar by default).
+
+* any scripts attached to the widget can't use the SDK APIs. So if you want
@Gozala Owner
Gozala added a note

maybe contentScript would be more explicit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...source/addon-development/tutorials/display-a-popup.md
((73 lines not shown))
+ });
+
+The content script "get-text.js" looks like this:
+
+ // Listen for the "show" event being sent from the
+ // main add-on code. It means that the panel's about
+ // to be shown.
+ self.port.on("show", function (arg) {
+ // Set the focus to the text area so the user can
+ // just start typing.
+ var textArea = document.getElementById("edit-box");
+ textArea.focus();
+ // When the user hits return, send the "text-entered"
+ // message to main.js.
+ // The message payload is the contents of the edit box.
+ textArea.onkeyup = function(event) {
@Gozala Owner
Gozala added a note

I would go for texArea.addEventListener('keyup', function() { .. }, false); form instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...source/addon-development/tutorials/display-a-popup.md
((121 lines not shown))
+
+Try it out: "main.js" is saved in your add-on's `lib` directory,
+and the other two files go in your add-on's `data` directory:
+
+<pre>
+my-addon/
+ data/
+ get-text.js
+ text-entry.html
+ lib/
+ main.js
+</pre>
+
+Run the add-on, click the widget, and you should see the panel.
+Type some text and press "return" and you should see the output
+in the console.
@Gozala Owner
Gozala added a note

I really think all this examples should be in our examples folder and this
tutorials should have links to them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...v-guide-source/addon-development/tutorials/logging.md
((7 lines not shown))
+<span class="aside">
+To follow this tutorial you'll need to have
+[installed the SDK](dev-guide/addon-development/installation.html)
+and learned the
+[basics of `cfx`](dev-guide/addon-development/tutorials/getting-started-with-cfx.html).
+</span>
+
+To help debug your add-on you can use the SDK's global `console` object
+to log error, warning, or informational messages. You don't have to
+`require()` anything to get access to the console: it is automatically
+made available to you.
+
+<span class="aside">
+Because `window.alert()` isn't available to your main add-on code,
+if you use it for diagnostics then the console is a
+useful replacement.
@Gozala Owner
Gozala added a note

I'm not sure it's useful to mention window.alert as most browsers today have console.log anyway, maybe it's even better to mention that it's just like browsers console.log but logs into different location.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...v-guide-source/addon-development/tutorials/logging.md
((35 lines not shown))
+* execute `cfx run`, then `cfx run` again
+
+Firefox will start, and the following line will appear in the command
+window you used to execute `cfx run`:
+
+<pre>
+info: Hello World!
+</pre>
+
+## `console` in Content Scripts ##
+
+You can use the console in
+[content scripts](dev-guide/addon-development/web-content.html) as well
+as in your main add-on code. The following add-on logs the HTML content
+of every tab the user loads, by calling `console.log()` inside a content
+script:
@Gozala Owner
Gozala added a note

I would just really say that console.log is also available in content scripts, explaining that it's loaded for each tab etc feels like making it more complicated.

@wbamberg Owner
wbamberg added a note

@Gozala, I don't understand this. When you say "explaining that it's loaded for each tab" are you referring to the second sentence "The following add-on logs the HTML content of every tab the user loads"? Because that's talking about the example that follows, not about content scripts. So unless you're asking to remove the example, I don't think this sentence can be removed really.

@Gozala Owner
Gozala added a note

@wbamberg I think I misread / misunderstood it when I wrote my comment. Feel free to ignore this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ource/addon-development/tutorials/reusable-modules.md
((291 lines not shown))
+// Implement getCurrentPosition by loading the nsIDOMGeoGeolocation
+// XPCOM object.
+function getCurrentPosition(callback) {
+ var xpcomGeolocation = Cc["@mozilla.org/geolocation;1"]
+ .getService(Ci.nsIDOMGeoGeolocation);
+ xpcomGeolocation.getCurrentPosition(callback);
+}
+
+exports.getCurrentPosition = getCurrentPositionWithCheck;
+</code></pre>
+
+### Update `main.js` ###
+
+Finally, update "main.js". First add a line to import the new module:
+
+ var geolocation = require("geolocation");
@Gozala Owner
Gozala added a note

I think we should encourage explicit form: require('./geolocation').

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
...ource/addon-development/tutorials/reusable-modules.md
((303 lines not shown))
+
+Finally, update "main.js". First add a line to import the new module:
+
+ var geolocation = require("geolocation");
+
+Edit the widget's call to `getCurrentPositionWithCheck()` so it calls
+the geolocation module's `getCurrentPosition()` function instead:
+
+ geolocation.getCurrentPosition(function(position) {
+ if (!position) {
+
+Now "main.js" should look like this:
+
+<pre><code>
+var geolocation = require("geolocation");
+
@Gozala Owner
Gozala added a note

same as above explicit form is better.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Gozala
Owner

@wbamberg cool stuff, I'm really excited to see all these tutorials as they cover most of the questions raised by people. I made few remarks in pull request and have some general suggestions:

  • I think it would be so much better if we had example add-on's for all these tutorials so users could always look at them. I don't know if we should dump them to examples folder, have separate repos or publish them to builder but either way I think it would be super helpful.
  • I found mix of markdown and html markup bit confusing, also I might be missing something, but I think most of a, il, pre tags can be replaced by markdown.
  • There is one more question that is raised on mailing lists and IRC over and over again, so I created a bug for it: https://bugzilla.mozilla.org/show_bug.cgi?id=734201 I think it can be a separate task.

Thanks & looking forward to see our users reactions!

@wbamberg
Owner

@Gozala thanks, and thanks for your review of this huge PR! I agree about examples, and I'll raise a separate bug about that. We've discussed this before, and I think the Builder is perhaps the best way to go.

About mixing Markdown and HTML: I try to keep to Markdown, but there are cases where I need to use HTML: for example, because I can't have class or name attributes with Markdown, or (apparently) because I want to include markup inside an element, like DIV or TABLE, that itself has to be specified using HTML directly. So we will inevitably have a hybrid. Still there probably are some HTML elements that could be MD, and I'll scan the patch before landing it.

@Gozala
Owner

We've discussed this before, and I think the Builder is perhaps the best way to go.

only problem with builder you won't see the file paths, but it may be not such a big issue.

About mixing Markdown and HTML: I try to keep to Markdown, but there are cases where I need to use HTML: for
example, because I can't have class or name attributes with Markdown, or (apparently) because I want to include
markup inside an element, like DIV or TABLE, that itself has to be specified using HTML directly. So we will inevitably
have a hybrid. Still there probably are some HTML elements that could be MD, and I'll scan the patch before landing it.

Right I have not thought about that.

@Gozala
Owner

@wbamberg do you still wanna keep this pull request open ? If no could you please close it ?

@wbamberg wbamberg closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Dec 2, 2011
  1. @wbamberg

    start at reworking tutes

    wbamberg authored
Commits on Dec 6, 2011
  1. @wbamberg
Commits on Dec 7, 2011
  1. @wbamberg

    ...

    wbamberg authored
  2. @wbamberg

    ...

    wbamberg authored
Commits on Dec 8, 2011
  1. @wbamberg

    ...

    wbamberg authored
  2. @wbamberg

    ...

    wbamberg authored
  3. @wbamberg
  4. @wbamberg

    clean up tutorials sidebar

    wbamberg authored
  5. @wbamberg
  6. @wbamberg
Commits on Dec 23, 2011
  1. @wbamberg
  2. @wbamberg

    ...

    wbamberg authored
  3. @wbamberg
Commits on Jan 4, 2012
  1. @wbamberg
  2. @wbamberg
  3. @wbamberg

    fix merge conflicts

    wbamberg authored
  4. @wbamberg

    some style changes

    wbamberg authored
Commits on Jan 5, 2012
  1. @wbamberg

    cange background colour

    wbamberg authored
Commits on Jan 7, 2012
  1. @wbamberg

    add 2 missing tutorial files

    wbamberg authored
  2. @wbamberg
Commits on Jan 8, 2012
  1. @wbamberg

    start toolbar tutorial

    wbamberg authored
Commits on Jan 10, 2012
  1. @wbamberg

    style changes

    wbamberg authored
Commits on Jan 11, 2012
  1. @wbamberg
  2. @wbamberg

    ...

    wbamberg authored
  3. @wbamberg

    ...

    wbamberg authored
Commits on Jan 12, 2012
  1. @wbamberg
Commits on Jan 16, 2012
  1. @wbamberg
Commits on Jan 25, 2012
  1. @wbamberg

    fix merge conflict

    wbamberg authored
Commits on Jan 26, 2012
  1. @wbamberg
  2. @wbamberg

    made prerequisites an aside

    wbamberg authored
Commits on Feb 2, 2012
  1. @wbamberg

    ...

    wbamberg authored
Commits on Feb 3, 2012
  1. @wbamberg

    added reusable modules tute

    wbamberg authored
  2. @wbamberg
Commits on Feb 4, 2012
  1. @wbamberg
  2. @wbamberg

    update main page

    wbamberg authored
  3. @wbamberg
  4. @wbamberg

    ...

    wbamberg authored
Commits on Feb 8, 2012
  1. @wbamberg

    ...

    wbamberg authored
  2. @wbamberg

    ...

    wbamberg authored
Commits on Feb 9, 2012
  1. @wbamberg
  2. @wbamberg

    ...

    wbamberg authored
  3. @wbamberg

    ...

    wbamberg authored
Commits on Feb 10, 2012
  1. @wbamberg

    ...

    wbamberg authored
  2. @wbamberg

    ...

    wbamberg authored
  3. @wbamberg

    get cfx testcfx to work

    wbamberg authored
  4. @wbamberg

    ...

    wbamberg authored
  5. @wbamberg

    ...

    wbamberg authored
  6. @wbamberg
  7. @wbamberg
Commits on Feb 16, 2012
  1. @wbamberg

    fix merge conflicts

    wbamberg authored
  2. @wbamberg

    added mobile doc

    wbamberg authored
  3. @wbamberg
Commits on Feb 28, 2012
  1. @wbamberg

    Fix merge conflicts

    wbamberg authored
Commits on Mar 9, 2012
  1. @wbamberg

    fix merge conflicts

    wbamberg authored
Commits on Mar 14, 2012
  1. @wbamberg
  2. @wbamberg
  3. @wbamberg
  4. @wbamberg
Commits on Mar 15, 2012
  1. @wbamberg

    update base.html

    wbamberg authored
  2. @wbamberg

    fix links

    wbamberg authored
  3. @wbamberg
  4. @wbamberg
Commits on Mar 17, 2012
  1. @wbamberg
Commits on Mar 18, 2012
  1. @wbamberg

    rework landing pages...

    wbamberg authored
Commits on Mar 19, 2012
  1. @wbamberg
  2. @wbamberg
  3. @wbamberg

    cleanup unused CSS rules

    wbamberg authored
  4. @wbamberg
  5. @wbamberg
  6. @wbamberg
  7. @wbamberg

    fix HTML validation errors

    wbamberg authored
  8. @wbamberg
  9. @wbamberg

    fix sidebar links

    wbamberg authored
  10. @wbamberg
This page is out of date. Refresh to see the latest.
Showing with 2,940 additions and 1,691 deletions.
  1. +0 −54 doc/dev-guide-source/addon-development/api-idioms.md
  2. +0 −12 doc/dev-guide-source/addon-development/api-intro.md
  3. +0 −203 doc/dev-guide-source/addon-development/api-modules.md
  4. +0 −23 doc/dev-guide-source/addon-development/getting-started.md
  5. +0 −24 doc/dev-guide-source/addon-development/guides.md
  6. +0 −188 doc/dev-guide-source/addon-development/implementing-reusable-module.md
  7. +0 −313 doc/dev-guide-source/addon-development/implementing-simple-addon.md
  8. +0 −28 doc/dev-guide-source/addon-development/index.md
  9. +0 −21 doc/dev-guide-source/addon-development/reference.md
  10. +0 −22 doc/dev-guide-source/addon-development/tutorials.md
  11. +14 −18 doc/dev-guide-source/{addon-development → }/cfx-tool.md
  12. 0  doc/dev-guide-source/{addon-development → }/console.md
  13. 0  doc/dev-guide-source/{appendices → }/credits.md
  14. +0 −5 doc/dev-guide-source/{appendices → }/glossary.md
  15. +79 −11 doc/dev-guide-source/{addon-development → guides}/commonjs.md
  16. +1 −1  doc/dev-guide-source/{addon-development → guides}/content-scripts/access.md
  17. +7 −7 doc/dev-guide-source/{addon-development/web-content.md → guides/content-scripts/index.md}
  18. 0  doc/dev-guide-source/{addon-development → guides}/content-scripts/loading.md
  19. 0  doc/dev-guide-source/{addon-development → guides}/content-scripts/reddit-example.md
  20. +1 −1  doc/dev-guide-source/{addon-development → guides}/content-scripts/using-port.md
  21. +1 −1  doc/dev-guide-source/{addon-development → guides}/content-scripts/using-postmessage.md
  22. +2 −2 doc/dev-guide-source/{addon-development → guides}/events.md
  23. 0  doc/dev-guide-source/{addon-development → guides}/firefox-compatibility.md
  24. +171 −0 doc/dev-guide-source/guides/index.md
  25. +1 −1  doc/dev-guide-source/{addon-development → guides}/library-detector.md
  26. +2 −2 doc/dev-guide-source/{addon-development → guides}/module-search.md
  27. +1 −1  doc/dev-guide-source/{addon-development → guides}/program-id.md
  28. +5 −6 doc/dev-guide-source/{addon-development → guides}/sdk-vs-xul.md
  29. +6 −8 doc/dev-guide-source/{addon-development → guides}/two-types-of-scripts.md
  30. +23 −22 doc/dev-guide-source/{addon-development → guides}/xul-migration.md
  31. +16 −0 doc/dev-guide-source/high-level-apis.md
  32. +140 −17 doc/dev-guide-source/index.md
  33. +34 −0 doc/dev-guide-source/low-level-apis.md
  34. +0 −56 doc/dev-guide-source/module-development/best-practices.md
  35. +0 −12 doc/dev-guide-source/module-development/guides.md
  36. +0 −47 doc/dev-guide-source/module-development/index.md
  37. +0 −13 doc/dev-guide-source/module-development/reference.md
  38. +0 −14 doc/dev-guide-source/module-development/tutorials.md
  39. +0 −76 doc/dev-guide-source/module-development/xpi.md
  40. +1 −1  doc/dev-guide-source/{addon-development → }/package-spec.md
  41. +7 −0 doc/dev-guide-source/third-party-apis.md
  42. +88 −0 doc/dev-guide-source/tutorials/add-a-context-menu-item.md
  43. +21 −44 doc/dev-guide-source/{addon-development/third-party-packages.md → tutorials/adding-menus.md}
  44. +175 −0 doc/dev-guide-source/tutorials/adding-toolbar-button.md
  45. +1 −1  doc/dev-guide-source/{addon-development → tutorials}/annotator/creating.md
  46. 0  doc/dev-guide-source/{addon-development → tutorials}/annotator/displaying.md
  47. +5 −5 doc/dev-guide-source/{addon-development/annotator/annotator.md → tutorials/annotator/index.md}
  48. +1 −1  doc/dev-guide-source/{addon-development → tutorials}/annotator/overview.md
  49. +1 −1  doc/dev-guide-source/{addon-development → tutorials}/annotator/storing.md
  50. +1 −1  doc/dev-guide-source/{addon-development → tutorials}/annotator/widget.md
  51. +3 −0  doc/dev-guide-source/{module-development → tutorials}/chrome.md
  52. +151 −0 doc/dev-guide-source/tutorials/display-a-popup.md
  53. +170 −0 doc/dev-guide-source/tutorials/getting-started-with-cfx.md
  54. +233 −0 doc/dev-guide-source/tutorials/index.md
  55. +8 −19 doc/dev-guide-source/{addon-development → tutorials}/installation.md
  56. 0  doc/dev-guide-source/{addon-development → tutorials}/l10n.md
  57. +73 −0 doc/dev-guide-source/tutorials/list-open-tabs.md
  58. +55 −0 doc/dev-guide-source/tutorials/listen-for-page-load.md
  59. +103 −0 doc/dev-guide-source/tutorials/load-and-unload.md
  60. +67 −0 doc/dev-guide-source/tutorials/logging.md
  61. +8 −1 doc/dev-guide-source/{addon-development → tutorials}/mobile.md
  62. +145 −0 doc/dev-guide-source/tutorials/modifying-web-pages-tab.md
  63. +190 −0 doc/dev-guide-source/tutorials/modifying-web-pages-url.md
  64. +57 −0 doc/dev-guide-source/tutorials/open-a-web-page.md
  65. +413 −0 doc/dev-guide-source/tutorials/reusable-modules.md
  66. +1 −1  doc/dev-guide-source/{addon-development → tutorials}/troubleshooting.md
  67. +166 −0 doc/dev-guide-source/tutorials/unit-testing.md
  68. +46 −109 doc/static-files/base.html
  69. +128 −94 doc/static-files/css/sdk-docs.css
  70. +7 −40 doc/static-files/js/main.js
  71. BIN  doc/static-files/media/bg-header.png
  72. BIN  doc/static-files/media/screenshots/context-menu-selection.png
  73. BIN  doc/static-files/media/screenshots/default-widget.png
  74. BIN  doc/static-files/media/screenshots/pagemod-ietf.png
  75. BIN  doc/static-files/media/screenshots/tabattach-bbc.png
  76. BIN  doc/static-files/media/screenshots/widget-jquery.png
  77. BIN  doc/static-files/media/screenshots/widget-mozilla.png
  78. +2 −1  doc/static-files/syntaxhighlighter/styles/shThemeDefault.css
  79. +4 −4 packages/addon-kit/docs/context-menu.md
  80. +1 −1  packages/addon-kit/docs/page-mod.md
  81. +9 −9 packages/addon-kit/docs/page-worker.md
  82. +7 −7 packages/addon-kit/docs/panel.md
  83. +1 −1  packages/addon-kit/docs/passwords.md
  84. +3 −3 packages/addon-kit/docs/self.md
  85. +1 −1  packages/addon-kit/docs/simple-storage.md
  86. +2 −2 packages/addon-kit/docs/tabs.md
  87. +15 −15 packages/addon-kit/docs/widget.md
  88. +1 −1  packages/addon-kit/package.json
  89. +2 −2 packages/api-utils/docs/content/worker.md
  90. +1 −1  packages/api-utils/docs/file.md
  91. +2 −4 {doc/dev-guide-source/module-development → packages/api-utils/docs}/globals.md
  92. +1 −1  packages/api-utils/docs/memory.md
  93. +1 −1  packages/api-utils/docs/plain-text-console.md
  94. +1 −1  packages/test-harness/README.md
  95. +1 −1  packages/test-harness/docs/run-tests.md
  96. +15 −6 python-lib/cuddlefish/docs/webdocs.py
  97. +40 −101 python-lib/cuddlefish/tests/static-files/doc/static-files/base.html
  98. +1 −1  python-lib/cuddlefish/tests/test_generate.py
View
54 doc/dev-guide-source/addon-development/api-idioms.md
@@ -1,54 +0,0 @@
-<!-- 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/. -->
-
-# Common Idioms #
-
-## Constructors ##
-
-Many SDK modules export constructors that create object instances for use
-by add-on code.
-
-A constructor takes a single argument, an object typically referred to as
-`options` and supplied as an object literal listing values for named object
-properties. So you will generally see objects constructed using the following
-pattern:
-
- var sdkModule = require("sdk-module");
-
- var mySdkObject = sdkModule.sdkObject({
- property1: value1,
- property2: value2
- });
-
-## Events ##
-
-The SDK supports event-driven programming: objects which are event emitters
-can emit events such as pages loading, windows opening and user interactions.
-
-Add-on developers can register listeners with event emitters and are then
-notified when the events occur.
-
-To learn more about events, see the
-[Working with Events](dev-guide/addon-development/events.html) page.
-
-## Content Scripting ##
-
-Several modules need to interact directly with web content, either web content
-they host themselves (such as the [`panel`](packages/addon-kit/panel.html) module) or
-web content hosted by the browser (such as the
-[`page-mod`](packages/addon-kit/page-mod.html)).
-
-These modules follow a common pattern in which the code
-that actually interacts with the content is executed as a separate script
-called a content script. The content script and the main add-on script
-communicate using an asynchronous message-passing mechanism.
-
-Objects that implement this scheme include properties that specify which
-content scripts should be run and when.
-
-To learn more about content scripts, see the [Working with Content Scripts
-](dev-guide/addon-development/web-content.html) page.
-
-<br>
-**Next**: [module overview](dev-guide/addon-development/api-modules.html).
View
12 doc/dev-guide-source/addon-development/api-intro.md
@@ -1,12 +0,0 @@
-<!-- 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/. -->
-
-# Introducing the APIs #
-
-### [Common Idioms](dev-guide/addon-development/api-idioms.html) ###
-An introduction to idioms used throughout the SDK.
-
-### [API Overview](dev-guide/addon-development/api-modules.html) ###
-A quick introduction to the modules provided in the
-[`addon-kit`](packages/addon-kit/index.html) package.
View
203 doc/dev-guide-source/addon-development/api-modules.md
@@ -1,203 +0,0 @@
-<!-- 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/. -->
-
-# API Overview #
-
-This section is a very quick overview of some of the APIs provided in the SDK.
-We've grouped them into four categories according to their function:
-
- 1. Building a UI
- 2. Interacting with the Web
- 3. Interacting with the Browser
- 4. Dealing with Data
-
-## Building a UI ##
-
-The SDK provides four modules to help you build a UI.
-
-### [panel](packages/addon-kit/panel.html) ###
-
-A panel is a dialog. Its content is specified as HTML and you can execute
-scripts in it, so the appearance and behaviour of the panel is limited only
-by what you can do using HTML, CSS and JavaScript.
-
-You can build or load the content locally or load it from a remote server.
-The screenshot below shows a panel whose content is built from the list of
-currently open tabs:
-
-<img class="image-center" src="static-files/media/screenshots/modules/panel-tabs-osx.png"
-alt="List open tabs panel">
-<br>
-
-Scripts executing in the panel's context can exchange messages with the main
-add-on code.
-
-### [widget](packages/addon-kit/widget.html) ###
-
-A widget is a small piece of HTML content which is displayed in the Firefox 4
-[add-on bar](https://developer.mozilla.org/en/The_add-on_bar).
-
-Widgets are generally used in one of two different contexts:
-
-* to display compact content that should always be visible to the user, such as
-the time in a selected time zone or the weather. The screenshot below shows a
-widget that displays the time in the selected city:
-
-<img class="image-center" src="static-files/media/screenshots/modules/widget-content-osx.png"
-alt="Mozilla widget content">
-<br>
-
-* to provide a way for the user to access other parts of an add-on's user
-interface. For example, a widget might display only an icon, but open a
-settings dialog when the user clicks it. The widget below displays only the
-Mozilla icon:
-
-<img class="image-center" src="static-files/media/screenshots/modules/widget-icon-osx.png"
-alt="Mozilla widget icon">
-<br>
-
-To simplify your code in the latter case, you can assign a panel object to
-your widget. Then when the user clicks the widget, the widget will display
-the panel anchored to the widget:
-
-<img class="image-center" src="static-files/media/screenshots/modules/widget-panel-osx.png"
-alt="Panel anchored to widget">
-<br>
-
-### [context-menu](packages/addon-kit/context-menu.html) ###
-
-The `context-menu` module lets you add items and submenus to the browser's
-context menu.
-
-You can define the context in which the item is shown using any
-of a number of predefined contexts (for example, when some content on the page
-is selected) or define your own contexts using scripts.
-
-In the screenshot below an add-on has added a new submenu to the context menu
-associated with `img` elements:
-
-<img class="image-center" src="static-files/media/screenshots/modules/context-menu-image-osx.png"
-alt="Context-menu">
-<br>
-
-### [notifications](packages/addon-kit/notifications.html) ###
-
-This module enables an add-on to display transient messages to the user.
-
-It uses the platform's notification service ([Growl](http://growl.info/) on Mac
-OS X and Windows, libnotify on Linux), so the notification will look slightly
-different on different platforms. On Mac OS X a notification will look
-something like this:
-
-<img class="image-center" src="static-files/media/screenshots/modules/notification-growl-osx.png"
-alt="Growl notification">
-<br>
-
-## Interacting with the Web ##
-
-As you might expect, the SDK provides several APIs for interacting with the
-Web. Some of them, like `page-mod` and `selection`, interact with web pages
-the user visits, while APIs like `page-worker` and `request` enable you to
-fetch web content for yourself.
-
-### [page-mod](packages/addon-kit/page-mod.html) ###
-
-The `page-mod` module enables you to execute scripts in the context of selected
-web pages, effectively rewriting the pages inside the browser.
-
-You supply a set of scripts to the page-mod and a [`match
-pattern`](packages/api-utils/match-pattern.html) which identifies, by URL,
-a set of web pages. When the user visits these pages the scripts are attached
-and executed.
-
-This is the module you should use if you need to modify web pages or simply to
-retrieve content from pages the user visits.
-
-### [selection](packages/addon-kit/selection.html) ###
-
-Using this module your add-on can get and set any selection in the active web
-page, either as text or HTML.
-
-### [page-worker](packages/addon-kit/page-worker.html) ###
-
-Using a page worker, an add-on can load a page and access its DOM without
-displaying it to the user.
-
-This is the module to use if you want to interact with a page's DOM without
-the user's involvement.
-
-### [request](packages/addon-kit/request.html) ###
-
-This module enables you to make network requests from your add-on.
-
-## Interacting with the Browser ##
-
-These APIs enable your add-on to interact with the browser itself.
-
-### [clipboard](packages/addon-kit/clipboard.html) ###
-
-The `clipboard` module enables you to get and set the contents of the system
-clipboard.
-
-### [private-browsing](packages/addon-kit/private-browsing.html) ###
-
-`private-browsing` enables your add-on to start and stop private browsing mode,
-and to be notified when the browser starts or stops private browsing
-mode.
-
-You should use these notifications to ensure your add-on respects private
-browsing.
-
-### [tabs](packages/addon-kit/tabs.html) ###
-
-This module enables you to interact with the currently open tabs and to open
-new tabs.
-
-You can get the list of open tabs and the current active tab, and get
-notified of tabs opening and closing, or becoming active and inactive.
-
-You can retrieve each tab and get certain information about it such as its URL.
-
-Note that you can't access the content hosted by the tab using this API: if you
-want to do this, use the [`page-mod`](packages/addon-kit/page-mod.html) API.
-
-### [windows](packages/addon-kit/windows.html) ###
-
-Like the `tabs` module, but for windows: this module enables you to
-interact with currently open windows and to open new windows.
-
-You can get the list of open windows, the current active window, and get
-notified of windows opening and closing, or becoming active and inactive.
-
-You can retrieve each window and get certain information about it such as the
-list of tabs it hosts.
-
-Again: you can't access the content hosted by the window using this API, and if
-you want to do this use the [`page-mod`](packages/addon-kit/page-mod.html)
-API.
-
-## Dealing with Data ##
-
-### [simple-storage](packages/addon-kit/simple-storage.html) ###
-
-This module provides your add-on with persistent storage.
-
-### [self](packages/addon-kit/self.html) ###
-
-Using this module you can access any files you have included in your add-on's
-`data` directory.
-
-For example: if your add-on uses [content
-scripts](dev-guide/addon-development/web-content.html) and you have chosen to
-supply them as separate files, you use `self` to retrieve them. Similarly, if
-your add-on includes an icon or some HTML content to display in a
-[`panel`](packages/addon-kit/panel.html) you can store the files in your
-`data` directory and retrieve them using `self`.
-
-This module also gives your add-on access to its [Program
-ID](dev-guide/addon-development/program-id.html).
-
-Note that the `self` module is completely different from the global `self`
-object accessible to content scripts, which is used by a content script to
-[communicate with the add-on code](dev-guide/addon-development/content-scripts/using-port.html).
View
23 doc/dev-guide-source/addon-development/getting-started.md
@@ -1,23 +0,0 @@
-<!-- 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/. -->
-
-# Getting Started #
-
-This tutorial provides a practical step by step introduction to developing
-add-ons with the SDK.
-
-### [A Simple Add-on](dev-guide/addon-development/implementing-simple-addon.html) ###
-Takes you through the process of implementing, running, and packaging a simple
-add-on.
-
-### [CommonJS, Packages, Modules and the SDK](dev-guide/addon-development/commonjs.html) ###
-A quick introduction to the CommonJS standard and the relationship between
-CommonJS and the SDK.
-
-### [Reusable Modules](dev-guide/addon-development/implementing-reusable-module.html) ###
-Goes through the process of creating your own modules, to help you structure
-your add-on and promote code reuse.
-
-### [Troubleshooting](dev-guide/addon-development/troubleshooting.html) ###
-Some pointers for help if you get stuck.
View
24 doc/dev-guide-source/addon-development/guides.md
@@ -1,24 +0,0 @@
-<!-- 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/. -->
-
-# Programming Guides #
-
-### [Two Types of Scripts](dev-guide/addon-development/two-types-of-scripts.html) ###
-An introduction to the different sorts of scripts you can write, and
-a summary of which APIs are available to which scripts.
-
-### [Working with Events](dev-guide/addon-development/events.html) ###
-Writing event-driven code using the SDK.
-
-### [Working with Content Scripts](dev-guide/addon-development/web-content.html) ###
-How to write code that interacts with web content using content scripts.
-
-### [The Program ID](dev-guide/addon-development/program-id.html) ###
-What the program ID is and why it matters to your add-on.
-
-### [Module Search](dev-guide/addon-development/module-search.html) ###
-How the `require()` function finds the module you asked for.
-
-### [Firefox Compatibility](dev-guide/addon-development/firefox-compatibility.html) ###
-How SDK versions map to Firefox versions.
View
188 doc/dev-guide-source/addon-development/implementing-reusable-module.md
@@ -1,188 +0,0 @@
-<!-- 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/. -->
-
-# Implementing Reusable Modules #
-
-So far we've seen how you can use the SDK to build a simple add-on. But you
-can also use the SDK to create reusable CommonJS modules with clearly defined
-APIs. These modules are then usable by any other program which follows the
-CommonJS standard, including other add-ons built using the SDK.
-
-Even if you do not expect to provide reusable modules to other developers, it
-can often make sense to structure a larger or more complex add-on as a
-collection of modules. This makes the design of the add-on easier to understand
-and provides some encapsulation as each module will export only what it chooses
-to, so you can change the internals of the module without breaking its users.
-
-In this example we'll start with the [wikipanel
-add-on](dev-guide/addon-development/implementing-simple-addon.html), and create
-a separate module containing the code that loads the panel.
-
-## Implementing "wikipanel.js" ##
-
-In the `lib` directory under your wikipanel's root, create a new file called
-`wikipanel.js` with the following contents:
-
- // Define the 'lookup' function using Panel
- function lookup(item) {
- var panel = require("panel").Panel({
- width: 240,
- height: 320,
- contentURL: getURL(item)
- });
- panel.show();
- }
-
- // Define a function to build the URL
- function getURL(item) {
- if (item.length === 0) {
- throw ("Text to look up must not be empty");
- }
- return "http://en.wikipedia.org/w/index.php?title=" + item + "&useformat=mobile";
- }
-
- // Export the 'lookup' and 'getURL' functions
- exports.lookup = lookup;
- exports.getURL = getURL;
-
-The `lookup()` function here is essentially the same as the `lookup()` in the
-original code.
-
-Just so we can demonstrate the SDK's unit testing framework, we've also
-split the code that creates the URL into its own trivial `getURL()` function.
-
-We export both functions by adding them to the global `exports` object.
-
-## Editing "main.js" ##
-
-Next we edit `main.js` to make it use our new module rather than the `panel`
-module:
-
- // Import the APIs we need.
- var contextMenu = require("context-menu");
- var wikipanel = require("wikipanel");
-
- exports.main = function(options, callbacks) {
- console.log(options.loadReason);
-
- // Create a new context menu item.
- var menuItem = contextMenu.Item({
- label: "What's this?",
- // Show this item when a selection exists.
- context: contextMenu.SelectionContext(),
- // When this item is clicked, post a message back with the selection
- contentScript: 'self.on("click", function () {' +
- ' var text = window.getSelection().toString();' +
- ' self.postMessage(text);' +
- '});',
- // When we receive a message, look up the item
- onMessage: function (item) {
- console.log('looking up "' + item + '"');
- wikipanel.lookup(item);
- }
- });
- };
-
-Next, execute `cfx run` again, and try out the add-on. It should work in
-exactly the same way as the previous version, except that now the core
-`lookup()` function has been made available to other parts of your add-on or
-to any other module that imports it.
-
-## Testing Your Module ##
-
-The SDK provides a framework to help test any modules you develop. To
-demonstrate this we will add a test for the `getURL` function.
-
-Navigate to the `test` directory and delete the `test-main.js` file. In its
-place create a file called `test-wikipanel.js` with the following contents:
-
- var wikipanel = require("wikipanel/wikipanel")
-
- var referenceURL =
- "http://en.wikipedia.org/w/index.php?title=Mozilla&useformat=mobile";
-
- function test_getURL(test) {
- test.assertEqual(wikipanel.getURL("Mozilla"), referenceURL);
- test.done();
- }
-
- function test_empty_string(test) {
- test.assertRaises(function() {
- wikipanel.getURL("");
- },
- "Text to look up must not be empty");
- };
-
- exports.test_getURL = test_getURL;
- exports.test_empty_string = test_empty_string;
-
-This file:
-
-* exports two functions, each of which expects to receive a single
-argument which is a `test` object. `test` is supplied by the
-[`unit-test`](packages/api-utils/unit-test.html) module and provides
-functions to simplify unit testing.
-The first function calls `getURL()` and uses [`test.assertEqual()`](packages/api-utils/unit-test.html#assertEqual(a, b, message))
-to check that the URL is as expected.
-The second function tests the wikipanel's error-handling code by passing an
-empty string into `getURL()` and using
-[`test.assertRaises()`](packages/api-utils/unit-test.html#assertRaises(func%2C predicate%2C message))
-to check that the expected exception is raised.
-
-* imports one module, the `wikipanel` module that lives in our
-`wikipanel` package. The `PACKAGE/MODULE` ("wikipanel/wikipanel") syntax lets
-you identify a specific module in a specific package, rather than searching
-all available packages (using, for example, `require("request")`). The
-[module-search](dev-guide/addon-development/module-search.html) documentation
-has more detail on this.
-
-At this point your package ought to look like this:
-
-<pre>
- /wikipanel
- package.json
- README.md
- /doc
- main.md
- /lib
- main.js
- wikipanel.js
- /test
- test-wikipanel.js
-</pre>
-
-Now execute `cfx --verbose test` from under the package root directory.
-You should see something like this:
-
-<pre>
-Running tests on Firefox 7.0.1/Gecko 7.0.1 ({ec8030f7-c20a-464f-9b0e-13a3a9e97384}) under Darwin/x86_64-gcc3.
-info: executing 'test-wikipanel.test_empty_string'
-info: pass: a == b == "Text to look up must not be empty"
-info: executing 'test-wikipanel.test_getURL'
-info: pass: a == b == "http://en.wikipedia.org/w/index.php?title=Mozilla&useformat=mobile"
-
-2 of 2 tests passed.
-OK
-</pre>
-
-What happens here is that `cfx test`:
-
-<span class="aside">Note the hyphen after "test" in the module name.
-`cfx test` will include a module called "test-myCode.js", but will exclude
-modules called "test_myCode.js" or "testMyCode.js".</span>
-
-* looks in the `test` directory of your
-package
-* loads any modules whose names start with the word `test-`
-* calls all their exported functions, passing them a `test` object
-implementation as their only argument.
-
-Obviously, you don't have to pass the `--verbose` option to `cfx` if you don't
-want to; doing so just makes the output easier to read.
-
-## Next: Introducing the SDK's APIs ##
-
-Next we'll summarize the
-[APIs provided by the SDK](dev-guide/addon-development/api-intro.html).
-
View
313 doc/dev-guide-source/addon-development/implementing-simple-addon.md
@@ -1,313 +0,0 @@
-<!-- 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/. -->
-
-# Implementing a Simple Add-on #
-
-This section of the tutorial takes you through the process of implementing,
-running and packaging a simple add-on using the SDK. The add-on will add a
-menu item to Firefox's context menu, to appear when anything in the page
-is selected. The menu item displays a popup dialog containing the
-Wikipedia entry for the selected text.
-
-## Initializing Your Add-on ##
-
-Create a directory called `wikipanel`. This is where we will keep all the
-files for this add-on.
-
-You *do not* have to create this directory under the SDK root: once you have
-called `source bin/activate` from the SDK root, `cfx` will remember where the
-SDK is, and you will be able to reference SDK packages from any directory.
-
-Keeping your add-on code outside the SDK is good practice as it makes it easier
-for you to update the SDK and to manage your code using a version control
-system.
-
-Next we'll use `cfx init` to create a skeleton structure for your add-on.
-Navigate to the `wikipanel` directory and execute `cfx init`. You should see
-something like this:
-
-<pre>
- * lib directory created
- * data directory created
- * test directory created
- * doc directory created
- * README.md written
- * package.json written
- * test/test-main.js written
- * lib/main.js written
- * doc/main.md written
-
- Your sample add-on is now ready for testing:
- try "cfx test" and then "cfx run". Have fun!"
-</pre>
-
-First, `cfx init` creates the directory structure your add-on needs:
-
-<span class="aside">
-When you create add-ons using the SDK, you might create two different sorts of
-scripts.
-All add-ons will create at least one script under `/lib`. Some add-ons
-will also create "content scripts" stored under `/data`.
-For more information
-on the difference between these two sorts of files, see
-[Two Types of Scripts](dev-guide/addon-development/two-types-of-scripts.html).
-</span>
-