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)

x86
Windows XP
defect
Not set
normal

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
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)
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)
Thanks Adrian. I made those 2 changes, and am closing this one now.
Status: UNCONFIRMED → RESOLVED
Closed: 10 years ago
Resolution: --- → FIXED
(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.