566261 - step-by-step tutorial for creating an addon using FlightDeck

Status: RESOLVED FIXED

(Mozilla Labs Graveyard :: FlightDeck, defect, P1)

Description

[Myk Melez [:myk] [@mykmelez]]

There should be a step-by-step tutorial for creating an addon using FlightDeck.  The goal of the tutorial should be to enable a casual developer who visits the site to use the site to create a simple, functional addon within a short period of time.

Note that the FlightDeck feature set and interface is in flux, and it will probably continue to change for some time, so whatever we write will need to be updated regularly.

The available API set is also in flux as we continue to build out the underlying SDK, so we'll also want to revisit the tutorial regularly to see if such changes warrant updating the tutorial to make sure it continues to provide the best example of a simple, functional addon given the current API set.

I'm not sure where this tutorial should live.  On the FlightDeck website itself?  On some other site?

Comment 1

[Piotr Zalewa [:zalun]]

Re: where it should live.

Technically it can be on the FlightDeck website. The only problem is data. If it will be written in code and send to github, then everything's fine. If using some sort of CMS in a separate database I guess it wpuld be fine as well. The only problem might be holding CMS in the same database as current Jetpacks, as it will be wiped.

Comment 2

[Myk Melez [:myk] [@mykmelez]]

I don't think the tutorial needs to be stored in a database, as I expect it'll be written in HTML and CSS, which we should be able to accommodate as part of the FlightDeck website's code.

But Atul has expressed an interest in taking this on, so I'm assigning this to him and will let him make the decision about where and how to host it.

Comment 3

[Atul Varma [:atul]]

Attachment: First shot at a tutorial

Here's a first attempt. Obviously the CSS will need to be redone, at the very least, I was just using what's there out of personal preference.

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 452106 [details]
First shot at a tutorial

This page needs to be wrapped in the standard site header/footer plus the documentation sidebar.  Atul, is that something you can do, or do we need Piotr's help incorporating this into the site?


>  <base href="http://flightdeck.zalewa.info/" target="_blank">

The base URL needs to vary by server.  Is it necessary to include it?  It looks like the URLs this document uses will work correctly without it (once the page is on the site, anyway).


><p>The Add-ons Builder makes it easy to write, test, and build add-ons
>that extend the browser.</p>

Nit: The Add-ons Builder -> Add-ons Builder


><p>To get started, first log into the site with your <a
>  href="https://addons.mozilla.org/">addons.mozilla.org</a>
> credentials and click on the button labeled <a
>  href="http://flightdeck.zalewa.info/addon/new/">Create
> Add-on</a>.</p>

Nit: log into -> sign into
Nit: button labeled Create Add-on -> Create Add-on button
Nit: credentials -> account (Credentials is a great word that I love to use in technical discussion, but my sense is that regular users typically think of them either as their "username/password" or their "account"; I'd love to change that, but I'm not sure this is the right venue for that. We use "account" elsewhere on FlightDeck.)

Also, it's great to include the button in the tutorial, but we should include the actual button (making it open in a new tab) rather than a link that does the same thing the button does.

And it would be handy if these instructions describe what is going to happen after each step you take, so you know what to expect and can tell if something has gone wrong.

Finally, I would reverse the Sign In and press Create Add-on button steps, since pressing the Create Add-on button will take you to the Sign In page if you aren't already signed in.

So I would make this something like:

    <p>To get started, first press the Create Add-on button.</p>
    
        [Create Add-on button]
    
    <p>Then Add-ons Builder will create a blank new add-on and take you to
    an interface for building it.</p>

    <p>Note: if you aren't signed in yet, you'll be asked to sign in with your
    <a href="https://addons.mozilla.org/">addons.mozilla.org</a> account.
    Don't have an account?
    <a href="https://addons.mozilla.org/users/register">Register for one!</a>
    </p>


><p>Then type the following code into the editing area:</p>
>
><pre>
>  var widgets = require("widget");
>
>  widgets.add(widgets.Widget({
>    label: "Mozilla",
>    image: "http://www.mozilla.org/favicon.ico"
>  }));
></pre>
>
><p>Click <i>Test</i> and a Mozilla logo (<img
>src="http://www.mozilla.org/favicon.ico" style="width: 1em; height: 1em">)
>should appear at the bottom-left corner of your browser.</p>

This should mention that you'll be asked to install the Helper add-on if you haven't already installed it!


><p>Of course, you may have made a typo, in which case nothing new appears
>in your browser and you are confused. If this is the case, go to
>Firefox's "Tools" menu and select "Error Console". Make sure that the
>"All" button appears pressed down in this window, and any errors in
>your code should be logged there.</p>

Nit: proper nouns like Tools, Error Console, and All (plus Create Add-on in the phrase "Create Add-on button" earlier in this document) would be more visually distinct and noticeable if we were to use italics, bold, monospaced fonts, or other typographic style to highlight them (as opposed to quotation marks, which have been historically used for such highlighting mostly because typewriters didn't permit the use of typographic style).


><p>This is a terrible debugging aid, we know&mdash;but trust us, this
>is just the beginning, and it'll be a lot better soon!</p>

There's no need to beat ourselves up about this. It doesn't particularly endear us to our audience, and it can come off as insincere (especially when accompanied by "trust us"!).

I don't think it's necessary or advisable to say anything here, given that our plans are currently amorphous, but if you really want to plug that we are going to make unspecified future improvements to error reporting, then I would say something simple like:

<p>Stay tuned for improvements to error reporting in future versions of Firefox.</p>


><p>Clicking on the button doesn't do anything though, so let's
>change that.</p>

Nit: button -> widget
Nit: anything though -> anything, though
Nit: . -> : (since this sentence references the code after it)

Also, I would be more explicit about what is happening here and say:

    <p>Clicking the widget doesn't do anything, though, so let's change that
    by adding a click handler:</p>


><pre>
>  var widgets = require("widget");
>
>  widgets.add(widgets.Widget({
>    label: "Visit The Mozilla Website",
>    image: "http://www.mozilla.org/favicon.ico",
>    onClick: function(event) {
>      event.view.content.location = "http://www.mozilla.org";
>    }}));
></pre>

Nit: it'd be nice if the code that has been added relative to the previous example were highlighted to show what has changed (for users who want to cut/paste or retype just that portion).

Also, it'd be better to use the tabs API to demonstrate opening a new tab, since it is more intuitive than event.view.content.location and shows the use of another high-level API, i.e.:

    onClick: function(event) {
      require("tabs").open("http://www.mozilla.org");
    }


><p>Now when you click on the button, the Mozilla website opens in the
>current tab, replacing whatever content was already there.</p>

If we use the tabs API, then this should say opens in a new tab, of course.


>family. Fortunately, that's really easy to do: the Add-ons Builder, as
>its name suggests, lets you create add-ons that work with the latest
>version of Firefox, no strings attached.</p>

the Add-ons Builder -> Add-ons Builder


><p>First you need to give your add-on a real name, a description, and
>a version number. Just click on the text "My Add-on" on the left side
>of the page and fill in the fields; we suggest starting at version
>0.0.1.</p>

Really? I'd think 0.1 would be sufficient.


><p>Then just click <i>Download</i> to get the XPI file that
>constitutes your addon. You can send this to friends and family, or

Nit: addon -> add-on


>people's addons</a>, view their source code and see how they work.</p>

Nit: addons -> add-ons


><p>Whatever you choose, we hope you enjoy making addons! Don't forget

Nit: addons -> add-ons


>to visit the <a href="https://forums.addons.mozilla.org/">Add-ons
>Forum</a> if you have any questions or want to share something with
>the rest of the community.</p>

In the footer of the site and the documentation landing page, we direct people with questions to the Jetpack discussion group.  We should do the same here as well (or change them all to point to the Add-ons Forum).

Comment 5

[Daniel Buchner [:dbuc]]

Piotr said he had the page stub done for this, so it should drop right into the design, I will confirm this again tomorrow!

Comment 6

[Atul Varma [:atul]]

(In reply to comment #4)
> (From update of attachment 452106 [details])
> This page needs to be wrapped in the standard site header/footer plus the
> documentation sidebar.  Atul, is that something you can do, or do we need
> Piotr's help incorporating this into the site?

I suspect we'll need Piotr's help, and that he might find it easiest to put it into whatever templating system he's likely using.

> >  <base href="http://flightdeck.zalewa.info/" target="_blank">
> 
> The base URL needs to vary by server.  Is it necessary to include it?  It looks
> like the URLs this document uses will work correctly without it (once the page
> is on the site, anyway).

Exactly--I only included the base href here so that you could actually click on the links while viewing it as hosted on https://bugzilla.mozilla.org/attachment.cgi?id=452106, so you'd know where they went without having to manually copy and paste things. All that needs to be done to make it "production-ready" is to remove the base href.

> Nit: credentials -> account (Credentials is a great word that I love to use in
> technical discussion, but my sense is that regular users typically think of
> them either as their "username/password" or their "account"; I'd love to change
> that, but I'm not sure this is the right venue for that. We use "account"
> elsewhere on FlightDeck.)

D'oh, agreed, will do.

> Also, it's great to include the button in the tutorial, but we should include
> the actual button (making it open in a new tab) rather than a link that does
> the same thing the button does.

Okay... This might be something that Piotr could do easily, since the button isn't actually an image on the site, it's a bunch of HTML and CSS. I suspect this will be particularly advantageous once l10n comes into play... So is it ok if I just put a placeholder in for now?

> So I would make this something like:

Sounds good, I'll fix that.

> Nit: proper nouns like Tools, Error Console, and All (plus Create Add-on in the
> phrase "Create Add-on button" earlier in this document) would be more visually
> distinct and noticeable if we were to use italics, bold, monospaced fonts, or

My bad, I will replace it with italix, since that's what I used for the buttons on the site.

> Also, I would be more explicit about what is happening here and say:
> 
>     <p>Clicking the widget doesn't do anything, though, so let's change that
>     by adding a click handler:</p>

Will do!

> Also, it'd be better to use the tabs API to demonstrate opening a new tab,
> since it is more intuitive than event.view.content.location and shows the use
> of another high-level API, i.e.:
> 
>     onClick: function(event) {
>       require("tabs").open("http://www.mozilla.org");
>     }

Oh, nice, didn't realize the tabs API actually made it in. Will definitely use that instead--not only is it more intuitive, but it also won't result in the user accidentally replacing their FlightDeck tab with the Mozilla website, which is what happened to me the first time I used it.

> ><p>First you need to give your add-on a real name, a description, and
> >a version number. Just click on the text "My Add-on" on the left side
> >of the page and fill in the fields; we suggest starting at version
> >0.0.1.</p>
> 
> Really? I'd think 0.1 would be sufficient.

Hehe, sure.

> In the footer of the site and the documentation landing page, we direct people
> with questions to the Jetpack discussion group.  We should do the same here as
> well (or change them all to point to the Add-ons Forum).

Sounds good, I'll do that.

Comment 7

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #6)
> >     onClick: function(event) {
> >       require("tabs").open("http://www.mozilla.org");
> >     }

Erm, except it's actually:

    onClick: function(event) {
      require("tabs").open(require("url").URL("http://www.mozilla.org"));
    }

:-/

I'm starting to rethink the "URL" constructor pattern.

Comment 8

[Atul Varma [:atul]]

Oh noes!

It seems like these routines that take URLs ought to be able to take strings in the case where the scheme is just http: or https:... is there a security reason that would be bad?

Anyways, I guess it's too late to fix it for this release. :(

Comment 9

[Atul Varma [:atul]]

Attachment: Fixes myk's concerns

Here's a new version. The only thing I didn't change was using require("tabs"), solely because I think the require("url").URL() bit is an unfortunate doozy. I would really, really like to get rid of that if at all possible. As a compromise, perhaps making URL a globally-available constructor might be feasible. Though it'd still raise the question of why the "image" property of the Widget is a bare string...

Anyways, I can still change it to require("tabs") if you'd like, just holding off on it for now in case we can think of something better.

Comment 10

[Atul Varma [:atul]]

Also, I'm keeping this stuff in an hg repo on my local computer, so if you want diffs between the different revisions of the copy I'm giving you, I can do that.

Comment 11

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 452181 [details]
Fixes myk's concerns

(In reply to comment #8)
> It seems like these routines that take URLs ought to be able to take strings
> in the case where the scheme is just http: or https:... is there a security
> reason that would be bad?

The security reason is that APIs that accept both HTML text and a URL via a single "content" parameter might load URLs received from untrusted services instead of displaying them as text if URLs are passed to them as strings.

But this is not an issue for APIs that only take URLs.  And for the rest, I'm starting to rethink the decision to standardize on URL objects across the API set.  There are no perfect solutions, but the current one is starting to feel like it isn't the best one.


(In reply to comment #9)
> Here's a new version. The only thing I didn't change was using
> require("tabs"), solely because I think the require("url").URL() bit is an
> unfortunate doozy. I would really, really like to get rid of that if at all
> possible.

It's possible, although it's very late in the 0.5 timeframe for such changes.  Nevertheless, I have filed bug 572977 and suggested that we make it.


> As a compromise, perhaps making URL a globally-available constructor might be
> feasible. Though it'd still raise the question of why the "image" property of
> the Widget is a bare string...

Yes, we should be consistent with such properties.


> Anyways, I can still change it to require("tabs") if you'd like, just holding
> off on it for now in case we can think of something better.

I think it's the right thing to do, even if the API remains the way it is.  It's still better than event.view.content.location.


><!-- This is a horrible approximation of the same button on the
>     front page of Add-ons Builder. It should be replaced by
>     "the real thing". -->
><ul id="new-addon">
>  <li>
>    <a id="create_addon" href="/addon/new/"><span>Create
>    Add-on</span></a>
>  </li>
></ul>
><p>To get started, first press the <i>Create Add-on</i> button.</p>

Nit: the button looks funky with text wrapped around it.  I think it'd look better if it appeared in its own row underneath the paragraph that references it, i.e.:

  To get started, first press the Create Add-on
  button.

      [button]


>Don't have an account?  <a
> href="https://addons.mozilla.org/users/register">Register for
>one!</a></p>

Nit: I was the one who gave you "Register for one!", but then I remembered that on the Sign In page I wrote "Get one!", and I think that works better ("register" is an unnecessarily official-sounding term).

>
><p>Now, type the following code into the editing area:</p>
>
><pre>
>  var widgets = require("widget");
>
>  widgets.add(widgets.Widget({
>    label: "Mozilla",
>    image: "http://www.mozilla.org/favicon.ico"
>  }));
></pre>
>
><p>Click <i>Test</i>. You may now be asked to install the <i>Add-ons

Nit: "Click <i>Test</i>" would flow a bit better as "Then click <i>Test</i>" or "And click <i>Test</i>".

Otherwise looks great, r=myk!

Comment 12

[Atul Varma [:atul]]

(In reply to comment #11)
> Nit: the button looks funky with text wrapped around it.  I think it'd look
> better if it appeared in its own row underneath the paragraph that references
> it, i.e.:

I agree--it's only wrapped-around because I was trying to approximate the CSS of the original button and got it to a state where it looked OK only if it was float:right. Perhaps I should just replace it entirely with a plain-text placeholder that says [Display Create Add-on Button Here].

> Nit: I was the one who gave you "Register for one!", but then I remembered that
> on the Sign In page I wrote "Get one!", and I think that works better
> ("register" is an unnecessarily official-sounding term).

Agreed--'register' sounds like something that could somehow involve bureaucracy and waiting in line. It makes me think of DMVs.

Comment 13

[Atul Varma [:atul]]

Attachment: Latest version

Here's another version with the nits fixed and suggestions applied.

Also, the HTML source can now be searched for the string 'TODO' to find all things that need to be changed/resolved before committing this to the SDK. The only one that Piotr won't be able to fix on his own is the one that asks what forum/mailing-list we're directing users to. Because the word "Jetpack" isn't anywhere in the copy and "add-on" is everywhere, I had assumed that we'd send them off to the AMO forum and start talking to addon developers there, leaving the jetpack google group for discussion of the jetpack platform itself--if the project's social structure becomes anything like that of ubiquity or python, there will be separate communities for those who develop *on* the platform and those who develop the platform itself; though if there's a way to avoid that without overwhelming people, I am all ears.

Comment 14

[Atul Varma [:atul]]

While bug 572977 isn't a hard blocker for this bug, I'm adding it as a dependency just so we remember to change the tutorial's content if bug 572977 makes it into the 0.5 release.

Comment 15

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 452280 [details]
Latest version

(In reply to comment #13)
> Because the word "Jetpack" isn't
> anywhere in the copy and "add-on" is everywhere, I had assumed that we'd send
> them off to the AMO forum and start talking to addon developers there, leaving
> the jetpack google group for discussion of the jetpack platform itself--if the
> project's social structure becomes anything like that of ubiquity or python,
> there will be separate communities for those who develop *on* the platform and
> those who develop the platform itself; though if there's a way to avoid that
> without overwhelming people, I am all ears.

Yes, we may indeed eventually want to have two different forums for these two kinds of discussions, but we don't have that yet, and I don't want to change that right now, although we should definitely consider it for the public beta.

Comment 16

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

An AMO-hosted forum would be easier for users, wouldn't it? They already have an AMO account to get in to Addons Builder. Less confusion than tossing them over to some non-Mozilla site's forum/newsgroup, imo.

Comment 17

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #16)
> An AMO-hosted forum would be easier for users, wouldn't it?

Perhaps.


> They already have an AMO account to get in to Addons Builder.

Right. On the other hand, AMO forums are much less usable than Google Groups.


And the primary audience for the upcoming preview release is Jetpack project participants, which are primarily subscribers to the Jetpack discussion group on Google Groups.  So it's the right place to direct users of the preview release.

That may well change for the public beta release, which we intend to promote to the broadest possible audience of interested parties.  At that point, it may well make sense to direct users to a forum specifically for users of the product (as opposed to project participants), and that forum may well be the AMO forums.

But we're not there yet.

Comment 18

[Atul Varma [:atul]]

Attachment: Replaced AMO Forum link with Jetpack Google Group link

It is done!

Comment 19

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 452362 [details]
Replaced AMO Forum link with Jetpack Google Group link

(In reply to comment #18)
> It is done!

Woot!

Piotr: this is ready for checkin.

Comment 20

[Piotr Zalewa [:zalun]]

Live

Comment 21

[Piotr Zalewa [:zalun]]

Looks good

Template code:
http://github.com/zalun/FlightDeck/blob/master/flightdeck/tutorial/templates/tutorial.html
Style code:
http://github.com/zalun/FlightDeck/blob/master/flightdeck/tutorial/media/css/UI.Tutorial.css

Please fork and make further changes directly in these files.