724962 - Write Source Editor documentation in MDN

Status: RESOLVED FIXED

(DevTools :: Source Editor, defect, P2)

Description

[Mihai Sucan [:msucan]]

Firefox extensions are starting to use the Source Editor component even if it lacks a public page on MDN with usage examples and docs. We should have a page with such information so we can point developers to it.

Sheppy: can you or someone from the MDN docs team please help us with writing the docs? Please let me know of any help you need! You can find the code in browser/devtools/sourceeditor.

You can also find code that uses the Source Editor in Scratchpad: browser/devtools/scratchpad (see scratchpad.js and the associated xul file). Style Editor uses it in browser/devtools/styleeditor/StyleEditor.jsm and in the associated styleeditor.xul file. Scratchpad code is easier to follow - Style Editor's usage is a bit more advanced and more complex.

Suggestions:
- please mention that source-editor-orion.jsm must not be Cu.import()ed directly. Always do Cu.import() of the source-editor.jsm.

- point out that private methods and properties of SourceEditor instances are a no-no in terms of compatibility with future Firefox versions.

- point out that the API is not yet too stable and that devs should keep an eye on their use of the new Source Editor component.

There should be sections for: integration into the XUL file and initialization in the JavaScript, basic api (get/set text, selections and so on), keyboard shortcuts, theming, events and probably more.

Thank you!

Comment 1

[Rob Campbell [:rc] (:robcee)]

Moving to Source Editor component.

Filter on CHELICERAE.

Comment 2

[Anton Kovalyov (:anton)]

Assigning to me. Once I fix bug 929766 I'll write up a draft and then someone can edit it.

Comment 3

[Anton Kovalyov (:anton)]

Started writing docs here: https://etherpad.mozilla.org/11Cvq0QFIU

Comment 4

[Jason Barnabe (np)]

I'm trying to make my extension Stylish use Source Editor, so I followed Anton's WIP. Here are my results so far with Firefox 27.0a2:

1. "ReferenceError: require is not defined". Included "var require = Components.utils.import("resource://gre/modules/devtools/Loader.jsm", {}).devtools.require;".
2. How do I detect if Source Editor is available? Check the Editor variable after "let Editor = require("devtools/sourceeditor/editor");"?
3. I get "env.contentWindow is undefined editor.js:202" and things don't work. Not sure if the docs are lacking something, or if this is a bug, or my problem...

Comment 5

[Jason Barnabe (np)]

#3 was because I was passing a textbox to appendTo instead of something that is supposed to have a child.

Comment 6

[Anton Kovalyov (:anton)]

Finished writing docs: https://developer.mozilla.org/en-US/docs/Tools/Editor

Need someone to edit that since English is not my native language.

Comment 7

[Gabriel Luong [:gl] (ΦωΦ)]

Did some minor edits to the descriptions in the API section. Looks good otherwise!

Comment 8

[Anton Kovalyov (:anton)]

Thank you!