@@ -34,24 +34,29 @@ EventManager.triggerEvent("drawImage-Handler", "someEventName", "param1", "param
3434Registers a named EventHandler. Event handlers are created using the call:
3535` EventDispatcher.makeEventDispatcher(Command.prototype); `
3636
37+ Type: [ function] [ 1 ]
38+
39+ ### Parameters
40+
41+ * ` handlerName ` ** [ string] [ 2 ] ** a unique name of the handler.
42+ * ` eventDispatcher ` ** [ object] [ 3 ] ** An EventDispatcher that will be used to trigger events.
43+
44+ ### Examples
45+
3746To register a close dialogue event handler in an extension:
47+
48+ ``` javascript
3849// in close-dialogue.js module winthin the extension, do the following:
3950const EventDispatcher = brackets .getModule (" utils/EventDispatcher"
4051EventDispatcher .makeEventDispatcher (exports );
4152const EventManager = brackets .getModule (" utils/EventManager"
4253
43- // Note: for event handler names, please change the ` extensionName ` to your extension name
54+ // Note: for event handler names, please change the < extensionName> to your extension name
4455// to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers
4556// and not available for use in extensions.
46- EventManager.registerEventHandler("` extensionName ` -closeDialogueHandler", exports);
57+ EventManager .registerEventHandler (" < extensionName> -closeDialogueHandler" exports );
4758// Once the event handler is registered, see triggerEvent API on how to raise events
48-
49- Type: [ function] [ 1 ]
50-
51- ### Parameters
52-
53- * ` handlerName ` ** [ string] [ 2 ] ** a unique name of the handler.
54- * ` eventDispatcher ` ** [ object] [ 3 ] ** An EventDispatcher that will be used to trigger events.
59+ ```
5560
5661Returns ** [ boolean] [ 4 ] **
5762
@@ -71,11 +76,6 @@ Returns **[boolean][4]**
7176
7277Triggers an event on the named event handler.
7378
74- To trigger an event to the ` closeDialogue ` event handler registered above
75- // anywhere in code, do the following:
76- const EventManager = brackets.getModule("utils/EventManager");
77- EventManager.triggerEvent("closeDialogueHandler", "someEvent", "param1", "param2", ...);
78-
7979Type: [ function] [ 1 ]
8080
8181### Parameters
@@ -84,6 +84,16 @@ Type: [function][1]
8484* ` eventName ` the event name as recognised by the handler. this is usually a string.
8585* ` eventParams ` ** ...any** Can be a comma seperated list of args or a single argument.
8686
87+ ### Examples
88+
89+ To trigger an event to the ` closeDialogue ` event handler registered above
90+
91+ ``` javascript
92+ // anywhere in code, do the following:
93+ const EventManager = brackets .getModule (" utils/EventManager"
94+ EventManager .triggerEvent (" closeDialogueHandler" " someEvent" " param1" " param2" ... );
95+ ```
96+
8797## onmessage
8898
8999This function acts as a secure event handler for all 'message' events targeted at the window object.
@@ -93,33 +103,43 @@ Instead of directly overriding window.onmessage, extensions or other elements th
93103listen to these events should register their named eventHandler with ` EventManager ` .
94104
95105By default, only origins part of ` window.Phoenix.TRUSTED_ORIGINS ` are whitelisted. If your extension is
96- bringing in a cross-origin ifrmame say \[ ` http://mydomain.com ` ] , you should add it to the whitelist by setting
97- ` window.Phoenix.TRUSTED_ORIGINS ["http://mydomain.com"] = true; `
106+ bringing in a cross-origin ifrmame say ` http://mydomain.com ` , you should add it to the whitelist by setting
107+ ` window.Phoenix.TRUSTED_ORIGINS["http://mydomain.com"]= true; `
98108
99109### Parameters
100110
101111* ` event ` ** [ MessageEvent] [ 6 ] ** The 'message' event targeted at the window object. The event's
102- 'data' property should have a 'handlerName' and ` eventName ` property that will be triggered in phcode.// We will try to communicate within an embedded iframe and an extension// In your extension in phoenix, register a handlerName to process a new kind of event.
103- const EventDispatcher = brackets.getModule("utils/EventDispatcher"),
104- EventDispatcher.makeEventDispatcher(exports);
105- const EventManager = brackets.getModule("utils/EventManager");
106- // Note: for event handler names, please change the ` extensionName ` to your extension name
107- // to prevent collisions. EventHandlers starting with ` ph- ` and ` br- ` are reserved as system handlers
108- // and not available for use in extensions.
109- window.Phoenix.TRUSTED_ORIGINS \[ "[ http://mydomain.com ] [ 7 ] "] = true;
110- EventManager.registerEventHandler("` extensionName ` -iframeMessageHandler", exports);
111- exports.on("iframeHelloEvent", function(\_ ev, event){
112- console.log(event.data.message);
113- });// Now from your iframe, send a message to the above event handler using:
114- window.parent.postMessage({
115- handlerName: "` extensionName ` -iframeMessageHandler",
112+ 'data' property should have a 'handlerName' and ` eventName ` property that will be triggered in phcode.
113+
114+ ### Examples
115+
116+ ``` javascript
117+ // We will try to communicate within an embedded iframe and an extension
118+
119+ // In your extension in phoenix, register a handlerName to process a new kind of event.
120+ const EventDispatcher = brackets .getModule (" utils/EventDispatcher"
121+ EventDispatcher .makeEventDispatcher (exports );
122+ const EventManager = brackets .getModule (" utils/EventManager"
123+ // Note: for event handler names, please change the <extensionName> to your extension name
124+ // to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers
125+ // and not available for use in extensions.
126+ window .Phoenix .TRUSTED_ORIGINS [" http://mydomain.com" = true ;
127+ EventManager .registerEventHandler (" <extensionName>-iframeMessageHandler" exports );
128+ exports .on (" iframeHelloEvent" function (_ev , event ){
129+ console .log (event .data .message );
130+ });
131+
132+ // Now from your iframe, send a message to the above event handler using:
133+ window .parent .postMessage ({
134+ handlerName: " <extensionName>-iframeMessageHandler"
116135 eventName: " iframeHelloEvent"
117136 message: " hello world"
118- }, '\* ');
119- // ` you should replace * with the trusted domains list in production for security. ` See how this can be
120- // done securely with this example: [ https://github.com/phcode-dev/phcode.live/blob/6d64386fbb9d671cdb64622bc48ffe5f71959bff/docs/virtual-server-loader.js#L43 ] [ 8 ]
121- // Abstract is that, pass in the parentOrigin as a query string parameter in iframe, and validate it against
122- // a trusted domains list in your iframe.
137+ }, ' *'
138+ // `you should replace * with the trusted domains list in production for security.` See how this can be
139+ // done securely with this example: https://github.com/phcode-dev/phcode.live/blob/6d64386fbb9d671cdb64622bc48ffe5f71959bff/docs/virtual-server-loader.js#L43
140+ // Abstract is that, pass in the parentOrigin as a query string parameter in iframe, and validate it against
141+ // a trusted domains list in your iframe.
142+ ```
123143
124144[ 1 ] : https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
125145
@@ -132,7 +152,3 @@ bringing in a cross-origin ifrmame say \[`http://mydomain.com`], you should add
132152[ 5 ] : https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
133153
134154[ 6 ] : https://developer.mozilla.org/docs/Web/API/MessageEvent
135-
136- [ 7 ] : http://mydomain.com
137-
138- [ 8 ] : https://github.com/phcode-dev/phcode.live/blob/6d64386fbb9d671cdb64622bc48ffe5f71959bff/docs/virtual-server-loader.js#L43
0 commit comments