KDP uiConf definitions and usage

This guide is intended for:

• KDP version 2.5.
• api_v3 (aka partner services 3).

Background

uiConf - User Interface Configuration file
The uiConf is a general name for xml files through which it is possible to customize the KDP for a specific need, layout and design. The uiConf affects three types of features:

• Layout - entirely defined by the uiConf files and is responsible for placing objects on stage (e.g. location of the play button).
• Functionality - partially defined by the uiCong files and partially hard-coded into the KDP widget and its modules.
• Look & Feel - defined in a compiled swf skin file that is linked on the uiConf file.

uiConf ingestion - How to create a modified KDP and use it ?

A custom KDP uiConf can be created in three main ways -

• Using the Application Studio inside the KMC.
• Creating a uiConf xml file locally and uploading it to the Kaltura Server using the APIs.
• Utilizing Kaltura's professional services and ordering a custom KDP design - Contact us.

To use a custom uiConf one must create his own version of a uiConf xml file and then use the public Kaltura API to upload the new uiConf and assign a widget id to be used as the new KDP instance identifier.
When embedding the KDP, specify the created widget id on the src attribute inside the <object> tag.

APIs used

• session.start - to create a new session to work with the Kaltura API.
• uiConf.add - to upload the new uiConf xml and create a uiConf object on the server that later can be used.
• widget.add - to generate a widget representation of the uiConf.

Creating a new uiConf using the API

To create your own KDP widget with a customized uiConf XML follow these steps -

• Use the following set of definitions and rules (described in this document) to create your own uiConf.
• It is highly suggested to download an existing uiConf to use as a base for your work and extend or modify it.
• Call the following API calls in the following order -
  
  • session.start - pass this API call with your partner id, user id and admin secret, and specify this is an ADMIN type KS.
  • uiConf.add - this will create a new uiConf in the system, this uiConf id will be used when requesting the KDP from the Kaltura Server.
  • widget.add - this API is not mandatory, but is good practice. It will take your newly created uiConf id as a parameter and create a dedicated widget id to be used when requesting a KDP instance from the Kaltura Server.
• Embed your KDP using the newly created widget id:
  
  <!--// replace "your_widget_id" with the widget id created by the widget.add api call -->
  <object src="http://www.kaltura.com/kwidget/wid/your_widget_id" ... >
  ...
  </object>

The uiConf XML

Parts of the KDP uiConf were inspired by MXML of Adobe Flex, however KDP uiConf presents various modifications and changes to the standard to comply for the KDP needs as a dynamic player application.

The KDP uiConf is defined according to the following rules:

1. The <layouts> Tag - The root element in every KDP uiConf XML.
   
   
   • Every uiConf file must be wrapped inside a <layouts> tag.
   • This tag has no attributes.
2. The <layout> Tag - Defines a KDP interface, each <layout> tag defines a layout for a KDP instance.
   
   • Every uiConf xml must contain a single <layout> tag.
   • The use of multiple <layout> tags is DEPRECATED and should be avoided since KDP version 2.0.
   • The <layout> Tag has two attributes -
     
     • id – It is recommended that every component will have a defined id.
       The id attribute should be uniquely defined for each of the uiConf components.
     • skinPath – relative path to the skin file (Flex skin and style - compiled swf that contains style and skin definitions).
3. Other Tags - All other tags can appear multiple times within the xml hierarchy.
4. There are two types of element tags which make up the application layout:
   
   • Containers
   • Modules and Components
5. Following are common attributes that all components (aka controllers) and modules hold:
   
   • width - in pixels (width=100) or percentages (width=100%)
   • height - in pixels (height=100) or percentages (height=100%)
   • x - in pixels. This attribute will be ignored in case of an HBox or VBox.
   • y - in pixels. This attribute will be ignored in case of an HBox or VBox.
   • maxWidth - in pixels, defines the maximum width that can be applied to the component.
   • maxHeight - in pixels, defines the maximum height that can be applied to the component.
   • minWidth - in pixels, defines the minimum width that can be applied to the component.
   • minHeight - in pixels, defines the minimum height that can be applied to the component.
   • id - unique identifier of the component, this can be any alpha-numeric string and must always start with a letter.
   • k_hide_in_fullscreen - Boolean(true/false), determine whether or not to hide this component on FullScreen mode.
   • styleName - the class name of the style that should be applied to the component, a matched class should be defined on the loaded compiled CSS swf.
   • visible – Boolean(true/false)controls the item visibility.
   • includeInLayout - detach the item from its container for absolute positioning.
6. Containers - These elements define the various containers in the layout.
   
   • The <Canvas> tag - Provides a layer on which other element can be placed in an absolute positioning.
     
     • All elements placed within a canvas, default to top left corner (x=0, y=0), unless their position is specifically defined by setting x and y attributes.
     • The canvas container is suggested for creating layers that are stacked on top of each other (like the effect of z-index in HTML's CSS, however, in the KDP uiConf the z-index is defined solely by the element's place in the code - from top down - so that the top most element has the lowest 'z-index').
   • The <HBox> tag - All elements placed within it are stacked horizontally.
     
     • All elements placed within it which exceed the boundaries of the HBox (defined by width and height attributes) are not visible (a la overflow:hidden).
     • All items placed within an HBox have a 6px gap between them. The gap value can be changed using the horizontalGap property of the attached class style in the compiled css swf (attached in the skin file pointed to from the skinPath attribute of the <layout> tag).
   • The <VBox> tag - All elements placed within it are stacked vertically.
     
     • All elements placed within it which exceed the boundaries of the VBox (defined by width and height attributes) are not visible (a la overflow:hidden).
     • All items placed within a VBox have a 6px gap between them. The gap value can be changed using the verticalGap property of the attached class style in the compiled css swf (attached in the skin file pointed to from the skinPath attribute of the <layout> tag).
   • The <Tile> tag - Elements placed within it are stacked horizontally until they reach the Tile width and then a new "row" begins.
     
     • All "cells" will have the height of the tallest cell and width of the widest cell.
     • The Tile container is suggested for displaying rows or elements which are all of the same size.
     • Gap between "rows" and "columns" defaults to 6px and can be changed using the verticalGap and horizontalGap properties of the Tile from within of the attached stylsheet.
     • Items placed within it which exceed the height of the Tile (as defined by it height and width attributes or styles) are not visible.
   • The <Button> tag - A generic button component. The following attributes are available:
     
     • Command - used to attach a certain behavior to the button. The following actions are available:
       
       • play – Play the video
       • ffwx2 – Play the video at 2x regular speed
       • ffwx4 – Play the video at 4x regular speed
       • ffwx8 – Play the video at 8x regular speed
       • download – download the video.
         
         • Will not be visible if no file is available for download.
         • Does not support Video Mixes - please contact Professional Services if you require Video Mix downloads.
       • stop – Stop playing the video.
       • replay – Play the video from the beginning.
       • fullScreen – Switch the KDP instance to full screen mode.
       • createThumbnail – Create an opening thumbnail for this video based on the current frame showing.
       • closePopup – Close modal window opened through k_click attribute.
       • gigyaButton – Displays "share" area/ layer.
     • unMute – Cancel the mute setting of the volume.
     • Label – Text that appears on button.
     • Tooltip – Tooltip text that appears when is moused-over.
     • labelPlacement – the positioning of the icon relative to the label
     • k_click – in case there is no command attached to the button it can get one of 3 other actions, see Adding k_click actions
   • The <Image> tag - used to load an image or interactive SWF.
     
     • source - the URL to the image/swf to load.
   • The <Label> tag - Line of text.
     
     • text – The text to appear. The text attribute is usually binded to some data, for information about binding see Dynamic Data section.
   • The <List> tag - A wrapper to present a list of items with a scroll bar that appears automatically as needed. (In the event that the total height of all the items exceeds the height of the List, as defined in its height attribute or style).
     The following attributes are available:
     • dataProvider – A Binding to the source of the data that appears in the list.
     • k_item_renderer_id – The id of the <screen> tag-set that contains the structure for each item in the list.
   • The <Scrubber> tag - A slider used to seek (navigate) the played video.
   • The <Spacer> tag - A whitespace component used to reserve empty spaces.
   • The <Module> tag -
     
     • A module is a compiled swf that provides additional functionality.
     • All <modules> must have the k_path that points to path of this swf.
     • There are several pre-defined modules, that have unique names:
     • <k_player> - required for KDP to display videos(!)
     • The module tag is different from other tags in that its tag can be anything you want, as long as it is not the same as any other tag.
     • It is strongly recommended to follow the naming conventions of every module.
   • The <screens> tag - The screens element is a container that holds one or more uiConf XML elements to describe a visual screen. The logic of this screen is similar to the UiConf logic. The top element of a screen must be a container. Each screen must have a unique "id" attribute so it could be referenced.
7. Using Dynamic Data -
   
   • Bindings are a method of attaching dynamic data to attribute values.
   • This can be as visible text such as in a <Label> used to define a title, or to set a physical attribute such as width.
   • If the source of the bound data is changed, the changed data is reflected where you used the binding.
   • Limitations:
     
     • Bindings can only refer to a property of the KDP object. You cannot use logic or mathematical operators.
   • In order to use Bindings, the value part of the attribute's name=value pair must be wrapped in curly brackets. Examples:
     
     • <Image source="{object.property}">
     • <Label text="{object.object.property}">
     • <Button label=" prefix: {object.object.property}">
8. Adding k_click actions -
   
   • A button can get a k_click attribute and perform one of 3 actions
   • jsCall – call to an external JS function:
     
     • k_click="jsCall('gotoEditorWindow',myKplayer.kalturaEntry.entryId);pauseMedia()"
       The example calls a JS function on the HTML page called "gotoEditorWindow" and will pass it the entryId taken from the myKplayer (the name we always give to the player module of the KDP) module. In addition it will also pause the video.
     • The KDP can also inject JS code to the page. This is done by writing some JS code within the uiConf xml file. In this case the player will use eval to inject the page the function and will call it. This code will be written in a special XML element in the uiConf, and the functionName will actually be the name of the matching JSBlock.
       
       <Button ... k_click="jsCall('alertEntry')">
       ...
        <javaScript>
               <jsBlock id="alertEntry" >
                       function alertEntry (entryId){
                               alert(entryId);
                       }
               </jsBlock>
        </javaScript>
   • popup – points to a module id from the popup XML section:
     
     <Button ... k_click="popup('report')">
     ...
     <popups>
         <module height="100%" id="report" k_path="popups/Report.swf"
        width="100%" />
         <module height="100%" id="credits"
        k_path="credits/CreditsWindow.swf" width="100%" />
     </popups>
   • navigate – open external URL:
     
     k_click="navigate('http://www.athletixnation.com')"
9. Date formatting -
   
   • There is a special function that formats a date through a uiConf
     <label text="updated:{formatDate(updated, 'DD/MM/YYY')}" />
10. Open attribute policy -
    
    • If a module gets any attribute, and the module has a setter for this attribute or a public property it will get the value of it when it loads, before the registerManager and init. In this way a module can get any property value from the uiConf as a string.
      <Module someAttribute="4"... />
11. Playlist & Itemrenderer -
12. The uiConf can define a list that will get a playlist special module as a dataProvider and each cell in the list can be custom configured in the screen section.

Playlist

The playlist is a KDP component that provides a list view of multiple media entries and the functionality to play each media individually or all in a sequence.
The playlist is composed of two main components:

• List Component: a KDP component that is binded to data provider of entries and display it in a list base container, each item in a single cell is an 'itemRenderer'.
• Playlist API: a non visual module that parse and manage one or more playlists. This module is the data provider object for the list.

The list component and the playlist API must be both defined in the uiConf XML.

The list XML attribute "dataProvider" refers to the playlist API. In addition, the list refers to an itemRenderer id that defines the structure of the list's item renderer. This XML is defined in the "screens" section.
Following is an example of implementing the list, the playlist and the itemRenderer screen:

There are 2 additional components that complete the playlist "package":

• Playlist scrolling tabs module: a module that shows and switches between playlists if there is more than one.
  <PlaylistTabs id="plTabs" styleName="scrollingTabsStyle" k_path="playlist/view/modules/PlaylistScrollingTabs.swf" height="100%" width="100%" scrollJump="120" buttonWidth="20" />
• Next-prev module: 2 buttons that command the playlist to play the next entry or the previous one, if available. This module holds both buttons. Usually we place this module in the controller area
  <PrevButton id="plPrevButton" direction="prev" k_path="playlist/view/modules/PlaylistNextPrevButton.swf" />

A special feature of this screen XML is the styleName.

The styleName is a regular CSS class, however it also defines the style of the itemRenderer.

This CSS can hold the "irScreenStyleName" attribute that holds the CSS class to be passed to the itemRenderer container. There is a special attribute in this class called "bgButtonStyleName". That is another reference to a CSS class that will describe a button that will appear as the background of the itemRenderer. Using this structure it is possible to define states and transitions for the itemRenderer as a flex skin button (up, over, selected, etc.)
The following example describes the CSS of a playlist itemRenderer -

Further steps

Download the Best practices PHP integration - KDP Sample Kit.
Modify the <xml id="xmldata"> page element to play around with the KDP uiConf locally.