HTML Templates

When Koru exports a scene, it generates 3D model and javascript code for displaying it, and finally it frames them with some HTML code that shows the scene in browser. That HTML code may vary depending on your needs. For instance, it can display a full-screen scene or a small 3D model with some extra information. For easy switching between various layouts Koru uses export templates. Template is a dummy HTML code that is filled with 3D model when you export a scene.

You can find templates by clicking File → Templates… in Koru menu. An Explorer or Finder window will pop up showing template folders. Each template consists of these files:

_template.html - the template itself;
_readme.txt - template title and description;
_preview.png - template preview to display in Export Wizard.

Templates may also have other files in their folders. Anything that is not started with underscore symbol will be copied to the output folder when exporting scene.

You can create your own templates by adding new folders next to the existing ones and placing template files there. Although you can edit existing templates, it is recommended to make a copy and edit it instead. This way you avoid possible overwriting them at the next update of Koru.

Template Files

As said above, templates should have at least three files: _preview.png, _readme.txt and _template.html. Each of them has its own rules and limitations that will be explained below.

_preview.png

This is a template preview image that is displayed at the first step of Export Wizard. It is expected to be square (1:1 aspect ratio) and it is expected to be at least 512x512 pixels. It also has to be in PNG format, as other ones are not supported.

_readme.txt

This file is expected to have UTF-8 encoding and contain at least two lines of text. The first line is used as a template name, while the rest lines are used for template description. Have a look at the built-in templates for details.

_template.html

This file contains HTML page for displaying 3D model. It must have all the <html> and <body> tags, unless you want to include it somewhere else. It is always a good idea to look through the built-in templates for details. Start with mini–fullscreen and mini–widget folders, as they have the simplest templates.

Here is the simplest template - mini–fullscreen:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>{{KORU_TITLE}}</title>
	<style>
		html, body {
			width: 100%;
			height: 100%;
			margin: 0;
			overflow: hidden;
		}
		{{KORU_NOSCRIPT_CSS}}
	</style>
</head>

<body>
	<div class="koru-viewport" {{KORU_DATA_SCENE_ATTRIBUTE}}>
		{{KORU_NOSCRIPT_HTML}}
	</div>
</body>

{{KORU_SCRIPT}}
{{KORU_EXTRA_SCRIPT}}

</html>

As you may see, it is quite a simple HTML page with embedded stylesheet and some tags placed in double curly braces. Here are the list of supported tags:

KORU_TITLE — this is the title you can specify on the second step of the export wizard;
KORU_NOSCRIPT_CSS — this is a placeholder for the built-in styles for <noscript> block that you can enable at the second step of the export wizard;
KORU_NOSCRIPT_HTML — the same as above, but this is replaced with HTML code of <noscript> tag;
KORU_DATA_SCENE_ATTRIBUTE — this tag is replaced with data attribute pointing to .koruDat file with exported scene, if exported for server. For single-file HTML export, this tag is simply deleted, as the scene is embedded into the same HTML file;
KORU_SCRIPT — this one is replaced with either javascript code of the scene for single-file export, or with <script> tag pointing to the external js-file with Koru loader for server-based export;
KORU_EXTRA_SCRIPT — here goes the custom script you can write in Script Editor using Scene → Script Editor menu item.

The main part of the template is a <div> tag with koru–viewport class. Koru loader finds that tag in HTML DOM and adds all the necessary things inside the tag. Make sure you keep both the tag and class attribute when modifying templates.

CSS Selectors For Koru Elements

If you want to fine-tune the look and feel of the exported document, you can simply extend the built-in stylesheet. This lets you re-position or re-color snapshot buttons or loading progress bar. For more complex modifications you need to use Javascript API provided by Koru.

Here are the list of CSS selectors you can use:

koru-viewport — the main <div> tag that is used as a Koru placeholder. Here you define the size of the 3D model preview;
koru-canvas — the <canvas> tag used for WebGL scene rendering;
koru-ul — list used to display snapshot buttons;
koru-button — controls single snapshot button appearance;
koru-progressBar — defines the loading progress bar background;
koru-progressIndicator — controls the progress bar indicator;
koru-error — used to display errors in case of any issues with loading scene. Try exporting for server and then removing scene data file to see the error;
koru-fullscreen — controls the appearance of the “full screen” button at the top right corner.

For more details on these selectors, it is recommended to use your browser developers tool to see how they are composed and work together. You can also find default styles there. Once you specify any of the styles above in the stylesheet, Koru will not load its own styles for them, so it is recommended to completely define all the styles you need, when overriding.