{{Short description|HTML5 API}} {{HTML}} '''Web Messaging''', or '''cross-document messaging''', is an API introduced in the WHATWG HTML5 draft specification, allowing documents to communicate with one another across different origins, or source domains<ref name="WHATWG"/> while rendered in a web browser. Prior to HTML5, web browsers disallowed cross-site scripting, to protect against security attacks. This practice barred communication between non-hostile pages as well, making document interaction of any kind difficult.<ref name="WHATWG"/><ref name="WebKit"/> Cross-document messaging allows scripts to interact across these boundaries, while providing a rudimentary level of security.
==Requirements and attributes== Using the Messaging API's <code>postMessage</code> method, plain text messages can be sent from one domain to another, e.g. from a parent document to an IFRAME.<ref name="INTRODUCING"/> This requires that the author first obtain the <code>Window</code> object of the receiving document. As a result, messages can be posted to the following:<ref name="WebKit"/> * other frames or iframes within the sender document's window * windows the sender document explicitly opens through JavaScript calls * the parent window of the sender document * the window which opened the sender document The message <code>event</code> being received has the following attributes: * <code>data</code> – The data, or actual content, of the incoming message. * <code>origin</code> – The origin of the sender document. This typically includes the scheme, hostname and port. It does not include the path or fragment identifier.<ref name="WHATWG"/> * <code>source</code> – the <code>WindowProxy</code> of where the document came from (the source window).
<code>postMessage</code> is not a blocking call; messages are processed asynchronously.<ref>{{Cite web|url=http://www.w3.org/TR/2010/WD-webmessaging-20101118/#web-messaging|title = HTML5 Web Messaging}}</ref>
==Example== Consider we want document A loaded from <code>example.net</code> to communicate with document B loaded from <code>example.com</code> into an <code>iframe</code> or popup window.<ref name="WHATWG"/> The JavaScript for document A will look as follows: <syntaxhighlight lang="javascript"> var o = document.getElementsByTagName('iframe')[0]; o.contentWindow.postMessage('Hello B', 'http://example.com/'); </syntaxhighlight> The origin of our <code>contentWindow</code> object is passed to <code>postMessage</code>. It must match the <code>origin</code> of the document we wish to communicate with (in this case, document B). Otherwise, a security error will be thrown and the script will stop.<ref name="INTRODUCING"/> The JavaScript for document B will look as follows: <syntaxhighlight lang="javascript"> function receiver(event) { if (event.origin == 'http://example.net') { if (event.data == 'Hello B') { event.source.postMessage('Hello A, how are you?', event.origin); } else { alert(event.data); } } } window.addEventListener('message', receiver, false); </syntaxhighlight> An event listener is set up to receive messages from document A. Using the <code>origin</code> property, it then checks that the domain of the sender is the expected domain. Document B then looks at the message, either displaying it to the user, or responding in turn with a message of its own for document A.<ref name="WHATWG"/>
==Security== Poor origin checking can pose a risk for applications which employ cross-document messaging.<ref name="Security"/> To safeguard against malicious code from foreign domains, authors should check the <code>origin</code> attribute to ensure messages are accepted from domains they expect to receive messages from. The format of incoming data should also be checked that it matches the expected format.<ref name="WHATWG"/>
==Support== Support for cross-document messaging exists in current versions of Internet Explorer, Mozilla Firefox, Safari, Google Chrome, Opera, Opera Mini, Opera Mobile, and Android web browser.<ref name="canIuse"/> Support for the API exists in the Trident, Gecko, WebKit and Presto layout engines.<ref name="SUPPORT"/>
==See also== * Cross-site scripting * Cross-site request forgery * Same-origin policy * Cross-origin resource sharing * JSONP
==References== {{Reflist|30em|refs= <ref name="WHATWG">[http://www.whatwg.org/specs/web-apps/current-work/multipage/comms.html#web-messaging ''Cross-Document Messaging – HTML Draft Standard'']</ref> <ref name="INTRODUCING">Remy, Sharp, ''Messages, Workers, and Sockets'', ''Introducing HTML5'', New Riders, 2011, p. 197-199</ref> <ref name="WebKit">{{Cite web |url=https://developer.apple.com/library/mac/#documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/Cross-documentmessaging.html |title=''WebKit DOM Programming Topics - Cross Document Messaging'' |access-date=2013-12-29 |archive-date=2012-06-09 |archive-url=https://web.archive.org/web/20120609170929/http://developer.apple.com/library/mac/#documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/Cross-documentmessaging.html |url-status=dead }}</ref> <ref name="Security">[http://www.veracode.com/blog/2010/05/html5-security-in-a-nutshell/ ''HTML5 Security in a Nutshell'']</ref> <ref name="canIuse">[http://caniuse.com/x-doc-messaging ''When can I use Cross-Document Messaging?'']</ref> <ref name="SUPPORT">{{Cite web |url=http://molly.com/html5/html5-0709.html |title=''A Selection of Supported Features in HTML5'' |access-date=2011-04-18 |archive-date=2011-11-12 |archive-url=https://web.archive.org/web/20111112155122/http://molly.com/html5/html5-0709.html |url-status=dead }}</ref>}}
==External links== * [http://www.w3.org/TR/2015/REC-webmessaging-20150519/ HTML5 Web Messaging recommendation] * [http://dev.w3.org/html5/postmsg/ HTML5 Web Messaging specification] {{Webarchive|url=https://web.archive.org/web/20101224010913/http://dev.w3.org/html5/postmsg/ |date=2010-12-24 }} * {{citation |url=http://www.whatwg.org/specs/web-apps/current-work/multipage/comms.html#web-messaging |title=''Cross-Document Messaging – HTML Draft Standard'' |publisher=WHATWG}} * {{citation |url=https://developer.apple.com/library/mac/#documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/Cross-documentmessaging.html |title=''WebKit DOM Programming Topics - Cross Document Messaging'' |publisher=Apple Developer Library |access-date=2013-12-29 |archive-date=2012-06-09 |archive-url=https://web.archive.org/web/20120609170929/http://developer.apple.com/library/mac/#documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/Cross-documentmessaging.html |url-status=dead }} * {{citation |url=http://www.veracode.com/blog/2010/05/html5-security-in-a-nutshell/ |title=''HTML5 Security in a Nutshell'' |date=2010-05-17 |first=Chris |last=Eng |publisher=Veracode}} * {{citation |url=http://caniuse.com/x-doc-messaging |title=''When can I use Cross-Document Messaging?'' |publisher=CanIUse}} * {{citation |url=http://molly.com/html5/html5-0709.html |title=''A Selection of Supported Features in HTML5'' |access-date=2011-04-18 |archive-date=2011-11-12 |archive-url=https://web.archive.org/web/20111112155122/http://molly.com/html5/html5-0709.html |url-status=dead }}
{{Web interfaces}}
Category:HTML Category:Application programming interfaces