KB112: The Character Builder API

Invoking methods on your module

When you publish your Character Builder module, you obtain a small snippet of html code that you place in your own website where you want your module to appear. In many cases the module is completely self-sufficient. For example a Slideshow module can be started and stopped using the navigation bar. Likewise, an Agent module can have a single message that is set to auto-play. You can also use JavaScript to control a module. This is especially useful with the Agent module, which can be configured with multiple messages, and different messages can be triggered by events on your page.

A typical embed tag for an Agent module looks like this:

<script src="https://www.mediasemantics.com/agent.min.js"></script>
<div id="myDiv" style="width:250px; height:200px;"></div>
<script>document.addEventListener("DOMContentLoaded", function() {CBAgentModule.setupDiv("myDiv", "123456", "12345678")})</script>

In order to get a reference to your module, you can alter the embed code as follows:

<script src="https://www.mediasemantics.com/agent.min.js"></script>
<div id="myDiv" style="width:250px; height:200px;"></div>
<script>var myAgent; document.addEventListener("DOMContentLoaded", function() {myAgent = CBAgentModule.setupDiv("myDiv", "123456", "12345678")})</script>

You can then invoke the module's API using this reference.

<a href="javascript:test()">test</a>
<script>
function test() {
  myAgent.play("Message 1");
}
</script>

You can also stop a long-running message with the stop() method.

Startup parameters

The fourth parameter to setupDiv() is a parameters object that you can use to override several default behaviors. For example you can override the default module "fade in" behavior as follows:

CBAgentModule.setupDiv("myDiv", "123456", "12345678", {fade:false})})

Using jquery

You can also use the jquery 'cbagent' plugin to invoke a method using the id of the containing div.

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script>
  function test() {
    $("#myDiv").cbagent("play", "Message 1");
  }
</script>

Similarly, you can use the jquery 'slideshow' and 'softskills' plugins to access these modules.

If you prefer, you can also use jquery to initialize the object using the standard jquery plugin syntax:

$("#myDiv").cbagent({userid:userid, moduleid:moduleid});

In the jquery syntax, the userid and moduleid parameters move into the parameters object, which becomes the only argument to cbagent().

Listening to events

You can also register one or more event handlers to react to events in your module. Event handlers should be attached to your containing div ('myDiv' in this case), and not the module instance.

One important event is "moduleLoaded", which fires when enough resources have been loaded to begin showing your module. The event fires immediately after the contents of the div become visible.

<script>
   document.getElementById("myDiv").addEventListener("moduleLoaded", function() {
      console.log("module loaded and visible");
    });
</script>

Here is the equivalent jquery syntax:

$('#myDiv').on("moduleLoaded", function() {
    console.log("module loaded and visible");
});

API Common to all modules


Parameters

fadeIf true, the module will fade to visible right after the moduleLoaded event. Defaults to true.
preloadIf true, the module will attempt to preload resources for faster operation. Defaults to true.

Methods

width()Returns the width, in pixels, of the module, as authored.
height()Returns the height, in pixels, of the module, as authored.
cleanup()You can clear the containing div or replace it with other content at any time. However it is best to call cleanup() on the instance before doing so. This gives the module a chance to stop playing any audio and release any resources. You do not need to invoke cleanup() if your entire page is being replaced - only do so in the case where the contents of the div will be replaced while the page remains visible.

Events

moduleLoadedDispatched by all modules as soon as all critical media has loaded and the module has just become visible. You can immediately turn around and hide it at this point if you like, and your module won't even be briefly visible.

API specific to Agent Module


Parameters

playShieldIndicates whether the module should begin with the play shield. This parameter defaults to true if the module has an auto-play message and if the audio context is locked for the web page. Several browsers, including all mobile browsers, require a click in order to begin playing audio, and the play shield provides a consistent visual reminder on how to start the experience, while also serving as the click that unlocks audio.

Methods

play(message) If the Agent is idle, begin playing the given message. If it is already playing a message, then add it to the message queue. The Agent will keep playing messages from the queue until the queue becomes empty, or until the stop() API is called. Messages are specified by name - this is the same name as you will see in the Character Builder control panel, e.g. "Message 1".
stop() Has no effect if the Agent is idle. If the Agent is playing a message, then it smoothly stops the current message. The queue is immediately emptied on a stop() so that no further messages will play when the smooth stop is complete. To perform a smooth stop, any currently-playing animation (such as a head turn or a gesture) will complete, and then the character will return to the rest position. There is also a ramp-down of the audio. In some cases it can take up to a second for the smooth stop to occur. In order to be notified when the character is truly idle, you can listen to the playComplete event. Alternatively, if you want the character to stop what it is doing and play a different message, you can invoke stop() followed by a new play(). In this case, the stop() immediately clears the queue() and begins the smooth stop. When the stop is complete, the queued message begins to play.
dynamicPlay(object)

This API is turned off by default - please see the faqs page for more information. This API works just like play(), except that the details are passed in using a parameter object. The fields of the object mimic the controls available in the control panel.

doIf specified, the given animation is played along with any audio. The values for this field are the same as the animation name shown in the control panel, but with spaces turned to dashes and all lower-case. For example, to play the animation "Look Up Right" you would use an object {do:"look-up-right"}.
sayIf specified, this forms the text to be spoke using Text-to-Speech. The text is always spoken in the character's voice, as assigned in the control panel's Appearance tab under the Character parameters. A 255 character limit applies to the say field, however multiple playDynamic() calls can be invoked to queue up a longer piece of text, usually one sentence at a time.

Example:

myAgent.playDynamic(do:"look-up-right", "say":"Let's take a look over here.");
playing()Returns true if the Agent is currently playing a message using play() or dynamicPlay(), or false if it is idle.

Events

playCompleteDispatched as soon as the play() or dynamicPlay() is complete, any play queue is empty, and the character has returned to the idle position.

API specific to Slideshow and SoftSkills modules


Parameters

playingIndicates whether the module should begin in the "playing" state. Default to false. This parameter should only be used when you know that audio context has been unlocked for the web page.
slideIf specified, provides the 1-based index of the initial slide. If none specified then the module begins on the first slide.
stepIf specified, provides the 1-based index of the initial step in the initial slide.
roundSimilar to slide but used in SoftSkills modules.

Methods

slide() or slide(n)With no arguments, returns the 1-based slide index for the current slide. With an argument, causes the slide to change instantly, with no fade.
round() or round(n)Similar to slide() but used in SoftSkills modules.
slides()Returns the total number of slides in the module.
rounds()Just like slides() but for SoftSkills modules.
step() or step(n)With no arguments, returns the 1-based step index for the current slide. With an argument, causes the step to change instantly, with no fade. Most slides have only one step, but some slides, such as Bullet slides, can use multiple steps to build the final visual.
steps()Returns the total number of steps in the current slide.
next()Advances instantly to next step or slide, and stops playing. Equivalent to pressing the Next button on the navigation bar.
previous()Moves back instantly to the previous step or slide, and stops playing. Equivalent to pressing the Previous button on the navigation bar.
first()Moves instantly to the first step of the first slide, and stops playing. Equivalent to pressing the First button on the navigation bar.
playing()Indicates whether the Slideshow is in the Playing state, which also corresponds to the enabled/disabled state of the Stop and Play buttons on the navigation bar.
play()Starts playing - equivalent to pressing the Play button on the navigation bar.
stop()Stops playing - equivalent to pressing the Stop button on the navigation bar.
enable(button)Overrides the enabled state of a navigation bar button in a Pressed event, such as nextPressed. The argument can be one of "play", "stop", "next", "previous", "first".
disable(button)Overrides the enabled state of a navigation bar button. The argument can be one of "play", "stop", "next", "previous", "first".

Events

slideChangedIndicates that the slide has changed, either under the user's control via the navigation bar, or via the agent's control. Use the slide() method to determine the new slide number.
stepChangedIndicates that the step has changed, either under the user's control via the navigation bar, or via the agent's control. Use the step() method to determine the new step number.
playingChangedIndicates that the "playing" state, as indicated by playing() has changed.
playPressedIndicates that the Play button has been pressed on the navigation bar.
stopPressedIndicates that the Stop button has been pressed on the navigation bar.
nextPressedIndicates that the Next button has been pressed on the navigation bar.
previousPressedIndicates that the Previous button has been pressed on the navigation bar.
firstPressedIndicates that the First button has been pressed on the navigation bar.





Copyright © 2019 Media Semantics, Inc. All rights reserved.
Comments? Write webmaster@mediasemantics.com.
See our privacy policy.