Rework the content scripts guide

RESOLVED FIXED

Status

P2
normal
RESOLVED FIXED
4 years ago
4 years ago

People

(Reporter: wbamberg, Assigned: wbamberg)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

Attachments

(1 attachment)

(Assignee)

Description

4 years ago
I've just had a go at reorganizing the content scripts guide. All the new stuff is currently under my user page for the time being, but I intend to move it under https://developer.mozilla.org/en-US/Add-ons/SDK/Guides when it's been reviewed.

The main idea of this is that the old guide was organized as a collection of pages with no real "overview", so there wasn't a very clear indication of what was the stuff you were almost certain to have to know, and what was the stuff that was more specialized. In this guide I've tried to make the main page https://developer.mozilla.org/en-US/docs/User:wbamberg/cs cover everything you're likely to need to know in one place, and linked out to sub-pages for more specialized things like unsafeWindow and x-domain content scripts.

I've also updated the content in quite a few places.

There are three new pages:
* the main page: https://developer.mozilla.org/en-US/docs/User:wbamberg/cs
* interacting with page scripts: https://developer.mozilla.org/en-US/docs/User:wbamberg/cs/Interacting_with_page_scripts (This includes updated stuff on cloneInto() and friends)
*  quirks of DOM access: https://developer.mozilla.org/en-US/docs/User:wbamberg/cs/Quirks_of_accessing_the_DOM_from_a_content_script

I intend for these pages to replace the existing content script guide:
https://developer.mozilla.org/en-US/Add-ons/sdk/Guides/Content_Scripts
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Loading_Content_Scripts
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Accessing_the_DOM
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Communicating_With_Other_Scripts
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Reddit_Example

I'm keeping these two pages more or less intact:
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/using_postMessage
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Cross_Domain_Content_Scripts

One thing I've done that might be arguable is not include panel in the guide, or any other UI modules that are specified with HTML. This is basically because the APIs we provide for these UI modules - panel, sidebar, frame - are all inconsistent with the other content scripting modules and with each other. So it's really hard to tell a consistent story about these APIs, and I thought it might be less confusing to describe them individually.

One this I would still like to do is write a much bigger "examples" page. There are lots of inline examples in this guide, and I'd like to take them all, plus a couple more, and keep them in their own page, along with a link to a repo for them all. But I'd like to deal with that in a different bug.
(Assignee)

Comment 1

4 years ago
Created attachment 8433626 [details] [diff] [review]
mdn.html
Attachment #8433626 - Flags: review?(jgriffiths)
(Assignee)

Comment 2

4 years ago
Comment on attachment 8433626 [details] [diff] [review]
mdn.html

Connor, since you're not so familiar with this already, I'd love to hear your feedback on the updates, especially on whether they are easier going than the original stuff.
Attachment #8433626 - Flags: feedback?(cbrem)
Comment on attachment 8433626 [details] [diff] [review]
mdn.html

As discussed, looks great.
Attachment #8433626 - Flags: review?(jgriffiths) → review+
Priority: -- → P2
(Assignee)

Comment 4

4 years ago
Thanks Jeff. I've also pulled out all the examples from this guide into a repo: https://github.com/mdn/addon-sdk-content-scripts in the hope that it's more usable like that.
Status: NEW → RESOLVED
Last Resolved: 4 years ago
Resolution: --- → FIXED
(Assignee)

Comment 5

4 years ago
I've relocated the guide to its proper place: https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts.
(In reply to Will Bamberg [:wbamberg] from comment #0)
...
> One this I would still like to do is write a much bigger "examples" page.
> There are lots of inline examples in this guide, and I'd like to take them
> all, plus a couple more, and keep them in their own page, along with a link
> to a repo for them all. But I'd like to deal with that in a different bug.

Hi Will!

The github repo is great!

How about enabling jshint and -- because it does not check indentation as of v2.5.0 -- jscs  on it?

Which would be the relevant style guide to comply with?

There are
https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style
and
https://github.com/mozilla/addon-sdk/wiki/Coding-style-guide
to start with, perhaps there's more.

Having test cases in the repo with the cs samples is a great start.

I have been experimenting with https://github.com/jsdoc3/jsdoc as of late, and it is a bit of a rough start.

It does not produce any output until you put in tags like @fileoverview, @class, @global.

But then it is pretty nice, especially with the jaguarjs templates (which currently fail to link to the global.html file, see https://github.com/davidshimjs/jaguarjs-jsdoc/issues/5).
(In reply to adrian from comment #6)
...
> Which would be the relevant style guide to comply with?

> https://github.com/mozilla/addon-sdk/wiki/Coding-style-guide

This one, to keep consistent with all other SDK-related material.
So here is my first try:

https://github.com/mdn/addon-sdk-content-scripts/pull/2

I am also looking into eslint checking now, which makes it easy to turn certain violation off, into warnings, into errors (think travis ci).

eslint does not do any style checking, hence the use of jscs as well.

jshint is doing away with indentation checking completely as of v2.5.0.
It won't tell you, just ignore those options like indent, trailing, white and leave you thinking all is well.
(In reply to adrian from comment #6)
> (In reply to Will Bamberg [:wbamberg] from comment #0)
> ...
> > One this I would still like to do is write a much bigger "examples" page.
> > There are lots of inline examples in this guide, and I'd like to take them
> > all, plus a couple more, and keep them in their own page, along with a link
> > to a repo for them all. But I'd like to deal with that in a different bug.
> 
> Hi Will!
> 
> The github repo is great!
> 
...
> I have been experimenting with https://github.com/jsdoc3/jsdoc as of late,
> and it is a bit of a rough start.
> 
> It does not produce any output until you put in tags like @fileoverview,
> @class, @global.
> 
> But then it is pretty nice, especially with the jaguarjs templates (which
> currently fail to link to the global.html file, see
> https://github.com/davidshimjs/jaguarjs-jsdoc/issues/5).

The gaia project is probably one of the best examples of jsodc3 usage.

See
https://github.com/mozilla-b2g/gaia#generate-jsdoc

The generated docs are also available at
http://alivedise.github.io/gaia-system-jsdoc/global.html#
Attachment #8433626 - Flags: feedback?(cbrem) → feedback-
Attachment #8433626 - Flags: feedback- → feedback+
You need to log in before you can comment on or make changes to this bug.