

## Forcing the type of loader on a model

Babylon's mesh importer is using the file extension of the model you provided in order to find out what loader to use. Sometimes, it is not possible to provide a file extension - especially if your server doesn't allow it. If that is the case, you can force a specific loader on a model.

To do that, use the `model.loader` configuration variable:

```html
<babylon extends="minimal" model.url="https://example.com/Rabbit" model.loader=".gltf"></babylon>
```

This will load [https://example.com/Rabbit](https://example.com/Rabbit) using the glTF loader.

## Retrieving the viewer instance

The viewer has a viewer manager that registers each viewer currently on this page. The viewer manager is event based, and will trigger a callback every time a new viewer was added. To register the callback, you can use the following:

```javascript
// using basic callback
BabylonViewer.viewerManager.onViewerAdded = function(viewer) {
    console.log(viewer);
}

// user observers

BabylonViewer.viewerManager.onViewerAddedObservable.add(function(viewer) {
    console.log(viewer);
})
```

Another way of getting the viewer is using the promise-based API:

```javascript
// you will need to set an id attribute to the viewer element and use it here:
BabylonViewer.viewerManager.getViewerPromiseById('viewer-id').then(function(viewer) {
    console.log(viewer.getBaseId());
});
```

The Promise-based API will either wait until the viewer was created, or return the viewer itself, if already initialized. It is therefore the safest way to get the viewer instance.

If you know the viewer was already initialized, there are two simple ways of getting it:

```javascript
// using the id
let viewer = BabylonViewer.viewerManager.getViewerById('viewer-id');
// using the viewer HTML element
let element = document.querySelector('babylon');
let viewer2 = BabylonViewer.viewerManager.getViewerByHTMLElement(element);
```

## Initializing a different HTML tag other than `<babylon>`

Babylon Viewer automatically initializes `babylon` HTML tags and renders a viewer on top of them. If you want to use a different HTML Tag, it is more than possible. To do that, you will need to disable the default init, and then init your own tags. Add the following script at the bottom of your page, after including the viewer js file:

```javascript
// a simple way of disabling auto init
BabylonViewer.disableInit = true;
// Initializing the viewer on specific HTML tags.
BabylonViewer.InitTags('the-other-tag-name');
```

## Finding the Babylon Engine, Scene, and Camera

The viewer instance exposes the used Engine, Scene, and Camera objects.
To get them, simply get the viewer (any way you see fit, as previously discussed), and get the public member you need:

```javascript
let viewer = getMeMyViewer();
viewer.sceneManager.scene instanceOf BABYLON.Scene; // true
viewer.engine instanceOf BABYLON.Engine; // true
viewer.sceneManager.camera instanceOf BABYLON.ArcRotateCamera; // true
```

## Event-based development

Other than the scene, engine and camera, the viewer exposes observables that are executed when a certain event happens. At the moment, there are 3 observables currently available:

```javascript
public onSceneInitObservable: PromiseObservable<Scene>; // Executed when a scene object was initialized
public onEngineInitObservable: PromiseObservable<Engine>; // Executed after the engine was created
public onModelLoadedObservable: PromiseObservable<AbstractMesh[]>; // Executed after a model was loaded.
```

You will notice these are Promise-based observables. The difference is, that you can run return a promise instead of a variable, and the viewer will wait for its execution.

Let's take a look at a (very not-helpful) example - we will delay the entire execution after a scene was created using setTimeout() and a Promise object:

```javascript
// taken from here - https://blog.raananweber.com/2015/12/01/writing-a-promise-delayer/
function DelayPromise(delay) {
  //return a function that accepts a single variable
  return function(data) {
    //this function returns a promise.
    return new Promise(function(resolve, reject) {
      setTimeout(function() {
        //a promise that is resolved after "delay" milliseconds with the data provided
        console.log('done!');
        resolve(data);
      }, delay);
    });
  }
}

// force a 500 ms delay after the scene was created.
viewer.onSceneInitObservable.add(DelayPromise(500));
```

This will print 'done' and then continue loading the model.

If we would simply use setTimeout and return, setTimeout would have async-executed, and the 'done' would have been logged 500 ms after the model started loading.

The registered function doesn't have to be a promise. If registering a simple function, it will still work and execute correctly:

```javascript
viewer.onSceneInitObservable.add(function(scene) {
    scene.clearColor = BABYLON.Color4.Blue();
    // returning the scene object. a common practice, not a must
    return scene;
});
```

## Enabling the Inspector

To enable the Inspector, add scene.debug="true" to your html tag:

```html
<babylon extends="minimal" scene.debug="true" model="https://playground.babylonjs.com/scenes/Rabbit.babylon"></babylon>
```

## Loading a model async

In certain cases you would want to load your model using javascript after the viewer was initialized. It is the case if, for example, a user clicks on a button to load a model, or drag & drops a model to be viewed. In this case, your HTML should just contain the configuration for the scene (engine, scene, camera and lights), without defining anything related to the model itself:

```html
<babylon id="babylon-viewer" camera.behaviors.auto-rotate="0"></babylon>
```

To do so, the viewer exposes the "loadModel" function. Loading model requires you to wait for the engine to initialize. So in order to get it to work correctly, you will need to wait for the onEngineInit observable to notify you about it:

```javascript
BabylonViewer.viewerManager.getViewerPromiseById('babylon-viewer').then(function (viewer) {
    // this will resolve only after the viewer with this specific ID is initialized

    viewer.onEngineInitObservable.add(function (scene) {
        viewer.loadModel({
            title: "Helmet",
            subtitle: "BabylonJS",
            thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
            url: "https://www.babylonjs.com/Assets/DamagedHelmet/glTF/DamagedHelmet.gltf"
        });

        // load another model after 20 seconds. Just to show it is possible
        setTimeout(() => {
            viewer.loadModel({
                title: "Rabbit",
                subtitle: "BabylonJS",
                thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
                url: "https://playground.babylonjs.com/scenes/Rabbit.babylon"
            });
        }, 20000);
    });
});
```

The `loadModel` function will return a `Promise<ViewerModel>` that is thenable when the model was fully loaded. Helpful when you want to tell the user the model loaded successfully :

```javascript
viewer.loadModel({
    title: "Helmet",
    subtitle: "BabylonJS",
    thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
    url: "https://www.babylonjs.com/Assets/DamagedHelmet/glTF/DamagedHelmet.gltf"
}).then(model => {
    console.log("model loaded!");
}).catch(error => {
    console.log("error loading the model!", error);
});
```


## Configuring the viewer

(Almost) every aspect of the viewer can be configured. The configuration is expressed using a TypeScript interface that is a JSON-like object describing the data that can be provided.

## The default configuration

The viewer currently defines two types of configurations:

1. The default configuration (`default`), including HTML templates for a navigation bar, layouts for help and error pages, a skybox, ground, shadows, and more. It is defined at [https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/default.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/default.ts)
2. The minimal configuration (`minimal`), with only the basics needed to show a model. It is defined at [https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/minimal.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/minimal.ts)

The default configuration will be loaded per default, unless other configuration type will be forced on the viewer by the developer. To force a different type of configuration, add the DOM attribute `extends` to the HTML element. For example:

```html
<babylon extends="minimal" model="https://playground.babylonjs.com/scenes/Rabbit.babylon"></babylon>
```

To understand the default configuration in more detail and learn how to recreate it using HTML see [Recreating the default configuration for the viewer](/features/featuresDeepDive/babylonViewer/defaultViewerConfig) 

## Extending and changing the default configurations

The default configuration types can be overwritten using many methods described below. As the configuration object never contains Array, any attribute in it can be references using a string, and can therefore be overwritten. 

The order in which the configuration is loaded is :

1. The DOM configuration
1. (optional) The extra configuration file provided using the `configuration` keyword.
1. The `extends` configuration (for example `default` or `minimal`). This is being merged with the DOM configuration, giving the DOM configuration priority

To explain this further, let's look at a simple example:

```html
<babylon extends="minimal" scene.debug="true" engine.antialiasing="false" model="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

At first, the configuration of the DOM element will be read (represented as JSON for better understanding):

```javascript
{
    extends: "minimal",
    scene: {
        debug: true
    },
    engine: {
        antialiasing: false
    },
    model: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
    configuration="http://example.com/viewerConfig.json"
}
```

Next, the `minimal`configuration will be loaded and appended to the existing configuration:

```javascript
{
    extends: "minimal",
    scene: {
        debug: true
    },
    engine: {
        antialiasing: false 
    },
    model: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
    configuration="http://example.com/viewerConfig.json",
    version: "0.1",
    templates: {
        main: {
            html: "<div>.........</div>"
        },
        loadingScreen: {
            html: "<div>.........</div>",
            params: {
                backgroundColor: "#000000",
                loadingImage: "data:image/png;base64....."
            }
        },
        viewer: {
            html: "<div>.........</div>",
        },
        overlay: {
            html: "<div>.........</div>",
            params: {
                closeImage: "data:image/png;base64.....",
                closeText: 'Close'
            }
        },
        error: {
            html: "<div>.........</div>"
        }

    },
}
```

Notice that thou the minimal configuration define antialiasing to be `true`, the configuration provided by the user will be used. It is only extending and not overwriting.

Next, the configuration object will be inspected. If it contains a configuration URL, it will be loaded. In our case, the (non-existing) [http://example.com/viewerConfig.json](http://example.com/viewerConfig.json) will be downloaded and appended to the configuration already provided. Notice that this configuration object will overwrite definitions in the current configuration object. So if the JSON file looks like this:

```json
{
    "scene": {
        "debug": false
    }
}
```

The `scene.debug` in the configuration object that will be provided to the viewer will have debug set to false.

### Configuring using the DOM element

The viewer will read each attribute on the `<babylon>` DOM element(s) provided and will create a JSON element out of them.
So, if the DOM element looks like this:

```html
<babylon scene.debug="true" camera.behaviors.auto-rotate="0" model.url="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

The configuration will look like this:

```javascript
{
    scene: {
        debug: true
    },
    camera: {
        behaviors: {
            autoRotate: 0
        }
    },
    model: {
        url: "https://playground.babylonjs.com/scenes/Rabbit.babylon"
    }
}
```

A few things to notice:

#### camel-case vs. kebab case

DOM attributes are usually written in kebab-case ('looks-like-this`), mainly since some browsers convert attributes to lower-case. Those attributes will be automatically converted to camelCase ('looksLikeThis').

#### Value conversions

Attribute-values are converted to their corresponding types in JSON. If the value can be converted to a number ("1" for example), it will be converted to a number. If the value is "true" or "false", it will be converted to a boolean.

#### Nested attributes

Nested attributes can be separated using ".". So `scene.debug="true"` will nest `debug` into `scene` and set its value to true.

#### Unidirectional definition

The DOM is read once, and is not being continuously processed, Changing a value of an attribute after the viewer was initialized will not influence the viewer.

### Configuring using nested DOM elements

Another way of using the DOM to configure the viewer is to use nested DOM elements inside the main element. A basic example:

```html
<babylon extends="minimal">
    <model url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf">
    </model>
    <camera>
        <behaviors>
            <auto-rotate type="0"></auto-rotate>
        </behaviors>
    </camera>
    <lights>
        <light1 type="1" shadow-enabled="true">
        </light1>
    </lights>
</babylon>
```

This is more human-readable and is easier for web-developers to understand. This example is technically the same as:

```html
<babylon extends="minimal" model.url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf" camera.behaviors.auto-rotate.type="0" lights.light1.type="2" lights.light1.shadow-enabled="true"></babylon>
```

A few things to consider:

#### Extending and using the DOM element configuration

Everything written regarding the DOM element configuration is extended here. The values are converted, kebab-case should be used, and nested attributes will still be correctly read. For example, this is also a valid configuration (notice the `<camera>` HTML tag):

```html
<babylon extends="minimal">
    <model url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf">
    </model>
    <camera behaviors.auto-rotate.type="0">
    </camera>
    <lights>
        <light1 type="1" shadow-enabled="true">
        </light1>
    </lights>
</babylon>
```

And it is the same as the example above.

### Configuring using external JSON

As previously explained, the viewer configuration has a `configuration` member, that can contain an external JSON file that will be loaded and merged with the selected configuration.

If the following is defined:

```html
<babylon scene.debug="true" camera.behaviors.auto-rotate="0" model.url="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

the file `http://example.com/viewerConfig.json` will be loaded into the configuration object. This is a great way of creating a general / global configuration  for a website, while providing the details model data using HTML.

### Configuring using JavaScript

Further discussed in [Advanced usage](//doc.babylonjs.com/extensions/Advanced_usage), JavaScript can be used to initialize a viewer. When initializing a viewer using JavaScript, you can provide the initial configuration that will be used with this viewer:

```javascript

let domElement = document.getElementById('my-amazing-element');

let viewer = new BabylonViewer.DefaultViewer(domElement, {
    scene: {
        debug: true
    },
    camera: {
        behaviors: {
            autoRotate: 0
        }
    },
    model: {
        url: "https://playground.babylonjs.com/scenes/Rabbit.babylon"
    }
});

```

In this case, the HTML attributes will be ignored(!) and the DOM element will simply serve as the container of the Babylon scene.

### Registering your own configuration parser using the mapper manager

As shown, the Babylon viewer has 3 types of configuration parsers for you to choose from - "html", "dom", and "json". Those mappers are registered in the mapper manager, exposed in the BabylonViewer namespace.

The mapper manager can be extended. If you have your own type of configuration, or want to support further file types, you can create your own mapper and register it with the mapper. Later on, you can define the type of mapper the configuration will be read with, using the configuration.type variable in the viewer's configuration. 

Let's build a pseudo YAML loader and register it:

First, we implement the IMapper interface:

```javascript

// In TypeScript
class YAMLMapper implements IMapper {
    map(yaml: YAMLThing): ViewerConfiguration {
        return this.convertToYaml(yaml);
    }

    // so, this needs to be actually implemented...
    convertYamlToJson(yaml) {}
}

// in JavaScript

let yamlMapper = {
    map : function(yaml) {
        return yaml.toJson();
    }
}
```

Afterwards, we need to register it with the mapperManager:

```javascript
BabylonViewer.mapperManager.registerMapper('yaml', yamlMapper);
```

And finally, we need to tell the manager which mapper to use:

```html
<babylon extends="minimal" scene.debug="true" engine.antialiasing="false" model="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration.url="http://example.com/viewerConfig.yaml" configuration.mapper="yaml"></babylon>
```

### Using your own payload without downloading a file

The configuration attribute of your html element can contain a url as previously shown, or a payload of type any - in case you already have the configuration in your own format loaded in the page.

This is useful if you want to be responsible to the download or if the data is simply already provided. As best practice you will need to:

1. Create your own mapper
1. Register the mapper
1. Set the payload and mapper

For example, let's say we have a predefined JSON configuration loaded in the page already. We could load it this way (notice configuration.payload):

```html
<babylon configuration.payload='{"scene": {"debug": true}}' model.title="Damaged Helmet" model.subtitle="BabylonJS" model.thumbnail="https://www.babylonjs.com/img/favicon/apple-icon-144x144.png"
            model.url="https://www.babylonjs.com/Assets/DamagedHelmet/glTF/DamagedHelmet.gltf" camera.behaviors.auto-rotate="0"
            templates.nav-bar.params.disable-on-fullscreen="true"></babylon>
```

This will work as the default mapper converts a JSON string to a configuration object. If you input a different style of configuration, you could set the mapper's type (after registering it):

```html
<babylon configuration.payload="scene.debug=true&engine.antialiasing=true" configuration.mapper="form" model.title="Damaged Helmet" model.subtitle="BabylonJS" model.thumbnail="https://www.babylonjs.com/img/favicon/apple-icon-144x144.png"
            model.url="https://www.babylonjs.com/Assets/DamagedHelmet/glTF/DamagedHelmet.gltf" camera.behaviors.auto-rotate="0"
            templates.nav-bar.params.disable-on-fullscreen="true"></babylon>
```

This will use the preregistered "form" mapper (which doesn't exist in reality - you should implement it) to read the payload and adjust the configuration.

## The full configuration interface

Please check the configuration on github, as it is constantly updated:
[https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/configuration.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/configuration.ts)

This tutorial is meant to show the advanced usage of the viewer's configuration only. It is meant as an explanation of what can be done and how you can modify the viewer to your needs using HTML only.

The default configuration is already implemented and can be used very easily, by adding `extends="default"` to your HTML element. In code, it is a JSON that looks roughly like this (without the HTML and image content):

```javascript
{
    templates: {
        main: {
            html: defaultTemplate,
            params: {
                babylonFont: babylonFont,
                noEscape: true
            }
        },
        fillContainer: {
            html: fillContainer,
            params: {
                disable: false
            }
        },
        loadingScreen: {
            html: loadingScreen,
            params: {
                backgroundColor: "#000000",
                loadingImage: images.loading
            }
        },
        viewer: {
            html: defaultViewer,
            params: {
                enableDragAndDrop: false
            }
        },
        navBar: {
            html: navbar,
            params: {
                speedList: {
                    "0.5x": "0.5",
                    "1.0x": "1.0",
                    "1.5x": "1.5",
                    "2.0x": "2.0",
                },
                logoImage: images.babylonLogo,
                logoText: 'BabylonJS',
                logoLink: 'https://babylonjs.com',
                hideHelp: true,
                hideHd: true,
                hideVr: true,
                disableOnFullscreen: false,
                text: {
                    hdButton: "Toggle HD",
                    fullscreenButton: "Fullscreen",
                    helpButton: "Help",
                    vrButton: "Toggle VR"
                }
            },
            events: {
                pointerdown: {
                    '.navbar-control': true,
                    '.help-button': true
                },
                input: {
                    '.progress-wrapper': true
                },
                pointerup: {
                    '.progress-wrapper': true
                }
            }
        }
    },
    camera: {
        behaviors: {
            autoRotate: {
                type: 0
            },
            framing: {
                type: 2,
                zoomOnBoundingInfo: true,
                zoomStopsAnimation: false
            },
            bouncing: {
                type: 1
            }
        }
    },
    skybox: {
    },
    ground: {
        receiveShadows: true
    },
    engine: {
        antialiasing: true
    }
}
```

## HTML element and viewer script

As a first step we will need to create our basic HTML page and include the viewer script. Since I am creating my own configuration, I will use `extends="none"` so that no configuration will be included at construction time.

```html
<html>
    <head>
        <title>Recreating the default configuration for Babylon.js viewer</title>
        <style>
            /* Force the viewer to have a specific size. This can be changed, of course. */
            babylon {
                width: 800px;
                height: 500px;
            }
        </style>
    </head>
    <body>
        <babylon extends="none"> </babylon>

        <script src="https://preview.babylonjs.com/viewer/babylon.viewer.js"></script>
    </body>
</html>
```

This is the basic foundation of the entire tutorial. From this point I will show only content in the `<body>` tag.

## Engine and camera configuration

To add the engine configuration (adding antialiasing for better image quality) I will add the engine HTML tag to the babylon tag:

```html
<babylon extends="none">
    
    <engine antialiasing="true"></engine>
</babylon>
```

The camera configuration is added afterwards, using the camera HTML tag:

```html
<babylon extends="none">
    
    <engine antialiasing="true"></engine>
    
    <camera>
        
        <behaviors>
            
            <auto-rotate type="0"></auto-rotate>
            
            <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
            
            <bouncing type="1"></bouncing>
        </behaviors>
    </camera>
</babylon>
```

The camera configuration includes camera behaviors' configuration, which are a native Babylon.js feature. You can read about it in [Camera behaviors](/features/featuresDeepDive/babylonViewer/configuringViewer)

## Adding environment

To add the environment we will need to enable the ground and the skybox. There are two options to do that. THe first is to enable them in the `<babylon>` tag. I use it when I don't want to further configure the element I am extending. For example:

```html
<babylon skybox="true" ground="true"> </babylon>
```

This will enable the default skybox and ground. Another way, which is the one I will be using is to add the HTML elements:

```html
<babylon extends="none">
    
    <ground receive-shadows="true"></ground>
    
    <skybox></skybox>

    
    <engine antialiasing="true"></engine>
    
    <camera>
        
        <behaviors>
            
            <auto-rotate type="0"></auto-rotate>
            
            <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
            
            <bouncing type="1"></bouncing>
        </behaviors>
    </camera>
</babylon>
```

The reasons I choose the 2nd way are:

-   It is readable and easy to understand
-   it is extendible. If I want to change the skybox's configuration, I need to change the tag and not add a new one.

## Templates - Main template

An important part of the viewer is the templating system - it takes predefined HTML elements, adds them where needed and attaches Babylon to the created canvas element and the buttons in the navigation bar. To read about it, visit [The templating system](/features/featuresDeepDive/babylonViewer/viewerTemplatingSystem).

The default viewer, which is the viewer we are using when using the `<babylon>` tag, expects certain templates to have specific elements (like a full screen button in the navigation bar, or a loading screen). If specific templates aren't included, the viewer will fail silently and will continue rendering the 3D element. The only obligatory template is the main template. Without a main template (which can be a single canvas and that's it) the viewer will fail.

### Adding a new template

To add a new template using HTML, I will add each template I want to add inside a `<script id="name-of-template" type="text/x-babylon-viewer-template">`. This template can later be referenced in the viewer configuration using the defined ID.

For example, this is the main template (copied from https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/assets/templates/default/defaultTemplate.html):

```html
<script id="main-template" type="text/x-babylon-viewer-template">
    <style>
        @font-face {
            font-family: 'babylon';
            src: url('{{babylonFont}}') format('woff');
            font-weight: normal;
            font-style: normal;
        }

        .icon {
            font-family: "babylon";
        }
    </style>

    {{#if fillScreen}}
    <style>
        html,
        body {
            width: 100%;
            height: 100%;

            margin: 0;
            padding: 0;
        }
    </style>
    {{/if}}

    <fill-container></fill-container>
</script>
```

Everything inside the script tag will be sent to [handlebars](https://handlebarsjs.com/). Since we are using handlebars you can parameters or use conditions inside your templates. Looking at the main template, you can see that there are two parameters that the template expects:

-   A link to a font file (that includes the icons we will later use in the navigation bar)
-   a flag, `fillScreen` that will add specific style definition if we want the viewer to fill the entire screen

You can also notice that the main template holds a tag called `fill-container`. The fill container tag will be populated using a template with the same name that I will define later. Using custom HTML tags are the way you can define your own templating tree and configure a specific part of the viewer without editing the rest of the elements.

### Adding the template to the viewer

The add the main template to the viewer, we will add the main tag to the babylon tag:

```html
<babylon extends="none">
    <templates>
        <main location="#main-template">
            <params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
        </main>
    </templates>

    
    <ground receive-shadows="true"></ground>
    
    <skybox></skybox>

    
    <engine antialiasing="true"></engine>
    
    <camera>
        
        <behaviors>
            
            <auto-rotate type="0"></auto-rotate>
            
            <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
            
            <bouncing type="1"></bouncing>
        </behaviors>
    </camera>
</babylon>
```

I'll dissect the templates tag to explain how it is configured.

#### Location parameter

```html
<main location="#main-template"></main>
```

This line adds a new template called "main" to the template manager. It will find its HTML source in the script template tag with the id `main-template` (which is the one we defined before). Location could also be a URL, from which the HTML will be downloaded and parsed. For example:

```html
<main location="https://example.com/templates/main.html"></main>
```

#### params element

To pass variables to the template when compiled (using handlebars), I pass variables in the params HTML tag. The following tag:

```html
<params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
```

will configure handlebars to not escape input (noEscape, https://handlebarsjs.com/reference.html) and will pass `babylonFont` to the template. It will then populate this in the line `src: url('{{babylonFont}}') format('woff');` of the main template I previously defined. We could also add the `fillScreen`flag to allow fullscreen viewer:

```html
<params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff" fill-screen="true"></params>
```

## Further templates

I continue adding the templates as I added the main template. I will show here two more templates that are important. The one holding the canvas, and the navigation bar - to show how to enable events.

### The template holding the canvas

A canvas is needed for babylon to work correctly. We will need to add one (and only one!) canvas element in one of the included templates.

```html
<script id="viewer-template" type="text/x-babylon-viewer-template">
    <style>
        viewer {
            position: relative;
            overflow: hidden;
            /* Start stage */
            z-index: 1;
            justify-content: center;
            align-items: center;

            width: 100%;
            height: 100%;
        }

        .babylonjs-canvas {
            flex: 1;
            width: 100%;
            height: 100%;
            /* enable cross-browser pointer events */
            touch-action: none;
        }
    </style>

    <canvas class="babylonjs-canvas" touch-action="none"></canvas>

    <nav-bar></nav-bar>
</script>
```

In order to get the pointer input work in all browsers - including iOS devices - I add the touch-action parameter to both the canvas element and the CSS definition of the canvas. This is very important. Otherwise certain browsers will not except user input.

### The navigation bar

In the case of navigation bar I want to show how to add the navbar's template and enable js-events on specific elements of it. The navbar's html code can be found here - https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/assets/templates/default/navbar.html .

This is the full `templates` object, with comments on the navbar definition

```html
<babylon extends="none">

    <templates>
        <main location="#main-template">
            <params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
        </main>
        <fill-container location="#fill-container-template">
            <params disable="false"></params>
        </fill-container>
        <loading-screen location="#loading-screen-template">
            <params background-color="#000000" loading-image="https://blogs.windows.com/uploads/mswbprod/sites/3/2018/05/b58474ab97a2708346422fe7ce30c15e.png"></params>
        </loading-screen>
        <viewer location="#viewer-template">
            <params enable-drag-and-drop="false"></params>
        </viewer>
        <nav-bar location="#nav-bar-template">
            
            <params logo-image="https://blogs.windows.com/uploads/mswbprod/sites/3/2018/05/b58474ab97a2708346422fe7ce30c15e.png" logo-text="BabylonJS"
                logo-link="https://babylonjs.com" hide-help="true" hide-hd="true" hide-vr="true" disable-on-fullscreen="false">
                
                <speed-list "0.5x"="0.5" "1.0x"="1.0" "2.0x"="2.0"></speed-list>
                
                <text hd-button="Toggle HD" fullscreen-button="Fullscreen"></text>
            </params>
            
            <events pointerdown="true" pointerup="true" input="true"></events>
        </nav-bar>
    </templates>

    
    <ground receive-shadows="true"></ground>
    
    <skybox></skybox>

    
    <engine antialiasing="true"></engine>
    
    <camera>
        
        <behaviors>
            
            <auto-rotate type="0"></auto-rotate>
            
            <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
            
            <bouncing type="1"></bouncing>
        </behaviors>
        
        <model url="https://models.babylonjs.com/shark.glb"></model>
    </camera>
</babylon>
```

## Viewing a model

Once the Babylon.js viewer if fully configured, you can specify which 3D model you want to view.

There are two ways to specify a 3D model

1. Add a `model` attribute on the `<babylon>` tag which can point to a 3D model file.

    ```html
    <babylon extends="none" model="https://models.babylonjs.com/shark.glb"></babylon>
    ```

2. Add a `<model>` HTML tag and set its `url` attribute to a 3D model file.
   `html <babylon extends="none"> <model url="https://models.babylonjs.com/shark.glb"></model> </babylon> `
   The examples point to a sample [shark glTF model](https://github.com/BabylonJS/MeshesLibrary/blob/master/shark.glb). You can also load other formats including `.glTF`, `.babylon`, `.obj`, and `.stl`. Note that the model won't be displayed till the entire configuration is added to the viewer.

## The full example

<p data-height="550" data-theme-id="light" data-slug-hash="KBXVdw" data-default-tab="html,result" data-user="BabylonJS" data-pen-title="[Babylon.js Viewer] Recreating default configuration" class="codepen">See the Pen <a href="https://codepen.io/BabylonJS/pen/KBXVdw/">[Babylon.js Viewer] Recreating default configuration</a> by Babylon.js (<a href="https://codepen.io/BabylonJS">@BabylonJS</a>) on <a href="https://codepen.io">CodePen</a>.</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>


This section holds a list of the current demos of the viewer

## Basic usage

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/basicExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/basicExample.html)

A basic example of loading a .babylon model with the default configuration.

[Live demo](https://viewer.babylonjs.com/basicexample)

## DOM configuration

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/domExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/domExample.html)

An example on how to use the DOM to configure the viewer

[Live demo](https://viewer.babylonjs.com/domexample)

## Events example

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/eventsExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/eventsExample.html)

An example on how to load the viewer and use its observers using promises, observables and callbacks.

[Live demo](https://viewer.babylonjs.com/eventsexample)

## Animations example

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/ufoExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/ufoExample.html)

An example of the animation system of the default viewer

[Live demo](https://viewer.babylonjs.com/ufoexample)


The viewer has a simple integrated templating system for you to use and extend. Using the templating system you can decide how the viewer components, such as the navbar, the error screen, help screen and so on, look like.

The templating system is using [Handlebars.js](https://handlebarsjs.com/) to parse the HTML. We recommend understanding the basic concepts of Handelbars before making major changes to the HTML templates.

## Basics of the templating engine

### Configuration

As with the general configuration, the template configuration is based on a TypeScript interface for ease of usage. These are the interfaces:

```javascript
export interface ITemplateConfiguration {
  location?: string; // #template-id OR http://example.com/loading.html
  html?: string; // raw html string
  id?: string;
  params?: { [key: string]: string | number | boolean | object };
  events?: {
    // pointer events
    pointerdown?: boolean | { [id: string]: boolean },
    pointerup?: boolean | { [id: string]: boolean },
    pointermove?: boolean | { [id: string]: boolean },
    pointerover?: boolean | { [id: string]: boolean },
    pointerout?: boolean | { [id: string]: boolean },
    pointerenter?: boolean | { [id: string]: boolean },
    pointerleave?: boolean | { [id: string]: boolean },
    pointercancel?: boolean | { [id: string]: boolean },
    //click, just in case
    click?: boolean | { [id: string]: boolean },
    // drag and drop
    dragstart?: boolean | { [id: string]: boolean },
    drop?: boolean | { [id: string]: boolean },

    [key: string]: boolean | { [id: string]: boolean } | undefined, // allow injecting further events
  };
}
```

### Location vs. HTML

There are two ways of defining where the template is found. The location and the html parameters. One of them will have to be defined. if both are defined, the 'html' parameter will be used.

The location parameter define a URL where the HTML can be found, or an ID of a script tag with the type "text/x-babylon-viewer-template". For example, the HTML page can have somewhere in it the following HTML element:

```html
<script id="loading-screen" type="text/x-babylon-viewer-template">
  <img class="loading-image" src="{{loadingImage}}">
</script>
```

The configuration for using this would be:

```javascript
    ...,
    templates: {
        main: {
            html: "<viewer></viewer><loading-screen></loading-screen>"
        },
        loadingScreen: {
            location: '#loading-screen',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        },
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

The 'html' parameter simply contains the raw HTML of the template. For example:

```javascript
    ...,
    templates: {
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

When the template is a simple HTML file and no other configuration is needed, the template configuration can be a single string of the URL or #id where the template can be found.

So this:

```javascript
    .....,
    templates: {
        main: {
            location: "#main-template"
        }
    },
    ....
```

is equal to this:

```javascript
    .....,
    templates: {
        main: "#main-template"
    },
    ....
```

### Simple walkthrough

The templating engine will load all defined templates in the configuration and parse them. As part of the parsing process, it will look for tags that are defined in the template configuration and will inject them in the right place. The template that will be injected to the main component (the `<babylon>` HTML tag per default) is always called 'main'.

For example, if the templating configuration looks like this:

```javascript
    templates: {
        main: {
            html: "<viewer></viewer><loading-screen></loading-screen>"
        },
        loadingScreen: {
            html: '<img class="loading-image" src="{{loadingImage}}">',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        },
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

the final `<babylon>` tag will look like this:

```html
<babylon .....>
  <viewer>
    <canvas class="babylonjs-canvas"></canvas>
  </viewer>
  <loading-screen>
    <img class="loading-image" src="data:image/png;base64,...." />
  </loading-screen>
</babylon>
```

_Note that the html tag names are in kebab-case. The configuration (when in JSON format) uses camelCase_.

### Handlebars expressions

Going back to the configuration from the last section, you can see that the HTML template of the loading screen is:

```html
<img class="loading-image" src="{{loadingImage}}" />
```

Anything inside a `{{` and `}}` is considered to be a handlebars expression. This parameter can be defined in the configuration file, as also seen in the last section:

```javascript
    templates: {
        ...,
        loadingScreen: {
            html: '<img class="loading-image" src="{{loadingImage}}">',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        }
    }
```

Using this method you can easily achieve internationalization, injecting the parameters using the configuration and not embedding them into the HTML.

### Event binding

Any template can have any native JavaScript event registered to it or to one of its children. The callback will be bound to the selected element, and will trigger a callback in the template, which can be used when registering the onEventTriggered observer of the template. But first, let's see how to simply bind events:

Let'S take a look at the following configuration (taken from the default configuration with a bit of changes):

```javascript
        navBar: {
            html: '<div class="button-container flex-container">  <div id="fullscreen-button" class="button"> <span>Full screen</span>> </div> </div>',
            events: {
                pointerdown: { 'fullscreen-button': true, 'some-other-id': true },
                drop: true
            }
        },
```

This events configuration will register two events:

1. pointerdown event that will be bound to the inner `#fullscreen-button` div
1. drop event that will be bound to the navbar element itself.

_If you are wondering why the event definition (\{ 'fullscreen-button': true, 'some-other-id': true \}) is a map and not an array of IDs - the template can also be configured using HTML, and HTML DOM elements don't support Arrays. This way the HTML can override the event by setting it to "false"._

The event callback will deliver the following object:

```javascript
export interface EventCallback {
  event: Event; // the native browser event
  template: Template; // the template on which is was executed
  selector: string; // the selector used (for example #fullscreen-button)
  payload?: any; // any extra payload. For future development, currently not being used.
}
```

To register for event listening, load the template using the template manager and add an observer to the `onEventTriggered` observable:

```javascript
// viewer is a viewer instance. See Advanced usage (//doc.babylonjs.com/extensions/Advanced_usage) for further details on how to get it.
let navbar = viewer.templateManager.getTemplate("navBar");
// let's be safe!
if (!navbar) return;

// register a new observer
navbar.onEventTriggered.add((data) => {
  switch (data.event.type) {
    case "pointerdown":
      switch (data.selector) {
        case "#fullscreen-button":
          // let's go full screen!!
          break;
        case "#some-other-id":
          // just do something else please
          break;
      }
      break;
    case "drop":
      // What shall we do with the dropped data?
      break;
  }
});
```

## The template manager

Any template-enabled viewer (the default viewer, for example) has its own template manager, which is in charge of loading and parsing the templates.

The template manager is a public member of the viewer and can be used to retrieve already-parsed templates:

```javascript
// not a part of this section, let's assume the viewer is being retrieved
let viewer = getViewer();

// We have previously defined a "canvas" element in the configuration. We can now retrieve it!
let canvasContainer = viewer.templateManager.getTemplate("canvasContainer");
```

### The template object

Any configured template is creating a new instance of the [Template class](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/templating/templateManager.ts).

Here are the public variables we can access:

```javascript
public onInit: Observable<Template>;
public onLoaded: Observable<Template>;
public onAppended: Observable<Template>;
public onStateChange: Observable<Template>;
public onEventTriggered: Observable<EventCallback>;

public isLoaded: boolean; // is the template fully loaded

public parent: HTMLElement; // the HTML container of this template. In this case, the <canvas-container> element.
```

The Template class has also a few promise-based help functions for common tasks:

```javascript
public show(visibilityFunction?: (template: Template) => Promise<Template>): Promise<Template>;
public hide(visibilityFunction?: (template: Template) => Promise<Template>): Promise<Template>;
```

If calling those functions without any parameters, the `display`of this template will be set to `flex` or `none` respectively.

To define your own show or hide functions, simply provide the visibilityFunction as the first parameter. The following is a real example from the default viewer:

```javascript
template.hide((template) => {
  // set the opacity to '0'. Opacity transition is set using CSS.
  template.parent.style.opacity = "0";
  // define a function for when the transition has ended:
  let onTransitionEnd = () => {
    template.parent.removeEventListener("transitionend", onTransitionEnd);
    // set display none when opacity is '0'
    template.parent.style.display = "none";
  };
  // add the transitionend event listener
  template.parent.addEventListener("transitionend", onTransitionEnd);
  // return immediately, don't wait for the transition to end
  return Promise.resolve(template);
});
```

## Templates of the default viewer

The default viewer comes with predefined templates that can be simply changed if needed.

The list of templates that are delivered:

- main - the main template (must always be present)
- viewer - containing the canvas
- loading screen - a simple loading screen template
- nav-bar - the bottom navigation bar
- overlay - a container for overlays, such as error or help
- error - an error screen
- help - a help screen
- share - a share screen

All templates can be found at the assets directory of the viewer - [https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/Viewer/assets/templates/default](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/Viewer/assets/templates/default). The templates include CSS internally, and are self-contained.

### Changing an existing template

If you want to change one of the templates, simply create a new HTML structure and set it in the viewer configuration. For example, if we want to change the loading screen so it will not show an image at all:

The new loadingScreen HTML injected in the page as `<script>` tag:

```html
<script id="loading-screen" type="text/x-babylon-viewer-template">
    <style>
      loading-screen {
          position: absolute;
          z-index: 100;
          opacity: 1;
          pointer-events: none;
          display: flex;
          justify-content: center;
          align-items: center;
          -webkit-transition: opacity 2s ease;
          -moz-transition: opacity 2s ease;
          transition: opacity 2s ease;
      }
  </style>

  <span> LOADING... </span>
</script>
```

This can be added to the configuration of the viewer element:

```html
<babylon templates.loading-screen.location="#loading-screen" templates.loading-screen.html="" model="...."></babylon>
```

### Extending an existing template

The nav bar, for example, can be extended to hold further buttons. The navbar default configuration is:

```javascript
navBar: {
    html: require("../../../assets/templates/default/navbar.html"),
    params: {
        buttons: [
            {
                id: 'fullscreen-button',
                altText: "Fullscreen",
                image: require('../../../assets/img/fullscreen.png')
            }
        ],
        visibilityTimeout: 2000
    },
    events: {
        pointerdown: { 'fullscreen-button': true }
    }
}
```

If you want, for example, to change the visibilityTimeout to 1 second, set it using your viewer configuration:

```html
<babylon templates.nav-bar.params.visibility-timeout="1000" model="...."></babylon>
```

## Creating your own templates

If you don't want to use the default templates and want to completely create your own, here are a few important notes.

### The main template

You should always have a template named "main", which will be the starting point of your template. Apart from "main", it is up to you to decide how to organize your templates. Main can technically contain everything, there is no actual need to create any other templates, unless you want to internally overwrite certain templates.

The main template can technically be a single canvas element, and that's about it.

### You need a canvas

Well, a canvas is needed, obviously. **and only one!** To avoid creating further unneeded configuration parameters, the first canvas found inside the parsed main template will be used as the canvas for Babylon.

## If help is needed

Look at the code or contact us, we will be more than happy to help!



## Display 3D models on your webpage

The Babylon.js viewer is the simplest way to display 3D content on a web page.

To display a 3D model on you web page:

1. Add a script reference to the viewer

    ```html
    <script src="https://cdn.babylonjs.com/viewer/babylon.viewer.js"></script>
    ```

2. Add a `<babylon>` tag and set the _model_ attribute to point to a `.gltf` or `.glb` file

    ```html
    <babylon model="model.gltf"></babylon>
    ```

    We recommend using the [glTF format](https://github.com/khronosgroup/gltf) (`.gltf` or `.glb`) for displaying 3D models on your webpage. Other formats supported by Babylon.js loaders are also supported by the viewer component including `.babylon`, `.obj`, and `.stl` formats.

The Babylon.js viewer automatically provides a [default viewing experience](#default-viewing-experience) for 3D models. All aspects of this experience are configurable. See [Configuring the viewer](//doc.babylonjs.com/extensions/babylonViewer/configuringViewer) for more information on customizing the viewing experience.

## Example

<p data-height="400" data-theme-id="light" data-slug-hash="QxzBPd" data-default-tab="html,result" data-user="BabylonJS" data-embed-version="2" data-pen-title="Babylon.js Viewer - Display a 3D model" class="codepen">See the Pen <a href="https://codepen.io/BabylonJS/pen/QxzBPd/">Babylon.js Viewer - Display a 3D model</a> by Babylon.js (<a href="https://codepen.io/BabylonJS">@BabylonJS</a>) on <a href="https://codepen.io">CodePen</a>.</p>

## Resizing

Controlling the size of the viewer is one of the most common configuration operation. It is rather easy as the viewer in default mode will fill 100% of the width and height of its container. So in order to control the viewer, you can simply style its encclosing container.

<p data-height="400" data-theme-id="light" data-slug-hash="qMBwar" data-default-tab="html,result" data-user="BabylonJS" data-pen-title="Babylon.js Viewer - Resize the viewer" class="codepen">See the Pen <a href="https://codepen.io/BabylonJS/pen/qMBwar/">Babylon.js Viewer - Resize the viewer</a> by Babylon.js (<a href="https://codepen.io/BabylonJS">@BabylonJS</a>) on <a href="https://codepen.io">CodePen</a>.</p>

<script async src="https://static.codepen.io/assets/embed/ei.js"></script>

## Using the viewer in your project

The Babylon.js viewer is available on CDN as well as an NPM package. The Babylon.js viewer is a wrapper around the Babylon.js engine and follows the same versioning scheme as the engine. The currently stable version of the Babylon.js viewer will use the current stable version of Babylon.js engine and the preview version of the Babylon.js viewer will use the preview version of Babylon.js engine.

## CDN

Stable versions of the viewer are available on:

-   https://cdn.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://cdn.babylonjs.com/viewer/babylon.viewer.max.js

Preview releases (nightlies) of the viewer are available on:

-   https://preview.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://preview.babylonjs.com/viewer/babylon.viewer.max.js

## NPM

To install the Babylon.js viewer through NPM use:

```javascript
npm install --save babylonjs-viewer
```

This will install the latest stable version of the viewer, including its needed dependencies.

Afterwards it can be imported to the project using:

```javascript
import "babylonjs-viewer";
```

This will enable the `BabylonViewer` namespace.



## Concepts

Tag? You may already have heard or read this word before. Let's see some generic concepts.

### Tags are used:

- as an index term assigned to a piece of information
- to pass parameters to subroutines
- as components of the HTML markup language
- as labels for specific revisions of a project
- as unique identifiers in URI
- as links to other Facebook pages
  ...

(from [Wikipedia](http://en.wikipedia.org/wiki/Tag))

### Tags on forums / Categories

If you spend some time on forums (let's pick one randomly: [forum](https://forum.babylonjs.com) ;)), you may have noticed that tags are attached to topics (and/or posts sometimes).
The author can write words (tags) to shortly describe his/her topic without having to write a gramatically correct sentence. It's kind of a list of words that you could say during a brainstorming after reading the post.

Thus, if you need information about, let's say, meshes, you can search for topics having "mesh" as a word in those topics, BUT you could also search for "mesh" as a tag of the topic. Indeed, maybe the word is never used in the topic (maybe it's only used, or not, in the title) but the author can choose to add it as a tag in the aim to categorize his/her topic.
Tags can be used to categorize/group things.

### CSS classes

OK...? What's the link with tags? Why are we about to talk about CSS classes?

Because CSS classes are great and Tags in Babylon.js can be considered similar, in principle, to CSS classes. So let's talk about them.

CSS stands for Cascading Style Sheets. It's used to define how to display HTML elements.

CSS classes are added to HTML elements (by writing them directly in the HTML code or by adding them via javascript) as a value of the `class` attribute of the corresponding HTML elements.

HTML elements can have several CSS classes in their `class` attribute and the same CSS class can be used on different HTML elements. CSS classes, just like tags on forums, can then be used to categorize HTML elements. Thus, a same style (background, font, color...) can easily be applied to a group of HTML elements identified by a CSS class (or a list of CSS classes).

_Style for all HTML elements of the page having the "center" class on them (to find elements with a specific class, write a period character, followed by the name of the class)_

```css
.center
{
    text-align: center;
    color: red;
}
```

Thanks to javascript, you can even retrieve all these elements and then do further javascript operations on them (jQuery plugins largely use CSS classes).

```javascript
const elements = document.getElementsByClassName(".center");
```

The above directive would gather a collection of all HTML elements that use the .center class.

Here we are! **Tags in babylon.js can be used to categorize/group elements, and helper functions are provided to retrieve/gather tagged elements.**

## Integration to babylon.js

Tags were integrated into babylon.js on April 7, 2014. [Pull request](https://github.com/BabylonJS/Babylon.js/pull/170#event-109351015)

### Pure javascript

The concept was expanded to allow the adding of tags on any javascript object (not necessarily only the objects created by babylon.js). The `Tag` class that has been added to babylon.js contains all the necessary code for this generic concept ([Typescript code](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Misc/tags.ts)) and internally uses the `AndOrNotEvaluator` class ([Typescript code](https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/core/src/Misc/andOrNotEvaluator.ts)).

The use of tags for a javascript object can be enabled/disabled like this (javascript code):

```javascript
const myJSObj = {};
// enable tags for myJSObj
BABYLON.Tags.EnableFor(myJSObj);

// disable tags for myJSObj
BABYLON.Tags.DisableFor(myJSObj);
```

`EnableFor` adds functions to the javascript object in the aim to:

- test if it has tags `hasTags`
- add tags to it `addTags`
- remove tags from it `removesTags`
- test if it matches a tags query `matchesTagsQuery` (see below)

Those functions are proxies of static methods of `Tags` (`HasTags`, `AddTagsTo`, `RemoveTagsFrom` and `MatchesQuery`).

`Tags` also contains `GetTags` which retrieves the array of tags of the javascript object.

Remark: Tags.AddTagsTo enables tags for the object if needed

```javascript
const myJSObj1 = {};
// enable tags for myJSObj1
BABYLON.Tags.EnableFor(myJSObj); // => addTags is available on myJSObj1
// add tags to myJSObj1
myJSObj1.addTags("tag1 tag2"); // same as BABYLON.Tags.AddTagsTo(myJSObj1, "tag1 tag2"),

const myJSObj2 = {};
// add tags to myJSObj2 without having to enable tags for it first
BABYLON.Tags.AddTagsTo(myJSObj2, "tag1 tag2"); // addTags couldn't be used on myJSObj2 since tags were not previously enabled for myJSObj2
```

Tags query:

`Tags.MatchesQuery` (and `matchesTagsQuery` if tags are enabled for the javascript object) accepts a list of correct tags (see "Rules to respect") containing parenthesis, and boolean evaluators such as `(tag1 && (tag2 || tag4 || !tag5)) || !(!tag1) && !!!tag5`. The tags query is evaluated thanks to `AndOrNotEvaluator`.

Full example:

```javascript
const myJSObj1 = {};
BABYLON.Tags.AddTagsTo(myJSObj1, "tag1 tag2");

const myJSObj2 = {};
BABYLON.Tags.AddTagsTo(myJSObj2, "tag3 tag4 tag5");

const myJSObj3 = {};
BABYLON.Tags.EnableFor(myJSObj3);

const myJSObj4 = {};

myJSObj4.hasTags(); // TypeError: undefined is not a function
BABYLON.Tags.HasTags(myJSObj4); // false

myJSObj3.hasTags(); // false
BABYLON.Tags.HasTags(myJSObj3); // false

myJSObj2.hasTags(); // true
myJSObj1.hasTags(); // true

myJSObj1.matchesTagsQuery("tag1"); // true
myJSObj1.matchesTagsQuery("tag2"); // true
myJSObj1.matchesTagsQuery("tag1 || tag2"); // true
myJSObj1.matchesTagsQuery("tag1 && tag2"); // true
myJSObj1.matchesTagsQuery("tag3"); // false
myJSObj1.matchesTagsQuery("!tag3"); // true
myJSObj1.matchesTagsQuery("tag1 && tag3"); // false
myJSObj1.matchesTagsQuery("tag1 || tag3"); // true
myJSObj1.matchesTagsQuery("tag1 && !tag3"); // true

myJSObj1.removeTags("tag1");

myJSObj1.matchesTagsQuery("tag1 && !tag3"); // false

myJSObj2.removeTags("tag4 tag3 tag5");

myJSObj2.hasTags(); // false

BABYLON.Tags.DisableFor(myJSObj2);

myJSObj2.hasTags(); // TypeError: undefined is not a function

myJSObj3.matchesTagsQuery(""); // false
myJSObj3.matchesTagsQuery(); // true

myJSObj4.matchesTagsQuery(""); // TypeError: undefined is not a function
myJSObj4.matchesTagsQuery(); // TypeError: undefined is not a function

BABYLON.Tags.MatchesQuery(myJSObj4, ""); // false
BABYLON.Tags.MatchesQuery(myJSObj4, undefined); // true
BABYLON.Tags.MatchesQuery(myJSObj4); // true
```

### Rules to respect

- the tags "true" and "false" are reserved and cannot be used as tags.
- a tag cannot start with "||", "&&", or '!'
- a tag cannot contain whitespaces

### Use in babylon.js

Since it's possible to use tags on any javascript object and since meshes are javascript objects, it's possible to add tags on them and to retrieve them according to a tags query.

```javascript
const meshes = myScene.getMeshesByTags("tag1 && (tag2 || tag4 || !tag5)) || !(!tag1) && !!!tag5");
```

All tags added to meshes, cameras, lights... are saved to the scene files (see [.babylon file format](/setup/support/.babylonFileFormat) and reloaded from them.

## What to do with them?

It's up to you!

You can use them to retrieve all the meshes that should be lighted by the light "light1":

```javascript
const meshesToLightByLight1 = myScene.getMeshesByTags("mustBeLightedByLight1");
```

or make some green ghosts appear when you want:

```javascript
const ghosts = myScene.getMeshesByTags("ghost && green");

for (let index = 0; index < ghosts.length; index++) {
  ghosts[index].isVisible = true;
}
```


Babylon.js Viewer

Display 3D models on your webpage

Example

Resizing

Using the viewer in your project

CDN

NPM

Further reading

Configuring the Babylon.js Viewer

How to configure the Babylon.js viewer.

Babylon.js Viewer Templating System

Using and extending the viewer's simple integrated templating system.

Modify the Babylon.js Viewer

Modifying the Babylon.js viewer using HTML.

Babylon.js Viewer - Advanced usage

Advanced uses of the viewer.

Babylon.js Viewer Examples

Examples of using the viewer

Coming next