Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Bug 673187 - Remove docs server, first part; r=warner

  • Loading branch information...
commit 6d19ec4b68fd651da5b0163bdc62bc5d6b418f33 1 parent da3c144
wbamberg authored September 12, 2011

Showing 120 changed files with 1,018 additions and 247 deletions. Show diff stats Hide diff stats

  1. 6  .gitignore
  2. 0  cuddlefish/docs/__init__.py b/python-lib/cuddlefish/docs/__init__.py
  3. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/about.md
  4. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/annotator.md
  5. 4  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/creating.md
  6. 4  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/displaying.md
  7. 2  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/overview.md
  8. 2  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/storing.md
  9. 6  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/annotator/widget.md
  10. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/api-idioms.md
  11. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/api-intro.md
  12. 12  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/api-modules.md
  13. 20  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/cfx-tool.md
  14. 4  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/commonjs.md
  15. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/console.md
  16. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/content-scripts/access.md
  17. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/content-scripts/loading.md
  18. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/content-scripts/reddit-example.md
  19. 179  doc/dev-guide-source/addon-development/content-scripts/using-port.md
  20. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/content-scripts/using-postmessage.md
  21. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/events.md
  22. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/getting-started.md
  23. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/guides.md
  24. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/implementing-reusable-module.md
  25. 4  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/implementing-simple-addon.md
  26. 2  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/installation.md
  27. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/module-search.md
  28. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/package-spec.md
  29. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/program-id.md
  30. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/reference.md
  31. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/troubleshooting.md
  32. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/tutorials.md
  33. 0  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/two-types-of-scripts.md
  34. 2  {static-files/md/dev-guide → doc/dev-guide-source}/addon-development/web-content.md
  35. 0  {static-files/md/dev-guide → doc/dev-guide-source}/appendices/credits.md
  36. 0  {static-files/md/dev-guide → doc/dev-guide-source}/appendices/glossary.md
  37. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/about.md
  38. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/best-practices.md
  39. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/chrome.md
  40. 2  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/e10s.md
  41. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/globals.md
  42. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/guides.md
  43. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/reference.md
  44. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/tutorials.md
  45. 0  {static-files/md/dev-guide → doc/dev-guide-source}/module-development/xpi.md
  46. 0  {static-files/md/dev-guide → doc/dev-guide-source}/welcome.md
  47. 30  { → doc}/static-files/base.html
  48. 0  { → doc}/static-files/css/api-reference.css
  49. 0  { → doc}/static-files/css/base.css
  50. 0  { → doc}/static-files/css/footer.css
  51. 0  { → doc}/static-files/css/header.css
  52. 0  { → doc}/static-files/css/sdk-docs.css
  53. 0  { → doc}/static-files/js/jquery.js
  54. 24  { → doc}/static-files/js/main.js
  55. 175  doc/static-files/md/dev-guide/addon-development/content-scripts/access.md
  56. 60  doc/static-files/md/dev-guide/addon-development/content-scripts/loading.md
  57. 67  doc/static-files/md/dev-guide/addon-development/content-scripts/reddit-example.md
  58. 0  { → doc}/static-files/md/dev-guide/addon-development/content-scripts/using-port.md
  59. 136  doc/static-files/md/dev-guide/addon-development/content-scripts/using-postmessage.md
  60. 0  { → doc}/static-files/media/annotator/annotation-list.png
  61. 0  { → doc}/static-files/media/annotator/annotation-panel.png
  62. 0  { → doc}/static-files/media/annotator/annotator-design.png
  63. 0  { → doc}/static-files/media/annotator/editor-panel.png
  64. 0  { → doc}/static-files/media/annotator/highlight.png
  65. 0  { → doc}/static-files/media/annotator/matcher.png
  66. 0  { → doc}/static-files/media/annotator/pencil-off.png
  67. 0  { → doc}/static-files/media/annotator/pencil-on.png
  68. 0  { → doc}/static-files/media/annotator/widget-icon.png
  69. 0  { → doc}/static-files/media/bg-footer.png
  70. 0  { → doc}/static-files/media/bg-header.png
  71. 0  { → doc}/static-files/media/commonjs-modules.jpg
  72. 0  { → doc}/static-files/media/commonjs-translator.jpg
  73. 0  { → doc}/static-files/media/content-scripting-events.png
  74. 0  { → doc}/static-files/media/content-scripting-overview.png
  75. 0  { → doc}/static-files/media/favicon.png
  76. 0  { → doc}/static-files/media/firefox-32.png
  77. 0  { → doc}/static-files/media/firefox-logo.png
  78. 0  { → doc}/static-files/media/footer-logo-med.png
  79. 0  { → doc}/static-files/media/mozilla-tab.png
  80. 0  { → doc}/static-files/media/multiple-workers.jpg
  81. 0  { → doc}/static-files/media/screenshots/default-panel-osx.png
  82. 0  { → doc}/static-files/media/screenshots/default-panel-ubuntu.png
  83. 0  { → doc}/static-files/media/screenshots/default-panel-windows.png
  84. 0  { → doc}/static-files/media/screenshots/modules/context-menu-image-osx.png
  85. 0  { → doc}/static-files/media/screenshots/modules/notification-growl-osx.png
  86. 0  { → doc}/static-files/media/screenshots/modules/panel-tabs-osx.png
  87. 0  { → doc}/static-files/media/screenshots/modules/widget-content-osx.png
  88. 0  { → doc}/static-files/media/screenshots/modules/widget-icon-osx.png
  89. 0  { → doc}/static-files/media/screenshots/modules/widget-panel-osx.png
  90. 0  { → doc}/static-files/media/screenshots/translator/context-menu-osx.png
  91. 0  { → doc}/static-files/media/screenshots/translator/translated-osx.png
  92. 0  { → doc}/static-files/media/screenshots/widget-panel-clock.png
  93. 0  { → doc}/static-files/media/twitter-widget.png
  94. 0  { → doc}/static-files/syntaxhighlighter/MIT-LICENSE
  95. 0  { → doc}/static-files/syntaxhighlighter/scripts/shBrushCss.js
  96. 0  { → doc}/static-files/syntaxhighlighter/scripts/shBrushJScript.js
  97. 0  { → doc}/static-files/syntaxhighlighter/scripts/shBrushXml.js
  98. 0  { → doc}/static-files/syntaxhighlighter/scripts/shCore.js
  99. 0  { → doc}/static-files/syntaxhighlighter/styles/shCore.css
  100. 0  { → doc}/static-files/syntaxhighlighter/styles/shThemeDefault.css
  101. 2  packages/addon-kit/docs/page-mod.md
  102. 6  packages/addon-kit/docs/panel.md
  103. 2  packages/addon-kit/docs/widget.md
  104. 24  python-lib/cuddlefish/__init__.py
  105. 0  python-lib/cuddlefish/{ → docs}/apiparser.py
  106. 0  python-lib/cuddlefish/{ → docs}/apirenderer.py
  107. 224  python-lib/cuddlefish/docs/generate.py
  108. 6  python-lib/cuddlefish/{ → docs}/webdocs.py
  109. 119  python-lib/cuddlefish/server.py
  110. 2  python-lib/cuddlefish/tests/__init__.py
  111. 0  python-lib/cuddlefish/tests/static-files/{static-files/md/dev-guide → doc/dev-guide-source}/no_h1.md
  112. 0  python-lib/cuddlefish/tests/static-files/{static-files/md/dev-guide → doc/dev-guide-source}/welcome.md
  113. 0  python-lib/cuddlefish/tests/static-files/{ → doc}/static-files/base.html
  114. 0  python-lib/cuddlefish/tests/static-files/{ → doc}/static-files/index.html
  115. 1  python-lib/cuddlefish/tests/static-files/doc/status.md5
  116. 2  python-lib/cuddlefish/tests/test_apiparser.py
  117. 4  python-lib/cuddlefish/tests/test_apirenderer.py
  118. 87  python-lib/cuddlefish/tests/test_generate.py
  119. 39  python-lib/cuddlefish/tests/test_server.py
  120. 6  python-lib/cuddlefish/tests/test_webdocs.py
6  .gitignore
@@ -3,7 +3,11 @@ python-lib/cuddlefish/app-extension/components/jetpack.xpt
3 3
 testdocs.tgz
4 4
 jetpack-sdk-docs.tgz
5 5
 .test_tmp/
6  
-jetpack-sdk-docs/
  6
+doc/dev-guide/
  7
+doc/index.html
  8
+doc/packages/
  9
+doc/status.md5
  10
+
7 11
 
8 12
 # If you want to add other files here, like *.pyc and *.DS_Store,
9 13
 # please add them to a global git ignore file.
0  cuddlefish/docs/__init__.py b/python-lib/cuddlefish/docs/__init__.py
No changes.
0  static-files/md/dev-guide/addon-development/about.md → doc/dev-guide-source/addon-development/about.md
Source Rendered
File renamed without changes
0  ...ev-guide/addon-development/annotator/annotator.md → ...e-source/addon-development/annotator/annotator.md
Source Rendered
File renamed without changes
4  ...dev-guide/addon-development/annotator/creating.md → ...de-source/addon-development/annotator/creating.md
Source Rendered
@@ -170,7 +170,7 @@ overview-amo-review-process/](http://blog.mozilla.com/addons/2011/02/04/overview
170 170
 You should see the highlight appearing when you move the mouse over certain elements:
171 171
 
172 172
 <img class="image-center"
173  
-src="media/annotator/highlight.png" alt="Annotator Highlighting">
  173
+src="static-files/media/annotator/highlight.png" alt="Annotator Highlighting">
174 174
 
175 175
 Click on the highlight and you should see something like this in the console
176 176
 output:
@@ -323,7 +323,7 @@ element and click the element when it is highlighted. You should see a panel
323 323
 with a text area for a note:
324 324
 
325 325
 <img class="image-center"
326  
-src="media/annotator/editor-panel.png" alt="Annotator Editor Panel">
  326
+src="static-files/media/annotator/editor-panel.png" alt="Annotator Editor Panel">
327 327
 <br>
328 328
 
329 329
 Enter the note and press the return key: you should see console output like
4  ...v-guide/addon-development/annotator/displaying.md → ...-source/addon-development/annotator/displaying.md
Source Rendered
@@ -191,13 +191,13 @@ Execute `cfx run` one last time. Activate the annotator and enter an
191 191
 annotation. You should see a yellow border around the item you annotated:
192 192
 
193 193
 <img class="image-center"
194  
-src="media/annotator/matcher.png" alt="Annotator Matcher">
  194
+src="static-files/media/annotator/matcher.png" alt="Annotator Matcher">
195 195
 <br>
196 196
 
197 197
 When you move your mouse over the item, the annotation should appear:
198 198
 
199 199
 <img class="image-center"
200  
-src="media/annotator/annotation-panel.png" alt="Annotation Panel">
  200
+src="static-files/media/annotator/annotation-panel.png" alt="Annotation Panel">
201 201
 <br>
202 202
 
203 203
 Obviously this add-on isn't complete yet. It could do with more beautiful
2  ...dev-guide/addon-development/annotator/overview.md → ...de-source/addon-development/annotator/overview.md
Source Rendered
@@ -10,7 +10,7 @@ We could represent the basic interactions between the `main` module and the
10 10
 various content scripts like this:
11 11
 
12 12
 <img class="image-center"
13  
-src="media/annotator/annotator-design.png" alt="Annotator Design">
  13
+src="static-files/media/annotator/annotator-design.png" alt="Annotator Design">
14 14
 
15 15
 ## User Interface ##
16 16
 
2  .../dev-guide/addon-development/annotator/storing.md → ...ide-source/addon-development/annotator/storing.md
Source Rendered
@@ -233,7 +233,7 @@ Firefox. Activate the add-on, add an annotation, and then right-click the
233 233
 widget. You should see something like this:
234 234
 
235 235
 <img class="image-center"
236  
-src="media/annotator/annotation-list.png" alt="Annotation List">
  236
+src="static-files/media/annotator/annotation-list.png" alt="Annotation List">
237 237
 <br>
238 238
 
239 239
 <span class="aside">
6  ...d/dev-guide/addon-development/annotator/widget.md → ...uide-source/addon-development/annotator/widget.md
Source Rendered
@@ -46,8 +46,8 @@ Save this in your `data/widget` directory as `widget.js`.
46 46
 
47 47
 You can copy the widget's icons from here:
48 48
 
49  
-<img style="margin-left:40px; margin-right:20px;" src="media/annotator/pencil-on.png" alt="Active Annotator">
50  
-<img style="margin-left:20px; margin-right:20px;" src="media/annotator/pencil-off.png" alt="Inactive Annotator">
  49
+<img style="margin-left:40px; margin-right:20px;" src="static-files/media/annotator/pencil-on.png" alt="Active Annotator">
  50
+<img style="margin-left:20px; margin-right:20px;" src="static-files/media/annotator/pencil-off.png" alt="Inactive Annotator">
51 51
 
52 52
 (Or make your own if you're feeling creative.) Save them in your `data/widget` directory.
53 53
 
@@ -100,7 +100,7 @@ Now from the `annotator` directory type `cfx run`. You should see the widget
100 100
 in the add-on bar:
101 101
 
102 102
 <div align="center">
103  
-<img src="media/annotator/widget-icon.png" alt="Widget Icon">
  103
+<img src="static-files/media/annotator/widget-icon.png" alt="Widget Icon">
104 104
 </div>
105 105
 <br>
106 106
 
0  ...iles/md/dev-guide/addon-development/api-idioms.md → doc/dev-guide-source/addon-development/api-idioms.md
Source Rendered
File renamed without changes
0  ...files/md/dev-guide/addon-development/api-intro.md → doc/dev-guide-source/addon-development/api-intro.md
Source Rendered
File renamed without changes
12  ...les/md/dev-guide/addon-development/api-modules.md → ...dev-guide-source/addon-development/api-modules.md
Source Rendered
@@ -22,7 +22,7 @@ You can build or load the content locally or load it from a remote server.
22 22
 The screenshot below shows a panel whose content is built from the list of
23 23
 currently open tabs:
24 24
 
25  
-<img class="image-center" src="media/screenshots/modules/panel-tabs-osx.png"
  25
+<img class="image-center" src="static-files/media/screenshots/modules/panel-tabs-osx.png"
26 26
 alt="List open tabs panel">
27 27
 <br>
28 28
 
@@ -40,7 +40,7 @@ Widgets are generally used in one of two different contexts:
40 40
 the time in a selected time zone or the weather. The screenshot below shows a
41 41
 widget that displays the time in the selected city:
42 42
 
43  
-<img class="image-center" src="media/screenshots/modules/widget-content-osx.png"
  43
+<img class="image-center" src="static-files/media/screenshots/modules/widget-content-osx.png"
44 44
 alt="Mozilla widget content">
45 45
 <br>
46 46
 
@@ -49,7 +49,7 @@ interface. For example, a widget might display only an icon, but open a
49 49
 settings dialog when the user clicks it. The widget below displays only the
50 50
 Mozilla icon:
51 51
 
52  
-<img class="image-center" src="media/screenshots/modules/widget-icon-osx.png"
  52
+<img class="image-center" src="static-files/media/screenshots/modules/widget-icon-osx.png"
53 53
 alt="Mozilla widget icon">
54 54
 <br>
55 55
 
@@ -57,7 +57,7 @@ To simplify your code in the latter case, you can assign a panel object to
57 57
 your widget. Then when the user clicks the widget, the widget will display
58 58
 the panel anchored to the widget:
59 59
 
60  
-<img class="image-center" src="media/screenshots/modules/widget-panel-osx.png"
  60
+<img class="image-center" src="static-files/media/screenshots/modules/widget-panel-osx.png"
61 61
 alt="Panel anchored to widget">
62 62
 <br>
63 63
 
@@ -73,7 +73,7 @@ is selected) or define your own contexts using scripts.
73 73
 In the screenshot below an add-on has added a new submenu to the context menu
74 74
 associated with `img` elements:
75 75
 
76  
-<img class="image-center" src="media/screenshots/modules/context-menu-image-osx.png"
  76
+<img class="image-center" src="static-files/media/screenshots/modules/context-menu-image-osx.png"
77 77
 alt="Context-menu">
78 78
 <br>
79 79
 
@@ -86,7 +86,7 @@ OS X and Windows, libnotify on Linux), so the notification will look slightly
86 86
 different on different platforms. On Mac OS X a notification will look
87 87
 something like this:
88 88
 
89  
-<img class="image-center" src="media/screenshots/modules/notification-growl-osx.png"
  89
+<img class="image-center" src="static-files/media/screenshots/modules/notification-growl-osx.png"
90 90
 alt="Growl notification">
91 91
 <br>
92 92
 
20  ...-files/md/dev-guide/addon-development/cfx-tool.md → doc/dev-guide-source/addon-development/cfx-tool.md
Source Rendered
@@ -23,8 +23,24 @@ applicable to a subset of the commands.
23 23
 
24 24
 ### cfx docs ###
25 25
 
26  
-This command launches an HTTP server on the localhost to view web-based
27  
-documentation in a new Firefox window.
  26
+This command displays the documentation for the SDK. The documentation is
  27
+shipped with the SDK in [Markdown](http://daringfireball.net/projects/markdown/)
  28
+format. The first time this command is executed, and any time after the
  29
+Markdown files on disk have changed, `cfx docs` will generate a set of HTML
  30
+pages from them and launch a web browser to display them. If the Markdown files
  31
+haven't changed, `cfx docs` just launches a browser initialized to the set of
  32
+generated pages.
  33
+
  34
+To regenerate the documentation associated with a single file, you can
  35
+specify the file as an argument. For example:
  36
+
  37
+<pre>
  38
+  cfx docs doc/dev-guide-source/addon-development/cfx-tool.md 
  39
+</pre>
  40
+
  41
+This command will regenerate only the HTML page you're reading.
  42
+This is useful if you're iteratively editing a single file, and don't want to wait for cfx to
  43
+regenerate the complete documentation tree.
28 44
 
29 45
 ### cfx init ####
30 46
 Create a new directory, change into it, and run `cfx init`.
4  ...-files/md/dev-guide/addon-development/commonjs.md → doc/dev-guide-source/addon-development/commonjs.md
Source Rendered
@@ -19,7 +19,7 @@ module wants to make available to other modules
19 19
 object of another module. Your translator add-on uses `require` to import the
20 20
 SDK modules it uses.
21 21
 
22  
-![CommonJS modules](media/commonjs-modules.jpg)
  22
+![CommonJS modules](static-files/media/commonjs-modules.jpg)
23 23
 
24 24
 The SDK
25 25
 [freezes](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/freeze)
@@ -62,7 +62,7 @@ soon as Firefox has enabled the add-on.
62 62
 So in terms of CommonJS objects the translator consists of a package that
63 63
 contains a single module called `main`, and which imports three SDK modules:
64 64
 
65  
-![CommonJS translator](media/commonjs-translator.jpg)
  65
+![CommonJS translator](static-files/media/commonjs-translator.jpg)
66 66
 
67 67
 Because an add-on is a CommonJS package it's possible to include more than one
68 68
 module in an add-on, and to make your modules available to any code that want
0  ...c-files/md/dev-guide/addon-development/console.md → doc/dev-guide-source/addon-development/console.md
Source Rendered
File renamed without changes
0  ...guide/addon-development/content-scripts/access.md → ...ource/addon-development/content-scripts/access.md
Source Rendered
File renamed without changes
0  ...uide/addon-development/content-scripts/loading.md → ...urce/addon-development/content-scripts/loading.md
Source Rendered
File renamed without changes
0  ...don-development/content-scripts/reddit-example.md → ...don-development/content-scripts/reddit-example.md
Source Rendered
File renamed without changes
179  doc/dev-guide-source/addon-development/content-scripts/using-port.md
Source Rendered
... ...
@@ -0,0 +1,179 @@
  1
+
  2
+# Communicating using "port" #
  3
+
  4
+To enable add-on scripts and content scripts to communicate with each other,
  5
+each end of the conversation has access to a `port` object which defines two
  6
+functions:
  7
+
  8
+**`emit()`** is used to emit an event. It may be called with any number of
  9
+parameters, but is most likely to be called with a name for the event and
  10
+an optional payload. The payload can be any value that is
  11
+<a href = "dev-guide/addon-development/content-scripts/using-port.html#json_serializable">serializable to JSON</a>
  12
+
  13
+    port.emit("myEvent", myEventPayload);
  14
+
  15
+**`on()`** takes two parameters: the name of the event and a function to handle it:
  16
+
  17
+    port.on("myEvent", function handleMyEvent(myEventPayload) {
  18
+      // Handle the event
  19
+    });
  20
+
  21
+Here's  simple add-on that sends a message to a content script using `port`:
  22
+
  23
+    var tabs = require("tabs");
  24
+
  25
+    var alertContentScript = "self.port.on('alert', function(message) {" +
  26
+                             "  window.alert(message);" +
  27
+                             "})";
  28
+
  29
+    tabs.on("ready", function(tab) {
  30
+      worker = tab.attach({
  31
+        contentScript: alertContentScript
  32
+      });
  33
+      worker.port.emit("alert", "Message from the add-on");
  34
+    });
  35
+
  36
+    tabs.open("http://www.mozilla.org");
  37
+
  38
+We could depict the interface between add-on code and content script code like
  39
+this:
  40
+
  41
+<img class="image-center" src="static-files/media/content-scripting-events.png"
  42
+alt="Content script events">
  43
+
  44
+Events are asynchronous: that is, the sender does not wait for a reply from
  45
+the recipient but just emits the event and continues processing.
  46
+
  47
+## Accessing `port` in the Content Script ##
  48
+
  49
+<span class="aside">Note that the global `self` object is completely
  50
+different from the [`self` module](packages/addon-kit/docs/self.html), which
  51
+provides an API for an add-on to access its data files and ID.</span>
  52
+
  53
+In the content script the `port` object is available as a property of the
  54
+global `self` object. Thus, to emit an event from a content script:
  55
+
  56
+    self.port.emit("myContentScriptEvent", myContentScriptEventPayload);
  57
+
  58
+To receive an event from the add-on code:
  59
+
  60
+    self.port.on("myAddonEvent", function(myAddonEventPayload) {
  61
+      // Handle the event
  62
+    });
  63
+
  64
+Compare this to the technique used to receive _built-in_ events in the
  65
+content script. For example, to receive the `context` event in a content script
  66
+associated with a [context menu](packages/addon-kit/docs/context-menu.html)
  67
+object, you would call the `on` function attached to the global `self` object:
  68
+
  69
+    self.on("context", function() {
  70
+      // Handle the event
  71
+    });
  72
+
  73
+So the `port` property is essentially used here as a namespace for
  74
+user-defined events.
  75
+
  76
+## Accessing `port` in the Add-on Script ##
  77
+
  78
+In the add-on code, the channel of communication between the add-on and a
  79
+particular content script context is encapsulated by the `worker` object. Thus
  80
+the `port` object for communicating with a content script is a property of the
  81
+corresponding `worker` object.
  82
+
  83
+However, the worker is not exposed to add-on code in quite the same way
  84
+in all modules. The `panel` and `page-worker` objects integrate the
  85
+worker API directly. So to receive events from a content script associated
  86
+with a panel you use `panel.port.on()`:
  87
+
  88
+    var panel = require("panel").Panel({
  89
+      contentScript: "self.port.emit('showing', 'panel is showing');"
  90
+    });
  91
+
  92
+    panel.port.on("showing", function(text) {
  93
+      console.log(text);
  94
+    });
  95
+
  96
+    panel.show();
  97
+
  98
+Conversely, to emit user-defined events from your add-on you can just call
  99
+`panel.port.emit()`:
  100
+
  101
+    var panel = require("panel").Panel({
  102
+      contentScript: "self.port.on('alert', function(text) {" +
  103
+                     "  console.log(text);" +
  104
+                     "});"
  105
+    });
  106
+
  107
+    panel.show();
  108
+    panel.port.emit("alert", "panel is showing");
  109
+
  110
+The `panel` and `page-worker` objects only host a single page at a time,
  111
+so each distinct page object only needs a single channel of communication
  112
+to its content scripts. But some modules, such as `page-mod`, might need to
  113
+handle multiple pages, each with its own context in which the content scripts
  114
+are executing, so it needs a separate channel (worker) for each page.
  115
+
  116
+So `page-mod` does not integrate the worker API directly: instead, each time a
  117
+content script is attached to a page, the worker associated with the page is
  118
+supplied to the page-mod in its `onAttach` function. By supplying a target for
  119
+this function in the page-mod's constructor you can register to receive
  120
+events from the content script, and take a reference to the worker so as to
  121
+emit events to it.
  122
+
  123
+    var pageModScript = "window.addEventListener('click', function(event) {" +
  124
+                        "  self.port.emit('click', event.target.toString());" +
  125
+                        "  event.stopPropagation();" +
  126
+                        "  event.preventDefault();" +
  127
+                        "}, false);" +
  128
+                        "self.port.on('warning', function(message) {" +
  129
+                        "window.alert(message);" +
  130
+                        "});"
  131
+
  132
+    var pageMod = require('page-mod').PageMod({
  133
+      include: ['*'],
  134
+      contentScript: pageModScript,
  135
+      onAttach: function(worker) {
  136
+        worker.port.on('click', function(html) {
  137
+          worker.port.emit('warning', 'Do not click this again');
  138
+        });
  139
+      }
  140
+    });
  141
+
  142
+In the add-on above there are two user-defined events:
  143
+
  144
+* `click` is sent from the page-mod to the add-on, when the user clicks an
  145
+element in the page
  146
+* `warning` sends a silly string back to the page-mod
  147
+
  148
+## <a name="json_serializable">JSON-Serializable Values</a> ##
  149
+
  150
+The payload for an event can be any JSON-serializable value. When events are
  151
+sent their payloads are automatically serialized, and when events are received
  152
+their payloads are automatically deserialized, so you don't need to worry
  153
+about serialization.
  154
+
  155
+However, you _do_ have to ensure that the payload can be serialized to JSON.
  156
+This means that it needs to be a string, number, boolean, null, array of
  157
+JSON-serializable values, or an object whose property values are themselves
  158
+JSON-serializable. This means you can't send functions, and if the object
  159
+contains methods they won't be encoded.
  160
+
  161
+For example, to include an array of strings in the payload:
  162
+
  163
+    var pageModScript = "self.port.emit('loaded'," +
  164
+                        "  [" +
  165
+                        "  document.location.toString()," +
  166
+                        "  document.title" +
  167
+                        "  ]" +
  168
+                        ");"
  169
+
  170
+    var pageMod = require('page-mod').PageMod({
  171
+      include: ['*'],
  172
+      contentScript: pageModScript,
  173
+      onAttach: function(worker) {
  174
+        worker.port.on('loaded', function(pageInfo) {
  175
+          console.log(pageInfo[0]);
  176
+          console.log(pageInfo[1]);
  177
+        });
  178
+      }
  179
+    });
0  ...-development/content-scripts/using-postmessage.md → ...-development/content-scripts/using-postmessage.md
Source Rendered
File renamed without changes
0  ...ic-files/md/dev-guide/addon-development/events.md → doc/dev-guide-source/addon-development/events.md
Source Rendered
File renamed without changes
0  ...md/dev-guide/addon-development/getting-started.md → ...guide-source/addon-development/getting-started.md
Source Rendered
File renamed without changes
0  ...ic-files/md/dev-guide/addon-development/guides.md → doc/dev-guide-source/addon-development/guides.md
Source Rendered
File renamed without changes
0  ...addon-development/implementing-reusable-module.md → ...addon-development/implementing-reusable-module.md
Source Rendered
File renamed without changes
4  ...de/addon-development/implementing-simple-addon.md → ...ce/addon-development/implementing-simple-addon.md
Source Rendered
@@ -250,12 +250,12 @@ page containing some text that is not in English, for example:
250 250
 Select some text on that page and right-click to activate the context menu.
251 251
 You should see a new item labeled "Translate Selection":
252 252
 
253  
-![translator context-menu](media/screenshots/translator/context-menu-osx.png)
  253
+![translator context-menu](static-files/media/screenshots/translator/context-menu-osx.png)
254 254
 
255 255
 Select that item and the text you selected should be replaced with its English
256 256
 translation:
257 257
 
258  
-![translator context-menu](media/screenshots/translator/translated-osx.png)
  258
+![translator context-menu](static-files/media/screenshots/translator/translated-osx.png)
259 259
 
260 260
 You will also see output like this appear in your command shell:
261 261
 
2  ...es/md/dev-guide/addon-development/installation.md → ...ev-guide-source/addon-development/installation.md
Source Rendered
@@ -114,7 +114,7 @@ add-on for distribution, view documentation, and run unit tests.
114 114
 ## cfx docs ##
115 115
 
116 116
 If you're reading these documents online, try running `cfx docs`. This will
117  
-run a self-hosted documentation server and open it in your web browser.
  117
+build the documentation for the SDK and display it in a browser.
118 118
 
119 119
 ## Problems? ##
120 120
 
0  ...s/md/dev-guide/addon-development/module-search.md → ...v-guide-source/addon-development/module-search.md
Source Rendered
File renamed without changes
0  ...es/md/dev-guide/addon-development/package-spec.md → ...ev-guide-source/addon-development/package-spec.md
Source Rendered
File renamed without changes
0  ...iles/md/dev-guide/addon-development/program-id.md → doc/dev-guide-source/addon-development/program-id.md
Source Rendered
File renamed without changes
0  ...files/md/dev-guide/addon-development/reference.md → doc/dev-guide-source/addon-development/reference.md
Source Rendered
File renamed without changes
0  ...md/dev-guide/addon-development/troubleshooting.md → ...guide-source/addon-development/troubleshooting.md
Source Rendered
File renamed without changes
0  ...files/md/dev-guide/addon-development/tutorials.md → doc/dev-guide-source/addon-development/tutorials.md
Source Rendered
File renamed without changes
0  ...v-guide/addon-development/two-types-of-scripts.md → ...-source/addon-development/two-types-of-scripts.md
Source Rendered
File renamed without changes
2  ...les/md/dev-guide/addon-development/web-content.md → ...dev-guide-source/addon-development/web-content.md
Source Rendered
@@ -49,7 +49,7 @@ to the event-handling interfaces described in the
49 49
 The diagram below shows an overview of the main components and their
50 50
 relationships. The gray fill represents code written by the add-on developer.
51 51
 
52  
-<img class="image-center" src="media/content-scripting-overview.png"
  52
+<img class="image-center" src="static-files/media/content-scripting-overview.png"
53 53
 alt="Content script events">
54 54
 
55 55
 This might sound complicated but it doesn't need to be. The following add-on
0  static-files/md/dev-guide/appendices/credits.md → doc/dev-guide-source/appendices/credits.md
Source Rendered
File renamed without changes
0  static-files/md/dev-guide/appendices/glossary.md → doc/dev-guide-source/appendices/glossary.md
Source Rendered
File renamed without changes
0  ...ic-files/md/dev-guide/module-development/about.md → doc/dev-guide-source/module-development/about.md
Source Rendered
File renamed without changes
0  ...md/dev-guide/module-development/best-practices.md → ...guide-source/module-development/best-practices.md
Source Rendered
File renamed without changes
0  ...c-files/md/dev-guide/module-development/chrome.md → doc/dev-guide-source/module-development/chrome.md
Source Rendered
File renamed without changes
2  static-files/md/dev-guide/module-development/e10s.md → doc/dev-guide-source/module-development/e10s.md
Source Rendered
@@ -16,7 +16,7 @@ parent chrome process.
16 16
 
17 17
 ## The Big Picture ##
18 18
 
19  
-![Multi-Process Architecture](media/twitter-widget.png)
  19
+![Multi-Process Architecture](static-files/media/twitter-widget.png)
20 20
 
21 21
 The above diagram is a simplified depiction of what happens when a hypothetical
22 22
 add-on using the `widget` module is loaded.
0  ...-files/md/dev-guide/module-development/globals.md → doc/dev-guide-source/module-development/globals.md
Source Rendered
File renamed without changes
0  ...c-files/md/dev-guide/module-development/guides.md → doc/dev-guide-source/module-development/guides.md
Source Rendered
File renamed without changes
0  ...iles/md/dev-guide/module-development/reference.md → doc/dev-guide-source/module-development/reference.md
Source Rendered
File renamed without changes
0  ...iles/md/dev-guide/module-development/tutorials.md → doc/dev-guide-source/module-development/tutorials.md
Source Rendered
File renamed without changes
0  static-files/md/dev-guide/module-development/xpi.md → doc/dev-guide-source/module-development/xpi.md
Source Rendered
File renamed without changes
0  static-files/md/dev-guide/welcome.md → doc/dev-guide-source/welcome.md
Source Rendered
File renamed without changes
30  static-files/base.html → doc/static-files/base.html
@@ -4,17 +4,17 @@
4 4
 <head>
5 5
   <base  >
6 6
   <meta http-equiv="Content-type" content="text/html; charset=utf-8">
7  
-  <script type="text/javascript" src="syntaxhighlighter/scripts/shCore.js"></script>
8  
-  <script type="text/javascript" src="syntaxhighlighter/scripts/shBrushCss.js"></script>
9  
-  <script type="text/javascript" src="syntaxhighlighter/scripts/shBrushXml.js"></script>
10  
-  <script type="text/javascript" src="syntaxhighlighter/scripts/shBrushJScript.js"></script>
11  
-  <link rel="stylesheet" type="text/css" media="all" href="css/base.css">
12  
-  <link rel="stylesheet" type="text/css" media="all" href="css/header.css">
13  
-  <link rel="stylesheet" type="text/css" media="all" href="css/footer.css">
14  
-  <link rel="stylesheet" type="text/css" media="all" href="css/sdk-docs.css">
15  
-  <link rel="stylesheet" type="text/css" media="all" href="css/api-reference.css">
16  
-  <link rel="stylesheet" type="text/css" href="syntaxhighlighter/styles/shCore.css">
17  
-  <link rel="stylesheet" type="text/css" href="syntaxhighlighter/styles/shThemeDefault.css">
  7
+  <script type="text/javascript" src="static-files/syntaxhighlighter/scripts/shCore.js"></script>
  8
+  <script type="text/javascript" src="static-files/syntaxhighlighter/scripts/shBrushCss.js"></script>
  9
+  <script type="text/javascript" src="static-files/syntaxhighlighter/scripts/shBrushXml.js"></script>
  10
+  <script type="text/javascript" src="static-files/syntaxhighlighter/scripts/shBrushJScript.js"></script>
  11
+  <link rel="stylesheet" type="text/css" media="all" href="static-files/css/base.css">
  12
+  <link rel="stylesheet" type="text/css" media="all" href="static-files/css/header.css">
  13
+  <link rel="stylesheet" type="text/css" media="all" href="static-files/css/footer.css">
  14
+  <link rel="stylesheet" type="text/css" media="all" href="static-files/css/sdk-docs.css">
  15
+  <link rel="stylesheet" type="text/css" media="all" href="static-files/css/api-reference.css">
  16
+  <link rel="stylesheet" type="text/css" href="static-files/syntaxhighlighter/styles/shCore.css">
  17
+  <link rel="stylesheet" type="text/css" href="static-files/syntaxhighlighter/styles/shThemeDefault.css">
18 18
   <!--[if IE]>
19 19
     <style type="text/css">
20 20
       .package-summary .module,
@@ -25,7 +25,7 @@
25 25
     </style>
26 26
   <![endif]-->
27 27
 
28  
-  <link rel="shortcut icon" type="image/x-icon" href="media/favicon.png">
  28
+  <link rel="shortcut icon" type="image/x-icon" href="static-files/media/favicon.png">
29 29
   <title></title>
30 30
 </head>
31 31
 <body>
@@ -178,7 +178,7 @@ <h3 class="sidebar-subsection-header"><a href="dev-guide/module-development/refe
178 178
 
179 179
 <div role="contentinfo" id="footer">
180 180
   <div class="section">
181  
-    <img alt="" src="media/footer-logo-med.png" class="footerlogo">
  181
+    <img alt="" src="static-files/media/footer-logo-med.png" class="footerlogo">
182 182
     <div id="social-footer">
183 183
       <ul>
184 184
         <li>get to know <b>add-ons</b></li>
@@ -204,8 +204,8 @@ <h3 class="sidebar-subsection-header"><a href="dev-guide/module-development/refe
204 204
   </div>
205 205
 </div>
206 206
 
207  
-<script type="text/javascript" src="js/jquery.js"></script>
208  
-<script type="text/javascript" src="js/main.js"></script>
  207
+<script type="text/javascript" src="static-files/js/jquery.js"></script>
  208
+<script type="text/javascript" src="static-files/js/main.js"></script>
209 209
 
210 210
 </body>
211 211
 
0  static-files/css/api-reference.css → doc/static-files/css/api-reference.css
File renamed without changes
0  static-files/css/base.css → doc/static-files/css/base.css
File renamed without changes
0  static-files/css/footer.css → doc/static-files/css/footer.css
File renamed without changes
0  static-files/css/header.css → doc/static-files/css/header.css
File renamed without changes
0  static-files/css/sdk-docs.css → doc/static-files/css/sdk-docs.css
File renamed without changes
0  static-files/js/jquery.js → doc/static-files/js/jquery.js
File renamed without changes
24  static-files/js/main.js → doc/static-files/js/main.js
... ...
@@ -1,5 +1,4 @@
1 1
 function run(jQuery) {
2  
-  var IDLE_PING_DELAY = 5000;
3 2
 
4 3
   function highlightCode() {
5 4
     $("code").parent("pre").addClass("brush: js");
@@ -95,29 +94,6 @@ function run(jQuery) {
95 94
     }
96 95
   }
97 96
 
98  
-  var serverNeedsKeepalive = true;
99  
-
100  
-  function sendIdlePing() {
101  
-    jQuery.ajax({url:"/api/idle",
102  
-               cache: false,
103  
-               error: function(req) {
104  
-                 if (req.status == 501 || req.status == 404) {
105  
-                   // The server either isn't implementing idle, or
106  
-                   // we're being served from static files; just bail
107  
-                   // and stop pinging this API endpoint.
108  
-                   serverNeedsKeepalive = false;
109  
-                 }
110  
-               }});
111  
-    scheduleNextIdlePing();
112  
-  }
113  
-
114  
-  function scheduleNextIdlePing() {
115  
-    if (serverNeedsKeepalive)
116  
-      window.setTimeout(sendIdlePing, IDLE_PING_DELAY);
117  
-  }
118  
-
119  
-  if (window.location.protocol != "file:")
120  
-    scheduleNextIdlePing();
121 97
   highlightCurrentPage();
122 98
   highlightCode();
123 99
   $(".syntaxhighlighter").width("auto");
175  doc/static-files/md/dev-guide/addon-development/content-scripts/access.md
Source Rendered
... ...
@@ -0,0 +1,175 @@
  1
+# Content Script Access #
  2
+
  3
+This page talks about the access content scripts have to:
  4
+
  5
+* DOM objects in the pages they are attached to
  6
+* other content scripts
  7
+* other scripts loaded by the page they are attached to
  8
+
  9
+## Access to the DOM ##
  10
+
  11
+Content scripts need to be able to access DOM objects in arbitrary web
  12
+pages, but this could cause two potential security problems:
  13
+
  14
+1. JavaScript values from the content script could be accessed by the page,
  15
+enabling a malicious page to steal data or call privileged methods.
  16
+2. a malicious page could redefine standard functions and properties of DOM
  17
+objects so they don't do what the add-on expects.
  18
+
  19
+To deal with this, content scripts access DOM objects via a proxy.
  20
+Any changes they make are made to the proxy, and so are not visible to
  21
+page content.
  22
+
  23
+The proxy is based on `XRayWrapper`, (also known as
  24
+[`XPCNativeWrapper`](https://developer.mozilla.oreg/en/XPCNativeWrapper)).
  25
+These wrappers give the user access to the native values of DOM functions
  26
+and properties, even if they have been redefined by a script.
  27
+
  28
+For example: the page below redefines `window.confirm()` to return
  29
+`true` without showing a confirmation dialog:
  30
+
  31
+<script type="syntaxhighlighter" class="brush: html"><![CDATA[
  32
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  33
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  34
+<html lang='en' xml:lang='en' xmlns="http://www.w3.org/1999/xhtml">
  35
+  <head>
  36
+    <script>
  37
+    window.confirm = function(message) {
  38
+      return true;
  39
+    }
  40
+    &lt;/script>
  41
+  </head>
  42
+</html>
  43
+
  44
+</script>
  45
+
  46
+But thanks to the content proxy, a content script which calls
  47
+`window.confirm()` will get the native implementation:
  48
+
  49
+    var widgets = require("widget");
  50
+    var tabs = require("tabs");
  51
+    var data = require("self").data;
  52
+
  53
+    var widget = widgets.Widget({
  54
+      id: "transfer",
  55
+      label: "Transfer",
  56
+      content: "Transfer",
  57
+      width: 100,
  58
+      onClick: function() {
  59
+        tabs.activeTab.attach({
  60
+          // native implementation of window.confirm will be used
  61
+          contentScript: "console.log(window.confirm('Transfer all my money?'));"
  62
+        });
  63
+      }
  64
+    });
  65
+
  66
+    tabs.open(data.url("xray.html"));
  67
+
  68
+You can try out this example [using the builder](https://builder.addons.mozilla.org/addon/1013777/revision/4/).
  69
+
  70
+The proxy is transparent to content scripts: as far as the content script
  71
+is concerned, it is accessing the DOM directly. But because it's not, some
  72
+things that you might expect to work, won't. For example, if the page includes
  73
+a library like [jQuery](http://www.jquery.com), or any other page script
  74
+adds other objects to any DOM nodes, they won't be visible to the content
  75
+script. So to use jQuery you'll typically have to add it as a content script,
  76
+as in [this example](dev-guide/addon-development/content-scripts/reddit-example.html).
  77
+
  78
+### unsafeWindow ###
  79
+
  80
+If you really need direct access to the underlying DOM, you can use the
  81
+global `unsafeWindow` object.
  82
+
  83
+To see the difference, try editing the
  84
+[example in the builder](https://builder.addons.mozilla.org/addon/1013777/revision/4/)
  85
+so the content script uses `unsafeWindow.confirm()` instead of
  86
+`window.confirm()` (to edit the example, you'll need to create an account
  87
+with the Add-on Builder and clone the original add-on). Alternatively, try out
  88
+[the example here](https://builder.addons.mozilla.org/addon/1015979/revision/3/).
  89
+
  90
+Avoid using `unsafeWindow` if possible: it is the same concept as
  91
+Greasemonkey's unsafeWindow, and the
  92
+[warnings for that](http://wiki.greasespot.net/UnsafeWindow) apply equally
  93
+here. Also, `unsafeWindow` isn't a supported API, so it could be removed or
  94
+changed in a future version of the SDK.
  95
+
  96
+
  97
+## Access to Other Content Scripts ##
  98
+
  99
+Content scripts loaded into the same document can interact
  100
+with each other directly as well as with the web content itself. However,
  101
+content scripts which have been loaded into different documents
  102
+cannot interact with each other.
  103
+
  104
+For example:
  105
+
  106
+* if an add-on creates a single `panel` object and loads several content
  107
+scripts into the panel, then they can interact with each other
  108
+
  109
+* if an add-on creates two `panel` objects and loads a script into each
  110
+one, they can't interact with each other.
  111
+
  112
+* if an add-on creates a single `page-mod` object and loads several content
  113
+scripts into the page mod, then only content scripts associated with the
  114
+same page can interact with each other: if two different matching pages are
  115
+loaded, content scripts attached to page A cannot interact with those attached
  116
+to page B.
  117
+
  118
+The web content has no access to objects created by the content script, unless
  119
+the content script explicitly makes them available.
  120
+
  121
+## Access to Page Scripts ##
  122
+
  123
+You can communicate between the content script and page scripts using
  124
+[`postMessage()`](https://developer.mozilla.org/en/DOM/window.postMessage),
  125
+but there's a twist: in early versions of the SDK, the global `postMessage()`
  126
+function in content scripts was used for communicating between the content
  127
+script and the main add-on code. Although this has been
  128
+[deprecated in favor of `self.postMessage`](https://wiki.mozilla.org/Labs/Jetpack/Release_Notes/1.0b5#Major_Changes),
  129
+the old globals are still supported, so you can't currently use
  130
+`window.postMessage()`. You must use `document.defaultView.postMessage()`
  131
+instead.
  132
+
  133
+The following page script uses
  134
+[`window.addEventListener`](https://developer.mozilla.org/en/DOM/element.addEventListener)
  135
+to listen for messages:
  136
+
  137
+<script type="syntaxhighlighter" class="brush: html"><![CDATA[
  138
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  139
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  140
+<html lang='en' xml:lang='en' xmlns="http://www.w3.org/1999/xhtml">
  141
+
  142
+  <head>
  143
+    <script>
  144
+      window.addEventListener("message", function(event) {
  145
+        window.alert(event.data);
  146
+      }, false);
  147
+    &lt;/script>
  148
+
  149
+  </head>
  150
+
  151
+</html>
  152
+
  153
+</script>
  154
+
  155
+Content scripts can send it messages using `document.defaultView.postMessage()`:
  156
+
  157
+    var widgets = require("widget");
  158
+    var tabs = require("tabs");
  159
+    var data = require("self").data;
  160
+
  161
+    var widget = widgets.Widget({
  162
+      id: "postMessage",
  163
+      label: "demonstrate document.defaultView.postMessage",
  164
+      contentURL: "http://www.mozilla.org/favicon.ico",
  165
+      onClick: function() {
  166
+        tabs.activeTab.attach({
  167
+          contentScript: "document.defaultView.postMessage('hi there!', '*');"
  168
+        });
  169
+      }
  170
+    });
  171
+
  172
+    tabs.open(data.url("listener.html"));
  173
+
  174
+You can see this add-on at
  175
+[https://builder.addons.mozilla.org/addon/1013849/revision/8/](https://builder.addons.mozilla.org/addon/1013849/revision/8/).
60  doc/static-files/md/dev-guide/addon-development/content-scripts/loading.md
Source Rendered
... ...
@@ -0,0 +1,60 @@
  1
+
  2
+# Loading Content Scripts #
  3
+
  4
+The constructors for content-script-using objects such as panel and page-mod
  5
+define a group of options for loading content scripts:
  6
+
  7
+<pre>
  8
+  contentScript      string, array
  9
+  contentScriptFile  string, array
  10
+  contentScriptWhen  string
  11
+</pre>
  12
+
  13
+We have already seen the `contentScript` option, which enables you to pass
  14
+in the text of the script itself as a string literal. This version of the API
  15
+avoids the need to maintain a separate file for the content script.
  16
+
  17
+The `contentScriptFile` option enables you to pass in the local file URL from
  18
+which the content script will be loaded. To supply the file
  19
+"my-content-script.js", located in the /data subdirectory under your package's
  20
+root directory, use a line like:
  21
+
  22
+    // "data" is supplied by the "self" module
  23
+    var data = require("self").data;
  24
+    ...
  25
+    contentScriptFile: data.url("my-content-script.js")
  26
+
  27
+Both `contentScript` and `contentScriptFile` accept an array of strings, so you
  28
+can load multiple scripts, which can also interact directly with each other in
  29
+the content process:
  30
+
  31
+    // "data" is supplied by the "self" module
  32
+    var data = require("self").data;
  33
+    ...
  34
+    contentScriptFile:
  35
+        [data.url("jquery-1.4.2.min.js"), data.url("my-content-script.js")]
  36
+
  37
+Scripts specified using contentScriptFile are loaded before those specified
  38
+using contentScript. This enables you to load a JavaScript library like jQuery
  39
+by URL, then pass in a simple script inline that can use jQuery.
  40
+
  41
+The `contentScriptWhen` option specifies when the content script(s) should be
  42
+loaded. It takes one of three possible values:
  43
+
  44
+* "start" loads the scripts immediately after the document element for the
  45
+page is inserted into the DOM. At this point the DOM content hasn't been
  46
+loaded yet, so the script won't be able to interact with it.
  47
+
  48
+* "ready" loads the scripts after the DOM for the page has been loaded: that
  49
+is, at the point the
  50
+[DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events)
  51
+event fires. At this point, content scripts are able to interact with the DOM
  52
+content, but externally-referenced stylesheets and images may not have finished
  53
+loading.
  54
+
  55
+* "end" loads the scripts after all content (DOM, JS, CSS, images) for the page
  56
+has been loaded, at the time the
  57
+[window.onload event](https://developer.mozilla.org/en/DOM/window.onload)
  58
+fires.
  59
+
  60
+The default value is "end".
67  doc/static-files/md/dev-guide/addon-development/content-scripts/reddit-example.md
Source Rendered
... ...
@@ -0,0 +1,67 @@
  1
+# Reddit Example #
  2
+
  3
+This example add-on creates a panel containing the mobile version of Reddit.
  4
+When the user clicks on the title of a story in the panel, the add-on opens
  5
+the linked story in a new tab in the main browser window.
  6
+
  7
+To accomplish this the add-on needs to run a content script in the context of
  8
+the Reddit page which intercepts mouse clicks on each title link and fetches the
  9
+link's target URL. The content script then needs to send the URL to the add-on
  10
+script.
  11
+
  12
+This is the complete add-on script:
  13
+
  14
+    var data = require("self").data;
  15
+
  16
+    var reddit_panel = require("panel").Panel({
  17
+      width: 240,
  18
+      height: 320,
  19
+      contentURL: "http://www.reddit.com/.mobile?keep_extension=True",
  20
+      contentScriptFile: [data.url("jquery-1.4.4.min.js"),
  21
+                          data.url("panel.js")]
  22
+    });
  23
+
  24
+    reddit_panel.port.on("click", function(url) {
  25
+      require("tabs").open(url);
  26
+    });
  27
+
  28
+    require("widget").Widget({
  29
+      id: "open-reddit-btn",
  30
+      label: "Reddit",
  31
+      contentURL: "http://www.reddit.com/static/favicon.ico",
  32
+      panel: reddit_panel
  33
+    });
  34
+
  35
+This code supplies two content scripts to the panel's constructor in the
  36
+`contentScriptFile` option: the jQuery library and the script that intercepts
  37
+link clicks.
  38
+
  39
+Finally, it registers a listener to the user-defined `click` event which in
  40
+turn passes the URL into the `open` function of the
  41
+[tabs](packages/addon-kit/docs/tabs.html) module.
  42
+
  43
+This is the `panel.js` content script that intercepts link clicks:
  44
+
  45
+    $(window).click(function (event) {
  46
+      var t = event.target;
  47
+
  48
+      // Don't intercept the click if it isn't on a link.
  49
+      if (t.nodeName != "A")
  50
+        return;
  51
+
  52
+      // Don't intercept the click if it was on one of the links in the header
  53
+      // or next/previous footer, since those links should load in the panel itself.
  54
+      if ($(t).parents('#header').length || $(t).parents('.nextprev').length)
  55
+        return;
  56
+
  57
+      // Intercept the click, passing it to the addon, which will load it in a tab.
  58
+      event.stopPropagation();
  59
+      event.preventDefault();
  60
+      self.port.emit('click', t.toString());
  61
+    });
  62
+
  63
+This script uses jQuery to interact with the DOM of the page and the
  64
+`self.port.emit` function to pass URLs back to the add-on script.
  65
+
  66
+See the `examples/reddit-panel` directory for the complete example (including
  67
+the content script containing jQuery).
0  ...e/addon-development/content-scripts/using-port.md → ...e/addon-development/content-scripts/using-port.md
Source Rendered
File renamed without changes
136  doc/static-files/md/dev-guide/addon-development/content-scripts/using-postmessage.md
Source Rendered
... ...
@@ -0,0 +1,136 @@
  1
+# Communicating using "postMessage()" #
  2
+
  3
+As an alternative to user-defined events content modules support the built-in
  4
+`message` event. In most cases user-defined events are preferable to message
  5
+events. However, the `context-menu` module does not support user-defined
  6
+events, so to send messages from a content script to the add-on via a context
  7
+menu object, you must use message events.
  8
+
  9
+## Handling Message Events in the Content Script ##
  10
+
  11
+To send a message from a content script, you use the `postMessage` function of
  12
+the global `self` object:
  13
+
  14
+    self.postMessage(contentScriptMessage);
  15
+
  16
+This takes a single parameter, the message payload, which may be any
  17
+<a href = "dev-guide/addon-development/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>.
  18
+
  19
+To receive a message from the add-on script, use `self`'s `on` function:
  20
+
  21
+    self.on("message", function(addonMessage) {
  22
+      // Handle the message
  23
+    });
  24
+
  25
+Like all event-registration functions, this takes two parameters: the name
  26
+of the event, and the handler function. The handler function is passed the
  27
+message payload.
  28
+
  29
+## Handling Message Events in the Add-on Script ##
  30
+