SDK Widgets
BETA

The Javascript SDK exposes a number of preset widget factories. These factories allow developers to leverage widgets as standalone components, but also provides the ability to compose each together in a few flexible ways. Our full player solution utilizes all of the available widgets together, initializing them internally the same way they are exposed through the top level cin.ui API.

Widget Events

All SDK widgets inherit from an event emitter and each can be subscribed to in a similar fashion. Each widget maintains their events under Widget.events. For example:


    
    // Subscribe to the player icon being clicked
    player.subscribe(player.events.ICON_TOUCHED, (count) => {
        console.log('--icon clicked', count);
    });

At this time the SDK exposes only a limited number of events. However, there are a number of state changes happening within the SDK that can be subscribed to in a flat fashion. To listen in on every change happening internally, the cin namespace exposes a `subscribe` function:



    cin.subscribe(state => {
        console.log('--new state', state);
    });

cin.ui.Player

The Cinematique web player is a truly responsive HTML5 player. The full player experience includes the video player itself, bundled with the user's touch list as well as touch details for each selected touch in that list. The video slides left to expose these inner features. The player can also be used as what we call a lite player. This configuration includes only our standard video player with none of the fixings.


    
    // Cinematique video ID
    const videoId = 412;

    // Initialize our Mobile web player widget with options
    let player = cin.ui.Player('#player', {
        autoplay: true
    });

    // Load the necessary data and recieve notice when the player is ready
    player.load(videoId, () => {
        console.log('Player loaded!', this.getVideo());
    });

cin.ui.Grid

The Grid widget is Cinematique's core touchable technology. This factory provides a configurable grid element that wraps the provided surface element and initializes touch tracking, while also providing our signature touch feedback animations over the plane. It can be configured as a standalone widget over any element or it can be connected with a `videoId`.



    // Initialize a standalone grid
    let grid = cin.ui.Grid()

        // Configure with appropriate video ID
        .configure({
            'videoId': videoId
        })

        // load the data
        .load(() => {
            console.log('--grid data loaded!');
        })

        // Attach it to a DOM selector or node
        .attachTo('#grid')

        // Listen for Grid interactions
        .listen(function(ev) { 
            console.log('--Grid touched', 
                event.currentTime, 
                event.coords, 
                event.matches, 
                event.added);
        });

A Grid can also be connected to an existing player, as well. This is also an example of passing options into the factory constructor:



    let secondaryGrid = cin.ui.Grid({ 
        'player': player 
    }).attachTo('#grid').listen(event => {
        console.log('--touched!', event);
    });

cin.ui.Icon

The Icon widget is the touch counter for a grid, or when standalone and provided a videoId, it can represent total touches a user has for this video. This factory provides a configurable component that can be connected with Grid at anytime. The icon also shows progress on total touches captured within a grid or based on static startCount and maxCount configuration options. An Icon can also be connected with any Player widget and a player can have unlimited icons connected to it on your page.



    // Initialize an icon and set a few skinning options
    let icon = cin.ui.Icon({
            'videoId': 412,
            'skin': {
                background: '#111',
                progress: 'pink', // get crazy!
            }
        })

        // Load the widget
        .load()

        // Lazy attach it to a DOM selector
        .attachTo('#icon');


    // The icon can be used as a standalone widget for a video ID. It can also be 
    // connected with an existing grid so it may inherit touch counts and updates
    icon.connectWith(grid);

cin.ui.TouchList

Touch lists are where Cinematique users save and store their touches for a video. This widget allows for loading that touch list outside of the player. Currently, a touch list cannot be created without a player instance though. In the future we plan to allow all widgets to be initialized in standalone mode, which allows for more creative ways to engage your users with touchable video.



    let list = cin.ui.TouchList('#list', player).load(() => {
        console.log('--touches loaded', this.getTouches());
    });

cin.ui.TouchDetail

The touch detail widget allows for loading a detail of the underlying item that is captured by collecting a touch from the player. Again, in the near future we will be allowing these widgets to be initialized in standalone mode so that they don't have to be directly tied to any other objects. For now, this detail must be connected to a TouchList instance. In most cases this is necessary anyway since you will not have an individual touch ID on hand. It's important to note that a TouchList creates and uses it's own TouchDetail internally.



    let detail = cin.ui.TouchDetail('#detail', list);

    // Open a specific touch
    detail.open(touchId);

    // and close it
    if (detail.isOpen()) {
        detail.close();
    }
    
    // all widgets can be destroyed as well
    detail.destroy();

Next Steps

Authoring Widgets