Added the possibility to set an id to the iframe

README.md

@@ -95,6 +95,8 @@ connection.promise.then(parent => {
 
 `options.appendTo` (optional) The element to which the created iframe should be appended. If not provided, the iframe will be appended to `document.body`.
 
+`options.iframe` (optional) The iframe element that Penpal will use instead of creating the iframe element itself. This iframe element must not be already attached to the DOM as it will be appended by Penpal. This option is useful if you need to set attributes to the iframe element before it is appended to the DOM, for example the sandbox attribute. Note that the src attribute will be set by Penpal with the `options.url` value, even if already set.
+
 `options.methods` (optional) An object containing methods which should be exposed for the child iframe to call. The keys of the object are the method names and the values are the functions. If a function requires asynchronous processing to determine its return value, make the function immediately return a promise and resolve the promise once the value has been determined.
 
 `options.timeout` (optional) The amount of time, in milliseconds, Penpal should wait for the child to respond before rejecting the connection promise. There is no timeout by default.
@@ -165,6 +167,39 @@ import {
 
 This provides an opportunity for build optimization (using tools like Webpack or Rollup) in cases where code only needs access to the error constants and not the rest of Penpal.
 
+## Security Note
+
+Penpal does not set the sandbox attribute on the iframe element it creates. If you need to sandbox the iframe, you must, in the parent, create the iframe element, set its sandbox attribute and call the connectToChild API with the created iframe. Here is an example setting the sandbox attribute in the parent window :
+
+
+```javascript
+import Penpal from 'penpal';
+
+const iframe = document.createElement('iframe');
+iframe.sandbox = 'allow-scripts';
+
+const connection = Penpal.connectToChild({
+  // URL of page to load into iframe.
+  url: 'http://example.com/iframe.html',
+  // Container to which the iframe should be appended.
+  appendTo: document.getElementById('iframeContainer'),
+  // The iframe element to use
+  iframe: iframe,
+  // Methods parent is exposing to child
+  methods: {
+    add(num1, num2) {
+      return num1 + num2;
+    }
+  }
+});
+
+connection.promise.then(child => {
+  child.multiply(2, 6).then(total => console.log(total));
+  child.divide(12, 4).then(total => console.log(total));
+});
+```
+
+
 ## Supported Browsers
 
 Penpal is designed to run successfully on the most recent versions of Internet Explorer, Edge, Chrome, Firefox, and Safari.

src/index.js

@@ -10,6 +10,7 @@ const DATA_CLONE_ERROR = 'DataCloneError';
 export const ERR_CONNECTION_DESTROYED = 'ConnectionDestroyed';
 export const ERR_CONNECTION_TIMEOUT = 'ConnectionTimeout';
 export const ERR_NOT_IN_IFRAME = 'NotInIframe';
+export const ERR_IFRAME_ALREADY_ATTACHED_TO_DOM = 'IframeAlreadyAttachedToDom';
 
 const DEFAULT_PORTS = {
   'http:': '80',
@@ -22,6 +23,7 @@ const Penpal = {
   ERR_CONNECTION_DESTROYED,
   ERR_CONNECTION_TIMEOUT,
   ERR_NOT_IN_IFRAME,
+  ERR_IFRAME_ALREADY_ATTACHED_TO_DOM,
 
   /**
    * Promise implementation.
@@ -336,26 +338,33 @@ const connectCallReceiver = (info, methods, destructionPromise) => {
  * for the child to respond before rejecting the connection promise.
  * @return {Child}
  */
-Penpal.connectToChild = ({ url, appendTo, methods = {}, timeout }) => {
+Penpal.connectToChild = ({ url, appendTo, iframe, methods = {}, timeout }) => {
+  if (iframe && iframe.parentNode) {
+    const error = new Error(
+      'connectToChild() must not be called with an iframe already attached to DOM'
+    );
+    error.code = ERR_IFRAME_ALREADY_ATTACHED_TO_DOM;
+    throw error;
+  }
+
   let destroy;
+
   const connectionDestructionPromise = new DestructionPromise(
     resolveConnectionDestructionPromise => {
       destroy = resolveConnectionDestructionPromise;
     }
   );
 
   const parent = window;
-  const iframe = document.createElement('iframe');
-
-  (appendTo || document.body).appendChild(iframe);
+  iframe = iframe || document.createElement('iframe');
+  iframe.src = url;
 
   connectionDestructionPromise.then(() => {
     if (iframe.parentNode) {
       iframe.parentNode.removeChild(iframe);
     }
   });
 
-  const child = iframe.contentWindow || iframe.contentDocument.parentWindow;
   const childOrigin = getOriginFromUrl(url);
   const promise = new Penpal.Promise((resolveConnectionPromise, reject) => {
     let connectionTimeoutId;
@@ -380,6 +389,7 @@ Penpal.connectToChild = ({ url, appendTo, methods = {}, timeout }) => {
     let destroyCallReceiver;
 
     const handleMessage = event => {
+      const child = iframe.contentWindow || iframe.contentDocument.parentWindow;
       if (
         event.source === child &&
         event.origin === childOrigin &&
@@ -456,7 +466,7 @@ Penpal.connectToChild = ({ url, appendTo, methods = {}, timeout }) => {
     });
 
     log('Parent: Loading iframe');
-    iframe.src = url;
+    (appendTo || document.body).appendChild(iframe);
   });
 
   return {