1058556 - Content script self object documentation should describe properties and methods like SDK modules do

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: Add-ons, defect)

Description

[Adrian Aichner [:anaran]]

+++ 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

Comment 2

[Will Bamberg [:wbamberg]]

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!

Comment 3

[Adrian Aichner [:anaran]]

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].

Comment 4

[Will Bamberg [:wbamberg]]

Thanks Adrian. I made those 2 changes, and am closing this one now.

Comment 5

[Adrian Aichner [:anaran]]

(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.