Embed API: Embedding a Scene Instead of a Configurator

Usually, the configurator is embedded into a web page: if that configurator uses a 3D scene, the scene is automatically embedded with the configurator as you would expect.  But in some cases you may want to embed an independent scene (with no configurator associated with it).  

First add to your web page a reference to the KBMax embed script.

<script src="https://subdomain.kbmax.com/js/embed.js"></script>

Replace the word 'subdomain' with your company subdomain, including the environment.

Add to your web page another script (either in a script tag, or in a referenced script file), where you can initalize your scene and start manipulating it.  Here is a full example:

//wait until the document loads before using the kbmax embed api
document.addEventListener("DOMContentLoaded", function() {
	//start the embed
	var config = new kbmax.SceneEmbed({
		elementId: "viewer",
		sceneId: 2008,
		sceneGuid: "d4478a96-7aa4-4566-aa68-f8dd48a263f8",
		bare: true,
		showFields: false,
		showConfigHeader: true,
		showMove: true,
		bindToFormSelector: "",
		loadImage: "",
		progressColor: "orange"	});


	//to interact with the scene, you primarily just set field values, 
	//and the scene rules take over from there.
	//To set field values, you can use the setFields command, 
	//which takes a javascript object where each
	//property is a field name, and the property value is the 
	//value you want to set for the field
	config.setFields({ "Field1": "Hello 3D!", "Field2": 15 });

	//you can run an action using the following...
	config.runAction("actionName");
});

Let's break down the scene script above to understand it.  First, you need to create a new instance of the SceneEmbed class:

var config = new kbmax.SceneEmbed({
	elementId: "viewer",
	sceneId: 2008,
	sceneGuid: "d4478a96-7aa4-4566-aa68-f8dd48a263f8",
	bare: true,
	showFields: false,
	showConfigHeader: true,
	showMove: true,
	bindToFormSelector: "",
	loadImage: "",
	progressColor: "orange"});

The constructor of the SceneEmbed class accepts an arguments object of the embed arguments.

If you want to get a reference to an already existing embed, that was created either by the HTML api or earlier in the javascript, you only need to provide the elementSelector (or elementId) argument.

var existingEmbed = new kbmax.SceneEmbed({elementId: "viewer"});

Now that you have an embed object, you can start making calls to control your scene.

SceneEmbed Calls

Call	Description
setFields(fieldsObject)	Sets values of fields in the scene. The fields object parameter is an anonymous object where the properties are field names, and the values are the value for that field. For example: config.setFields({ "Width": 5, "Height": 10, "Color": "Red"});  Only the fields that you provide values for will be set in the scene. Any other fields in the scene will be left alone.
getFields(callback)	Gets an anonymous object where the properties are the field names, and the values are the field values from the configurator. This is an asynchronous call and requires you to use a callback to get the result. config.getFields(function(o){ //o will contain the field names and values });
runAction(actionName)	Runs a scene action with the given name. For example, if you have a button on your HTML page, and when clicked you want the scene to run its explode animation, you could add the following code in the button click handler: viewer.runAction("explode");
setFieldsFromForm(formSelector)	Similar to the bindToForm embed argument, calling setFieldsFromForm will look for any inputs in the given form, match them with fields in the scene, and update the scene accordingly.
onMessage.add(handler)	Configurators can send messages to your page when certain events have occurred. For example, if you have a configurator of a car, and the user clicks on the dashboard, you might want to switch to a tab with options for the interior of the car. You can add a handler that will be called whenever you get a message from the configurator, and respond accordingly. For example: config.onMessage.add(function (msg) { if (msg.name == "show tab") { //messages have a name to differentiate //the data property of the message contains custom data from your scene. //In this case, we are using it to pass the name of the tab //this is just sample code, replace with your own showTab("#" + msg.data); } });
onMessage.remove(handler)	Used to remove a message handler that you added using onMessage.add().