Closed
Bug 1058556
Opened 10 years ago
Closed 10 years ago
Content script self object documentation should describe properties and methods like SDK modules do
Categories
(Developer Documentation Graveyard :: Add-ons, defect)
Tracking
(Not tracked)
RESOLVED
FIXED
People
(Reporter: anaran, Assigned: wbamberg)
References
()
Details
+++ This bug was initially created as a clone of Bug #1058552 +++
(How can it be a true clone without all the typos of the original, which is the point of this clone?)
See:
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts#Accessing_port_in_the_content_script
Details:
The self object is not to be confused with the Addon-SDK self module.
The Note in this section makes a good start at pointing that out.
But then it falls short to provide a clear overview of the self object.
The sidebar covers the object but does not reveal its structure:
The port API
port.emit()
port.on()
port.removeListener()
port.once()
JSON-serializable values
The postMessage API
Suggestion:
-----------
Follow the convention used by the Add-on SDK for describing objects.
E.g.
https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/tabs#Tab
describes the structure of objects well in the sidebar:
Globals
Functions
open(options)
Properties
activeTab
length
Events
open
close
ready
activate
deactivate
Tab
Methods
pin()
unpin()
close(callback)
reload()
activate()
getThumbnail()
attach(options)
Properties
id
title
url
favicon
contentType
index
isPinned
window
Events
close
ready
load
pageshow
activate
deactivate
I would suggest to do the same for the content script self object, leading to this structure in the sidebar:
Self
Properties:
port
Methods:
postMessage
on
once
removeListener
Port
Methods:
emit
on
once
removeListener
Assignee | ||
Comment 2•10 years ago
|
||
Thanks for such constructive feedback. I agree that this seems like an improvement. I experimented a bit and in the end drafted two new pages:
* one on self: https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/self
* one on port: https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/port
...that are structured like the module API pages. I've kind of skimped on self's messaging API, since for almost all purposes "port" is better. For "port" I've moved the content from https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts#The_port_API.
(I thought it was confusing covering both APIs in one page, because one of them (self) is only available in content scripts, while the other (port) exists on both sides of the conversation.
I'd appreciate your feedback on this. Thanks!
Flags: needinfo?(adrian.aichner)
Reporter | ||
Comment 3•10 years ago
|
||
Looks good to me, Will!
Two points I noticed:
1. Should we point out the other major serialization pitfall, circular objects, in
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/port#JSON-serializable_values
as well?
2. Broken link ...
See this link:
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/self_and_port#JSON-serializable_values
referenced from
https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/self
Details:
This takes a single parameter, the message payload, which may be any [JSON-serializable value].
Flags: needinfo?(adrian.aichner)
Assignee | ||
Comment 4•10 years ago
|
||
Thanks Adrian. I made those 2 changes, and am closing this one now.
Status: UNCONFIRMED → RESOLVED
Closed: 10 years ago
Resolution: --- → FIXED
Reporter | ||
Comment 5•10 years ago
|
||
(In reply to Will Bamberg [:wbamberg] from comment #4)
> Thanks Adrian. I made those 2 changes, and am closing this one now.
both fixes work well for me.
You need to log in
before you can comment on or make changes to this bug.
Description
•