KDP

From Kaltura Wiki

[edit] Kaltura Dynamic Player (KDP)

The Kaltura Dynamic Player (aka KDP) is a highly flexible media player allowing any developer to create his own skinned version which may include different sets of components.
As with the Kaltura Contributor Wizard, the KDP enables easy integration of 3rd party Flash components.

In order to embed a KDP on a web page a developer should first create a widget (or use one of the available widgets) which describes the settings of the required player.
There are two types of widgets:

1. Gallery mode – The widget will render a KDP that can show different media clips.The media clips can be changed using a simple javascript call to the html flash object.
2. Embed mode – The widget is bounded to a specific media (e.g. image, video, remix).

This is usually the case when an end user shares (via embed code) the media on another site (e.g. MySpace, Facebook).

The KDP can be configured using an xml configuration file.
The configuration file defines the graphical layout and functionality of the different parts of the player.
Different instances of the KDP may use different components such as the accreditation component, rating component, different progress bars.

Extra data may be passed to the KDP through flashvars in order to propagate it to all of the widgets embedded from the current instance (e.g. a link to the original page containing the widget).

[edit] Customizing the KDP

The KDP configuration file is an XML file that may contain several layout options. Each layout is described under the layout node:

<layouts>
	<layout layoutId="Large"...>
	.
	.
	</layout>
 
	<layout layoutId="Small"...>
	.
	.
	</layout>
</layouts>

The layout encapsulates three different customization aspects:

1. Graphical layout and selection of components
2. References to an external CSS file
3. Declaring and binding functionality to the different components

The sample xml we’ll use in this document is used for a wiki player layout.

[edit] Layout & Components

The layout definition is similar to a standard flex mxml layout. All of the non-standard attributes are prefixed by “k_”.

Here’s an excerpt from the layout XML:

<?xml version="1.0" encoding="UTF-8"?>
<!-- A uiConf file can hold more than one layout. We can switch them by the 'layoutId' attribute and a 'layoutId' flashvar. the 1st layout is the default one -->
<layouts>
	<!-- A layout must have a skinPath that points the position of the skin file. A skin file is a flash css file compiled into a SWF-->
	<layout skinPath="/content/uiconf/kaltura/wiki.swf" layoutId="wiki">
		<!-- The top level container of the KDP. This container will hold all containers and all components. It is set to 100% width & height so it will be stretched in fullscreen
		mode. This container will be stretched on the space the HTML swf tag  -->
		<VBox width="100%" height="100%" styleName="topLevelVbox" >
 
		<!-- this topBar an area that has 2 dynamic labels and one 'start new video' button in case we don't need 
		this topBar - we can just delete this element-->
 
			<HBox id="topBar" width="100%" height="46" styleName="topBar" >
				<VBox id="topBarTitles" width="100%" height="46" styleName="topBarTitles" >
					<!--dynamic label are expressions within {} that being replaced in runtime with data from the KDP. It can get flashvars, show data, and
					properties of other components.  The KDP will try to take the left property, If it can't find it, it will move on to the next one
					until it finds one that returns a value. The last string on the left side is the default, in our case - an empty string  -->
					<Label id="movieName" styleName="vtitle" height="22" width="100%" label="{kdpModel.Title,myKplayer.kalturaShow.kshowName,myKplayer.kalturaEntry.entryName,''}"/>
					<Label id="movieDescription" styleName="vdescript" height="15" width="100%" label="{kdpModel.Description,myKplayer.kalturaShow.description,''}"/>
				</VBox>
				<VBox id="topBarButtons" width="100" height="40">
					<!-- the k_click can get 3 commands: jsInject - inject a JS function call to the page and calling it (see documentation), popup - pop a  modal window to the user and navigate - navigate to a web page with or without dynamic abilities   -->
					<LinkButton id="startNewVideo" label="Start New Video" width="100" height="15" styleName="transparentLinkButton" k_click="jsInject:gotoContribWizard" />
				</VBox>
			</HBox>
			<!-- this container holds the player display object. It should be 100% W/H so it will be placed in the remaining place that the other 
			containers are not using. See all other containers are 100% width BUT fixed pixels size-->		
		    <Canvas id="PlayerHolder" styleName="PlayerBackground" width="100%" height="100%" >
				<!--The KplayerModule. This is the only mandatory Module in a KDP. Its maxHeight/maxWidth is its maximum dimensions in fullscreen mode. 
				The k_path is the path to the module-->
 
				<KplayerModule id="myKplayer" styleName="centered" 	k_path="kplayer/KplayerModule.swf" width="100%" height="100%" maxWidth="600" maxHeight="450"/>
				<!-- Additional layers in the player holder container (like Watermark, Commercials, Play/pause center-player button) must get the same width/Height/maxWidth/maxHeight as the KplayerModule-->
		      	<playerPlayBtn id="playerPlayBtn" styleName="centered"  width="100%" height="100%" maxWidth="600" maxHeight="450"  k_path="playerPlayPauseBtn/PlayerPlayPauseButton.swf" />
		      	<waterMark id="kalturaWaterMark" styleName="centered"  width="100%" height="100%" maxWidth="600" maxHeight="450"  k_path="watermarks/KalturaWaterMark.swf" />
			</Canvas>
			<!--this is the controller's container below the player area -->
			<HBox styleName="controllerBox" height="20" width="100%">
				<VBox>
					<!--play/pause Button is not a module it's id must be 'play'-->
			      	<Button	 id="play" styleName="play" width="20" height="20" />
			      	<Spacer height="1"/>
		    	</VBox>
		      	<Spacer width="2"/>
				<VBox width="100%" height="19">
					<!--Scrubber is not a module. Its id must be 'scrubber'-->
					<Scrubber id="scrubber" styleName="scrubber" width="100%" height="16"/>
					<Spacer height="3"/>
				</VBox>
				<!--There is more than one timers text display this one shows the movie time and the remaining time-->
		      	<TimerCountdown  id="timer" height="19" width="73" k_path="timertext/TimerAndTotalTime.swf" />
		      	<Spacer width="4"/>
				<!-- volume bar -->
		      	<VolumeModule id="volume" width="18" height="18" k_path="VolumeBars/VolumeBarA.swf" />
				<!-- fullscreen button must be id  'fullscreen' -->
				<Button id="fullScreen" width="19" height="19" styleName="fs" />
		      	<Spacer width="2"/>
			</HBox>
			<HBox styleName="bottomLinks"  height="40" width="100%">
 
				<LinkButton id="addToFavorit" width="25%" styleName="blueButton" label="Add to Favorites"  height="40" k_click="navigate:http://www.someserver.org/?action={kdpModel.pd_addContent}" />
				<!--just some link buttons navigating to a fixed or dynamic URL. The curly brackets content is being replaced with the data the KDP holds-->
				<LinkButton id="addContent" width="25%" styleName="blueButton" label="Add Content" height="40" k_click="navigate:http://www.someserver.org/?action={kdpModel.pd_addContent}"  />
				<LinkButton id="talkBack" width="25%" styleName="blueButton" label="Talk Back"  height="40" k_click="navigate:http://www.someserver.org/?action={kdpModel.pd_talkback}" />
				<LinkButton id="remix" width="25%" styleName="redButton" label="Remix"  height="40" k_click="navigate:http://www.someserver.org/?action={kdpModel.pd_remix}&show={kdpModel.kshowId}" />
			</HBox>
 
			<HBox styleName="poweredBox" width="100%" height="18">
		    	<poweredBy id="poweredBy" k_path="poweredby/PoweredBy.swf" styleName="poweredBy" width="120" height="14" />
				<!--this button calls a popup module from the popups section of the UI-->
		    	<Button id="credits" styleName="creditsButton" width="120" height="14" k_click="popup:creditsWindow" />
		    </HBox>
    	</VBox>
	 	<popups>
			<!-- a popup module is opened in a modal window-->
			<credits id="creditsWindow" k_path="credits/CreditsWindow.swf" width="400" height="300"/>
	 	</popups>
	 	<javaScript>
				<!--  a jsBlock is a js code that buttons/linkButtons can run. The functionName is the function the KDP will build with the 'params' parameters inserted to. We can also call a 
				function on the page -->
	 	   		<jsBlock id="gotoContribWizard" functionName="gotoContribWizard" params="kshowId,objectId" >
					<![CDATA[
						function gotoContribWizard (kshowId,objectId)
						{
							alert ( "gotoContribWizard (" + kshowId + "," + objectId + ")" );
						};
					]]>
				</jsBlock>
		</javaScript>
	</layout>
</layouts>

the layout node contains two attributes:

1. layoutId - An optional string that is used to select the requested layout. The id is passed through flashvars in order to tell the KDP which layout to render.
2. skinPath - A string URL pointing to a compiled css swf file containing all the styles and graphical elements that are used by this layout.

The components are extending the original flex classes. The supported components are Label, Button, LinkButton, Panel, Canvas, Spacer, and TitleWindow. Each component can have these layout attributes: width height (pixels or percents), label, x, y, maxHeight and maxWidth. The styleName attribute defining the element css class is grabbed from the skin file referenced by the layout node.

Other nodes use external flex modules:

<KplayerModule id="myKplayer" styleName="Kplayer" k_path="kplayer/KplayerModule.swf" width="100%" height="100%" maxWidth="600" maxHeight="450"/>

The KplayerModule tag name is used for readability only; however the k_path attribute suggests the use of an external component, in this case the Kaltura video player. The k_path attribute is the path to the flex module which can also be a full URL for a component residing on another web site. Each component has an id that can be used by other components which need to reference it. Any attribute not listed above must be declared as a property by the external module and will be set once the module is loaded.

[edit] Dynamic Functionality

The dynamic nature of the KDP offers any designer the ability to add buttons, links and labels and for any developer to add his own customized components.

[edit] Dynamic Labels

<Label id="vtitle" styleName="vtitle" height="23" width="100%" label="{kdpModel.Title,myKplayer.kalturaShow.kshowName,''}"/>

Dynamic labels accept expressions instead of plain literal text.
The label content is encapsulated within curly braces.
Tokens separated by a comma are evaluated from left to right.
The first token which is not null is used as the label text.
Dynamic labels are rendered each time a new entry is loaded into the KDP.

In this example the first token is kdpModel.Title.
The kdpModel is the container holding among other values all the flashvars passed to the KDP.
If a flashvar named Title was passed to the KDP it will be shown as the text of this sample label.
The next token myKplayer.kalturaShow.kshowName relates to the KplayerModule that was given the id myKplayer.
Each component may give access to properties it holds to any other component (if the property isn’t found, the next token will be used).
In this case the label will show the name given to the current kshow.
The last token is a string literal, which is an empty string in this sample.
When the KDP is not bounded to a specific entry this is the text that will show on the label before an entry will be inserted to the KDP via javascript code.
The data model exposed by the KplayerModule is detailed at the end of this document.

[edit] Binding clickable actions

<LinkButton id="addToReel" width="150" styleName="addToReel" label="Add to this video" height="22" k_click="jsInject:gotoContribWizard" />

The k_click attribute controls which action should be taken when a user clicks on a component.
The action is defined by a type and a name separated by a colon.
The available types of actions are jsInject and popup.
If a type is not defined, the action is interpreted as one of the KDP external interface commands (such as pauseMedia).
A list of the KDP external interface is provided later in this document, however only commands without parameters may be used as actions.
Multiple actions may be chained using a comma separator (e.g. k_click="jsInject:gotoContribWizard,playMedia").

[edit] JsInject

<LinkButton id="addToReel" width="150" styleName="addToReel" label="Add to this video" height="22" k_click="jsInject:gotoContribWizard" />

The jsInject action injects a javascript code into the page. The javascript code is defined within the layout xml after all of the actual layout definitions.

Simple case of calling a javascript function:

<javaScript>
  <jsBlock id="gotoContribWizard" functionName="gotoCW" params="kshowId,pd_extraData" >
  </jsBlock>
</javaScript>

A more advanced case of defining a javascript function (which is called implicitly)

<jsBlock id="addVideo" functionName="addVideo" params="" >
<![CDATA[
        function addVideo()
       {
          kalturaOpenModalBoxBeginKaltura( "/devwiki/index.php?title=Special:KalturaAjaxCollaborativeVideoInfo&inflow=2" );
       };
]]>
</jsBlock>

Each function is defined within a jsBlock node. The node id is used by the k_click attribute to refer to the right block.
In the first sample, clicking on the button will call a javascript function named gotoCW (already defined on the page) passing two parameters kshowId – the current kshow id and pd_extraData that will be described later in this document.
The parameters are treated as strings and therefore the KDP surround them by quotes.

In the second example a new javascript function named addVideo is injected into the page and called implicitly by the jsBlock.

Javascript blocks accept dynamic parameters as well:

<jsBlock id="foobar" functionName="foobar" params="kshowId,{myKplayer.kalturaShow.kshowName}" >
      <![CDATA[
      function foobar (kshowId,name)
      {
            alert (kshowId + "," + name );
      };
]]>
</jsBlock>

Here the second parameter will be evaluated from the expression enclosed within the curly brackets.

[edit] Popup

<LinkButton id="sharePopUp" height="15" styleName="topLinkButtons" label="Share" k_click="popup:SharePop"  />

The popup action opens another flex component within the KDP area. The popup layout is defined within the layout xml after all of the actual layout definitions.

<popups>
  <SharePop id="SharePop" k_path="popups/SharePopup.swf" width="350" height="350"/> 
</popups>

Each popup is defined using a single node.
The node is a flex component which is loaded dynamically by the KDP.
The component will be loaded only upon request so it doesn’t increase the load time of the base KDP.
A popup is opened in a modal window over the player and it must dispatch a close event (CloseEvent.CLOSE) whenever it has to close.

[edit] KDP Embedded Data

All of the flashvars passed to the KDP are accessible to all of the dynamic components.
Additionally flashvars beginning with the prefix pd_ (partner data) have a special meaning.
Whenever an end user wishes to embed the media played on the KDP on his own site, a new widget id is created on the Kaltura servers.
The new widget contains references to the widget it was embedded from as well as to the root widget from which the embedding process started (e.g. the KDP was embedded on site A; a user embedded the code through a share button on site B.
Another user clicked share on this widget and embedded it on site C). All of the flashvars starting with the prefix pd_ will be stored with the new widget on the Kaltura servers.

A sample use case could be shown through the KDP wiki implementation.
On the original article page where the KDP is embedded, the URL is passed using flashvars within the variable pd_article_url.
When a user shares this widget the pd_article_url is stored within the new widget on the Kaltura servers.
Now when the user embeds this new widget on his site, a simple KDP LinkButton may be programmed to navigate the browser back to the pd_article_url page.
This way the wiki extension developer is able to add a link back to the original wiki page without customizing the KDP code base.
Multiple variables, passing all kinds of data, may be passed this way using flashvars, and these variables will be part of the embedded widgets.

[edit] KDP Utility Functions

The KDP offers a set of utility functions for interacting with the different components. [TBD]

[edit] Events

KplayerModule events – the KplayerModule offers numerous events that any component may listen to. This enables the creation of custom scrubbers, dynamic accreditation components, customized timeline based annotations and much more.

The KplayerModule listens to the following events:

The KplayerModule dispatches the following events

[edit] Data Model

KplayerModule – The KplayerModule exposes properties describing the current playing entry (either a single media clip or a roughcut). kalturaEntry - an object that holds the data of the entry (TBD) kalturaShow - an object that holds the data of the kshow (TBD)

For example the name of the kshow is retrieved from the kalturaShow object by accessing kalturaShow.kshowName.

[edit] KDP External Interface

The KDP exposes an external interface, accessible via javascript.

The following functions are available: insertMedia(kshow_id, entry_id, autoPlay, entryVersion) load a new entry into the KDP. Using entry_id = “-1” will show the kshow roughcut.

pauseMedia() pause the current playing media

stopMedia() stops the current playing media

seekMedia(timeStamp) move the player scrubber to the requested time stamp

playMedia() play the currently select media

In addition to callable functions, the KDP calls several javascript functions in response to events. Each function passes the KDP html object instance as the first parameter.

readyF We can add a JS function on the page that will be called when the KDP is ready to show content. We pass the name of the function through a flashvar called 'readyF'. The function will get a single parameter – the objected of the swf.

emptyF As readyF, the KDP can call a JS function on the page that it is ready but it has no content to show. This enables the JS on the page call the 'insertMedia' only when the KDP is ready. In this case – the name of the JS function should be passed to the KDP as the flashvars 'emptyF'. The function will get a single parameter – the objected of the swf.

finishF When the KDP finished a show – it can notify the JS function on the page that it is done. The name of the function is the flashvar ' finishF'. The function will get a single parameter – the embed tag ID.

[edit] Embedding the KDP

The KDP should not be embedded directly on a page; a widget id is embedded instead.
A widget can be created programmatically using the addwidget API call (or using the share component of the KDP).
The widget is either bound to a specific entry or used as a placeholder for viewing entries selected using the insertMedia javascript function.

The widget contains a ui_conf_id' which points to a layout xml file residing on the Kaltura servers.
Embedding a widget is done using a flash object pointing to: http://www.kaltura.com/index.php/kwidget/wid/widget_id

The widget_id' is the id of the requested widget.

[edit] Security

On the developer web site the flashvars may contain additional parameters such as the partner_id, subp_id, uid and KS that was created on the server.
Whenever a user embeds a widget on an external site a new widget_id is created.
When the newly created widget is embedded on the external site the object tag doesn’t contain the KS in the flashvars, instead the KDP issues a startwidgetsession request to the Kaltura servers using the widget_id.
A KS is then generated using the widget partner_id and an anonymous uid, since once sharing was allowed the newly created widget is regarded as public for viewing purposes.

[edit] Additional Parameters

Additional parameters can be passed to the KDP via flashvars. As described above any parameter prefixed by pd_ will be passed to a newly embedded widget.

Other built-in parameters are: