Getting started

Christian Schlinkmann edited this page Oct 28, 2015 · 25 revisions

Requirements

xml3d.js runs on any browser with WebGL support.

Enable XML3D

To make XML3D work, all you need to do is include the xml3d.js library in your HTML or XHTML document.

Just make sure, that you include xml3d.js as the very first js library in your document, like so:

<!doctype html>
<html>
<head>
    <!-- Your usual header stuff, but NO <script> -->
    <script src="http://www.xml3d.org/xml3d/script/xml3d.js"></script>
    <!-- Other <script> tags -->
</head>

We also have a Gist for xml3d.js boilerplate code.

Important things to remember:

  • Always add the xml3d.js library first for all JavaScript libraries! (Yes, even before jquery.)
  • All XML3D elements, including the element currently only support '''inline style properties''' with the style attribute

Using XML3D locally

XML3D, like all WebGL based frameworks, will not work properly when served from a filesystem! If you want to develop XML3D websites locally on your machine you should do it through a local HTTP server like Wamp, Apache or a simple Node.js web server. Python also includes a simple built-in HTTP server.

Be sure your server always supplies a Content-Type header for all files that XML3D may need to load. More information can be found in the troubleshooting section I'm getting errors about missing content-type headers.

Write XML3D

XML3D is an extension to HTML. It defines a small set of elements that allow you to add 3D content inside your web document.

To work with XML3D, you need to understand the set of XML3D elements. Good news: there are only few of them. Currently less than 20.

Here are some resources for learning XML3D:

Using Camera Controller

If a standard navigation mode is sufficient for your web application then you can include the camera controller that comes with xml3d.js:

    <script src="http://www.xml3d.org/xml3d/script/xml3d.js"></script>
    <script src="http://www.xml3d.org/xml3d/script/tools/camera.js"></script>

Convert XHTML to HTML

When switching from XHTML to HTML you should make sure that all XML3D elements always have an opening and closing tag, even those without children. Self closing tags (eg. <transform translation="1 1 1" />) are only legal in XHTML documents

'''Exceptions:''' HTML elements such as <img> don't need to be closed.

Example

XML3D in XHTML:

<xml3d xmlns="http://www.xml3d.org/2009/xml3d" >
  <view />
  <data id="meshData">
    <data src="external1.json" />
    <data src="external2.json" />
  </data>
  <mesh src="#meshData" />
</xml3d>

XML3D in HTML:

<xml3d>
  <view></view>
  <data id="meshData">
    <data src="external1.json" ></data>
    <data src="external2.json" ></data>
  </data>
  <mesh src="#meshData" ></mesh>
</xml3d>

Regular Expression for converting from XHTML to HTML

You can use the following regular expression to help you convert to HTML.

RegExp: <([A-Za-z]+) ?([^>]*)/>

Replacement: <$1 $2></$1>