Adding HTML and CSS to Verge3D applications

Introduction

The template Verge3D application offers a single-page widescreen layout with a full-screen button and a preloader. Interactive elements such as buttons can be implemented as 3D objects pinned to the camera - the same applies to text boxes.
A more flexible and effective approach, however, would be to leverage the established web standards for creating user interfaces. With HTML and CSS you can build any layout for your app, making it responsive and SEO-friendly. The UI and especially text created with HTML and CSS look usually sharper than their 3D counterparts thanks to the specialized rasterisation engines of the modern web browsers. This approach will also allow you to easily mix 2D media such as images, videos and web links with 3D content, and style your app to match the design of a website on which it will be deployed.
There are plenty of web design tools ranging from the plain text editor to full-blown what-you-see-is-what-you-get website builders. The latter can produce complete sets of HTML/CSS/JavaScript ready-to-use web pages thus allowing you to never touch any code.

Where to add HTML and CSS

Suppose you created your application using the App Manager (with default configuration options), and named it my_awesome_app. If you look inside the verge3d/applications/my_awesome_app folder you'll find there my_awesome_app.html and my_awesome_app.css files that seem to be natural to start edit - but they only seem so!
In practice, you might never want to edit these files as they are auto-generated by the App Manager and may get overridden as a result of a clean update. A more robust way to add your own HTML/CSS to a Verge3D app would be creating a new .html file, in which the Verge3D app .html is embedded, matryoshka-style.

Quick Overview: Teapot Heater

Check out the following example (Verge3D Teapot Heater demo): all the interface is built using third-party web design software and saved as index.html (this name is not obligatory). Besides interface HTML elements, the index.html file also contains an iframe element via which the Verge3D project, teapot_heater.html, is embedded.
In Verge3D App Manager such a composite project has two launching icons that you can use to independently run either the pure Verge3D project or the assembled app:
Finally, the 2D and 3D parts are logically interconnected with HTML puzzles to handle user events.

Tutorial

In the following tutorial we'll show how to create a simple app with HTML-based UI. This app will have only 2 buttons for hiding and revealing the default cube.
Let's start with creating a new project named my_awesome_app with the App Manager. Then we'll create the user interface .html file with 3 different tools: a text editor, Google Web Designer and Webflow. Once the UI is ready, we'll make the HTML buttons operable with Puzzles.

Tool #1: Text Editor

The plain text editor is still considered by many web designers to be the most powerful and flexible tool for building web pages. Even if you are not going to dive in coding, this guide may help you understand the internal structure of a web page generated by more artist-friendly tools.
You can use any text editor for editing HTML/CSS code, but it is more convenient to work if your editor supports syntax highlighting and line numbering, like Notepad++ or Atom.
A basic HTML document we can start from can look as follows. You can just copy these contents to a new text document and save as index.html in the verge3d/applications/my_awesome_app folder. Again, the name of the file is not obligatory and we only use it everywhere for the sake of consistency.
<!DOCTYPE html> <html> <head> <title>Index of My Awesome App</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0"> <meta name="description" content="Put some description here - remember about SEO!"> </head> <body> </body> </html>
The new .html file immediately starts being displayed as an extra blue icon in the App Manager, producing a white blank page upon launching.
Now we can add an iframe element to the document's body to embed our Verge3D app's main launching file, my_awesome_app.html:
<body> <iframe id="my_iframe" src="my_awesome_app.html"></iframe> </body>
If you run the assembled app from the App Manager now, it will display a small embedding of the default cube application in the top-left corner. We can make it wide-screen and border-less by in-lining some CSS:
<style> #my_iframe { position: absolute; top: 0px; left: 0px; width: 100%; height: 100%; border: 0; } </style>
Now let's create 2 buttons by adding 2 div elements to the body, supplied with unique id attributes for referencing in CSS and in Puzzles:
<div id="hide_button">Hide</div> <div id="show_button">Show</div>
You won't notice them in the app though, until you make them absolutely positioned and styled with some CSS:
#hide_button, #show_button { position: absolute; width: 100px; height: 30px; background-color: DodgerBlue; color: white; text-align: center; line-height: 30px; cursor: pointer; } #hide_button { left: 10px; } #show_button { left: 120px; }
That's it - now you have two HTML buttons in your app! Here is the full listing of the index.html:
<!DOCTYPE html> <html> <head> <title>Index of My Awesome App</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0"> <meta name="description" content="Put some description here - remember about SEO!"> <style> #my_iframe { position: absolute; top: 0px; left: 0px; width: 100%; height: 100%; border: 0; } #hide_button, #show_button { position: absolute; width: 100px; height: 30px; background-color: DodgerBlue; color: white; text-align: center; line-height: 30px; cursor: pointer; } #hide_button { left: 10px; } #show_button { left: 120px; } </style> </head> <body> <iframe id="my_iframe" src="my_awesome_app.html"></iframe> <div id="hide_button">Hide</div> <div id="show_button">Show</div> </body> </html>

Tool #2: Google Web Designer

Google Web Designer is a free cross-platform tool which can be used for creating HTML elements and assigning styles to them in a visual manner.
After launching this program, select Create new file...
...then select HTML on the left panel and fill out all the fields: Name (e.g. "my_awesome_app_gwd"), Location (use any path, preferably, out of your app folder to avoid confusion with the published version) and Title, and click OK.
Let's start by adding the iframe element for embedding our Verge3D app's main launching file, my_awesome_app.html. In Google Web Designer this can be done by dragging the IFrame component out from the list under the Components tab.
After the IFrame component is placed on the page, switch to the Properties tab and make your iframe element occupy the entire page by specifying zeroes for the left and top positions and 100% for the width and height. Also, in the Source field put the path to Verge3D app main file - "my_awesome_app.html" (assuming that we'll be publishing our UI file in the root of the app folder).
At this stage we can generate our UI .html file and try it with the Verge3D app. Click the Publish button in the top-right corner and select Locally.
In the publishing dialog select the path to the app folder, my_awesome_app, as Location. Leave the Name field empty in order to save the files right in the root of the app folder.
The new .html file immediately starts being displayed as an extra blue icon in the App Manager. You can run it to check if it actually loads the Verge3D app.
Now let's add those two buttons. On the most left panel click on the Element tool, then select the Div element and start drawing a rectangle on the page.
In the Properties tab use the color picker to fill the button with color, specify its position and dimensions and most importantly, set the ID for this element which we will be using for referencing it in Puzzles.
To add a caption to the button ("Hide" or "Show"), double-click on it so that it becomes outlined in red. Click on the Text tool, then on the button and type text in the text area. Use font settings to setup the size, color and other properties. You can use the Selection tool (the first button with an arrow) to move your text field on the button.
As a result, in the Outliner panel you should see the iframe element, 2 div elements with unique IDs assigned to them and two text elements nested inside those divs.
As a finishing touch, in the CSS properties window we can make the mouse cursor turn to its "clicking" form when it is over those buttons:
After publishing the index.html file and running the assembled app from the App Manager you should see something like this:
For more information on using Google Web Designer tools and components refer to their docs.

Tool #3: Webflow

Webflow is a cloud-based tool which can also be used for creating HTML/CSS user interfaces for Verge3D apps. The necessary Embed component and the Export Code feature are only available to paid accounts starting from the "Lite" level.
In the dashboard click the New Project button and select Blank Site from the templates:
Fill out the name of your project and click Create project:
Now let's add an iframe element for embedding our Verge3D app's main launching file, my_awesome_app.html. In Webflow this can be achieved as follows. On the left panel click Add Elements and click or drag out the Embed component:
Copy and paste the following line to the editor window:
<iframe width="100%" height="100%" frameborder="0" src="my_awesome_app.html"></iframe>
Here we assume that index.html generated by Webflow will be placed in the root of the app folder. Click Save & Close.
After the Embed component is placed on the page, switch to the Style tab and make your iframe element occupy the entire page by specifying Fixed for its position and 100% for the width and height.
At this stage we can generate our UI .html file and try it with the Verge3D app. Click the Export Code button on the top bar...
...and then click Prepare ZIP and finally Download ZIP:
Save the archive to any location on your hard drive and unpack to the root of the app folder, my_awesome_app. The new .html file immediately starts being displayed as an extra blue icon in the App Manager. You can run it to check if it actually loads the Verge3D app.
Now let's add those two buttons. On the most left panel click on Add Elements, then click or drag out the Div Block component.
In the Style tab use the color picker to fill the button with color, specify its position and dimensions.
In order to set the ID for this element which we will be using for referencing it in Puzzles, go to the Element Settings tab and type "hide_button" or "show_button" in the ID field.
To add a caption to the button ("Hide" or "Show"), drag out the Text Block component on the button and type text in the text area.
Use Typography settings under the Style tab to setup the size, color and other properties.
As a result, in the Navigator tab you should see the iframe element, 2 div elements and two text elements nested inside those divs.
As a finishing touch, in the Style tab we can make the mouse cursor turn to its "clicking" form when it is over those buttons:
After exporting the project and running the assembled app from the App Manager you should see something like this:
For more information on using Webflow tools and components refer to their tutorials.

HTML Puzzles

Now what's left is to make our buttons operable so that by clicking on them, the user can hide and reveal the cube. This can easily be achieved by leveraging the HTML event puzzle used in connection with the element IDs:
Since the clickable HTML elements are located in the parent .html file in which the Verge3D app is embedded, we should check the in parent doc checkbox to make them work.