Javascript API

Requirements

The user's browser must support the HTML5 postMessage feature. Most modern browsers support postMessage, though Internet Explorer 7 does not.
Embedded widgets must have a viewport that is large enough to display the components selected.
Any web page that uses the API must also implement the following JavaScript function:
- onYouglishAPIReady – The API will call this function when the page has finished downloading the JavaScript for the widget API, which enables you to then use the API on your page. Thus, this function might create the widget objects that you want to display when the page loads.

Getting started

The HTML page below creates an embedded widget that searches for English tracks containing 'courage', and plays each track 3 times before moving to the next one.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The widget will replace this <div> tag. -->
    <div id="widget-1"></div>


    <script>
      // 2. This code loads the widget API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://youglish.com/public/emb/widget.js";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates a widget after the API code downloads.
      var widget;
      function onYouglishAPIReady(){
        widget = new YG.Widget("widget-1", {
          width: 640,
          components:9, //search box & caption 
          events: {
            'onFetchDone': onFetchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.fetch("courage","english");
      }

     
      var views = 0, curTrack = 0, totalTracks = 0;
    
      // 5. The API will call this method when the search is done
      function onFetchDone(event){
        if (event.totalResult === 0)   alert("No result found");
        else totalTracks = event.totalResult; 
      }
         
      // 6. The API will call this method when switching to a new video. 
      function onVideoChange(event){
        curTrack = event.trackNumber;
        views = 0;
      }
         
      // 7. The API will call this method when a caption is consumed. 
      function onCaptionConsumed(event){
        if (++views < 3)
          widget.replay();
        else 
          if (curTrack < totalTracks)  
            widget.next();
      }
    </script>
  </body>
</html>

Loading a YouGlish widget

After the API's JavaScript code loads, the API will call the onYouglishAPIReady function, at which point you can construct a YG.Widget object to insert a widget in your page. The HTML excerpt below shows the onYouglishAPIReady function from the example above:

      var widget;
      function onYouglishAPIReady(){
        widget = new YG.Widget("widget-1", {
          width: 640,
          components:9, //search box & caption 
          events: {
            'onFetchDone': onFetchDone,
            'onVideoChange': onVideoChange,
            'onCaptionConsumed': onCaptionConsumed
          }          
        });
        // 4. process the query
        widget.fetch("courage","english");
      }

The constructor for the widget specifies the following parameters:

The first parameter specifies either the DOM element or the id of the HTML element where the API will insert the tag containing the widget.
The second parameter is an object that specifies widget options. The object contains the following properties:
- width (number) – The width of the video widget.
- components (number) – The components selected (see them all here).
- events (object) - The object's properties identify the events that the API fires and the functions that the API will call when those events occur.

Click here to see all the properties that can be used to customize the widget.

Name

Type

Meaning

Values

width

number

width of the widget in pixels.

Default: expand to all its container width.

height

number

height of the widget in pixels.

Default: expand to its actual content height.

autoStart

number

loaded video will start playing automatically.

1 to enable - 0 to disable.

Default: 1

components

number

sum of all selected components ID.

ex: widget with search, title and speed support will have a components value of 1+4+16 = 21

Component	ID
Search box	`1`
Accent panel	`2`
Title	`4`
Caption	`8`
Speed controls	`16`
Toggle UI (deprecated)	`32`
Control Buttons	`64`
Dictionary support	`128`
Near by panel	`256`
Phonetic panel	`512`
Draggable	`1024`
Minimizable	`2048`
Closable	`4096`
All Captions	`8192`
Toggle light	`16384`
Toggle tumbnails	`32768`

Default: 255

backgroundColor

string

widget background color.