Manage scenes

Once you understand the scene structure and identification as well as the rules for adding, deleting, and changing scenes, you can call APIs of the Whiteboard SDK to manage scenes and build multi-scene whiteboard applications according to your business needs.

This feature is for Web only.

This page describes how to call APIs provided by the Whiteboard SDK to get scene information, insert new scenes, switch, move, and delete scenes, and clear all the contents of a scene.

Understand the tech

The Whiteboard SDK provides the following methods in the Room interface for managing scenes:

Prerequisites

To follow the procedure on this page, ensure that you have integrated the Whiteboard SDK into your project and implemented joining a room. For details, see Join the Whiteboard Room.

The following section extends the Join the Whiteboard Room sample code to show the implementation of scene management.

Implement scene management

Get scene information

After successfully joining the whiteboard room, you can call the following methods to get the scene information:

• SceneState: Gets the information of the scene that is currently displayed on the whiteboard. The information includes the scene path, name, and index.
• entireScenes: Gets the information of all scenes in the current room.

For example, to get the information of the current scene, you can add the following lines to the joinWhiteboard.js file:

whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Add the following code to get the path, name, and index of the current scene.
    var sceneState = room.state.sceneState;
    console.log("scene path:", sceneState.scenePath);
    console.log("scene name:", sceneState.sceneName);
    console.log("scene index:", sceneState.index);

}).catch(function(err) {

    console.error(err);
});

Save the changes, refresh the index.html page, and open the console of your browser. You can see the following information on the console:

[White] join room success
scene path: /init
scene name: init
scene index: 0

In a newly created whiteboard room, there is only one default initial scene, whose path is /init, name is init, and index is 0.

Add scenes

The Whiteboard SDK provides the putScenes method to insert new scenes in a specified scene directory and display images or web pages on scenes.

When calling putScenes, you need to pass in the following parameters:

• path: The path of a scene directory, which must start with / and cannot be the path of a scene.

• scenes: An array of scenes. A single scene contains the following fields:

  • name: Name of the scene.
  • ppt: (Optional) The image or web page to be displayed in the scene. Each scene can display only one image or web page. You can also use PptDescription.

• index: (Optional) The index number of the first scene to be inserted in the scene directory. The index numbers of subsequent scenes increase sequentially. The index number of a scene starts from 0.

For example, add the following lines to the joinWhiteboard.js file to insert two new scenes in the root scene directory (new-page5, which has an image, and new-page6, which is blank):

whiteWebSdk.joinRoom(joinRoomParams)
	.then(function(room) {

		room.bindHtmlElement(document.getElementById("whiteboard"));
		// Create new scenes and insert them to the specified scene directory.
		var scenes = [{
				name: "new-page5",
				ppt: {
					width: 720,
					height: 640,
					src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"
				}
			},
			{
				name: "new-page6"
			},
		]
		room.putScenes("/", scenes);

		// Output a list of all scenes in the room.
		var scenemap = room.entireScenes();
		console.log("scene map:", scenemap);

	})
	.catch(function(err) {

		console.error(err);
	});

Save the changes and refresh the index.html page. You can see the following information on the browser's console:

{
    "/": [
        {name: "init", ppt: undefined},
        {name: "new-page5", ppt: {width: 720, height: 640, src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"}},
        {name: "new-page6", ppt: undefined},
    ],
}

However, after calling putScenes to insert new scenes, the SDK does not directly switch to the newly inserted scene. You need to call setScenePath or setSceneIndex to switch to a specified scene.

Switch scenes

The Whiteboard SDK provides the following methods to switch scenes:

• setScenePath: Switches to a scene by specifying the path of the scene. This method can switch to any scene in the current room.
• setSceneIndex: Switches to a scene by specifying the index number of the scene. This method can only switch to a scene in the current scene directory.

Now you can call the two methods to switch to the new scenes inserted in the Add scenes section.

To switch to new-page5 by specifying its path, add the following line after room.putScenes("/", scenes); in the previous example code:

room.setScenePath("/new-page5");

After saving the changes and refreshing the index.html page, you can see the new scene with an image on the whiteboard. The information of the current scene output on the console is as follows:

[White] join room success
scene path: /new-page5
scene name: new-page5
scene index: 1

You can call setSceneIndex and pass in index number 2 to switch to scene new-page6:

room.setSceneIndex(2);

Save the changes and refresh the index.html page. You can see the blank new scene display in the whiteboard room. You can also check the current scene information on the console to verify the switch is successful.

Move scenes

You can call moveScene and pass in the original scene path and the target scene path to move a scene or rename a scene.

For example, to move the new-page5 scene to a new scene directory, SceneC, add the following code after room.putScenes("/", scenes);:

room.moveScene("/new-page5", "/sceneC/new-page5");

After saving the changes and refreshing the index.html page, you can see the following information under the scene map section on the browser's console:

{
    "/": [
        {name: "init", ppt: undefined},
        {name: "new-page6", ppt: undefined},
    ],
    "/sceneC": [
        {name: "new-page5", ppt: {width: 720, height: 640, src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"}},
    ],
}

This information shows that new-page5 is successfully moved to sceneC.

To rename a scene, keep the scene directories unchanged and only change the scene name in the target scene path. For example, to rename new-page5 to new-page7, add the following code:

room.moveScene("/new-page5", "/new-page7");

Clear the contents of a scene

You can call cleanCurrentScene to clear all contents on the current scene. This method does not clear the image or web page displayed on the scene by default, however. If you need to clear the image or web page as well, call cleanCurrentScene(false).

For example, add the following code in the joinWhiteboard.js file to clear the current scene:

room.cleanCurrentScene();

After saving the changes and refreshing the index.html page, you can see the scene is cleared.

Delete scenes

You can call removeScenes and pass in the path of a scene or a scene directory to delete a scene or all scenes under a scene directory.

For example, to remove all scenes under the root scene directory, add the following code in the joinWhiteboard.js file:

room.removeScenes("/");

Save the changes and refresh the index.html page. Check the scene map information output on the browser's console and you can see there is only one scene with the path /init in the room. This is the scene the SDK creates automatically after all scenes in the room are deleted.

Reference

Once you grasp the basic operations of scenes, you can refer to Display Files for instructions on creating a set of scenes to display a complete file.