Added optional DOM Container parent and config values

src/boot/Config.js

@@ -50,6 +50,13 @@ var ValueToColor = require('../display/color/ValueToColor');
  * @property {integer} [timeout=0] - [description]
  */
 
+/**
+ * @typedef {object} DOMContainerConfig
+ *
+ * @property {boolean} [createContainer=false] - Create a div element in which DOM Elements will be contained. You must also provide a parent.
+ * @property {boolean} [behindCanvas=false] - Place the DOM Container behind the Phaser Canvas. The default is to place it over the Canvas.
+ */
+
 /**
  * @typedef {object} GameConfig
  *
@@ -83,6 +90,7 @@ var ValueToColor = require('../display/color/ValueToColor');
  * @property {boolean} [banner.hidePhaser=false] - [description]
  * @property {string} [banner.text='#ffffff'] - [description]
  * @property {string[]} [banner.background] - [description]
+ * @property {DOMContainerConfig} [dom] - The DOM Container configuration object.
  * @property {FPSConfig} [fps] - [description]
  * @property {boolean} [render.antialias=true] - [description]
  * @property {boolean} [render.pixelArt=false] - [description]
@@ -212,6 +220,18 @@ var Config = new Class({
          */
         this.autoFocus = GetValue(config, 'autoFocus', true);
 
+        //  DOM Element Container
+
+        /**
+         * @const {?boolean} Phaser.Boot.Config#domCreateContainer - [description]
+         */
+        this.domCreateContainer = GetValue(config, 'dom.createContainer', false);
+
+        /**
+         * @const {?boolean} Phaser.Boot.Config#domBehindCanvas - [description]
+         */
+        this.domBehindCanvas = GetValue(config, 'dom.behindCanvas', false);
+
         //  Input
 
         /**

src/boot/CreateDOMContainer.js

@@ -0,0 +1,37 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+var AddToDOM = require('../dom/AddToDOM');
+
+var CreateDOMContainer = function (game)
+{
+    var config = game.config;
+
+    if (!config.parent || !config.domCreateContainer)
+    {
+        return;
+    }
+
+    var width = game.canvas.width;
+    var height = game.canvas.height;
+
+    var z = (config.domBehindCanvas) ? 1 : 3;
+
+    //  DOM Element Container
+    var div = document.createElement('div');
+
+    div.style = 'width: ' + width + 'px; height: ' + height + 'px; padding: 0; margin: 0; position: absolute; overflow: hidden; pointer-events: none; z-index: ' + z;
+
+    // game.canvas.style.position = 'absolute';
+    // game.canvas.style.zIndex = '2';
+    // game.canvas.parentElement.style.position = 'relative';
+
+    game.domContainer = div;
+
+    AddToDOM(div, config.parent);
+};
+
+module.exports = CreateDOMContainer;

src/boot/Game.js

@@ -10,6 +10,7 @@ var CacheManager = require('../cache/CacheManager');
 var CanvasPool = require('../display/canvas/CanvasPool');
 var Class = require('../utils/Class');
 var Config = require('./Config');
+var CreateDOMContainer = require('./CreateDOMContainer');
 var CreateRenderer = require('./CreateRenderer');
 var DataManager = require('../data/DataManager');
 var DebugHeader = require('./DebugHeader');
@@ -68,6 +69,20 @@ var Game = new Class({
          */
         this.renderer = null;
 
+        /**
+         * A reference to an HTML Div Element used as a DOM Element Container.
+         * 
+         * Only set if `createDOMContainer` is `true` in the game config (by default it is `false`) and
+         * if you provide a parent element to insert the Phaser Game inside.
+         *
+         * See the DOM Element Game Object for more details.
+         *
+         * @name Phaser.Game#domContainer
+         * @type {HTMLDivElement}
+         * @since 3.12.0
+         */
+        this.domContainer = null;
+
         /**
          * A reference to the HTML Canvas Element that Phaser uses to render the game.
          * This is created automatically by Phaser unless you provide a `canvas` property
@@ -305,6 +320,8 @@ var Game = new Class({
 
         CreateRenderer(this);
 
+        CreateDOMContainer(this);
+
         DebugHeader(this);
 
         AddToDOM(this.canvas, this.config.parent);
@@ -611,6 +628,12 @@ var Game = new Class({
         this.config.width = width;
         this.config.height = height;
 
+        if (this.domContainer)
+        {
+            this.domContainer.style.width = width + 'px';
+            this.domContainer.style.height = height + 'px';
+        }
+
         this.renderer.resize(width, height);
 
         this.input.resize();
@@ -666,6 +689,11 @@ var Game = new Class({
             }
         }
 
+        if (this.domContainer)
+        {
+            this.domContainer.parentNode.removeChild(this.domContainer);
+        }
+
         this.loop.destroy();
 
         this.pendingDestroy = false;