This integration guide assumes the use of Kaltura components at the following versions:
- Kaltura Partner Service: 3.0 (aka api_v3)
Usage
Web site designers may want to add a Gallery component to their web pages so that end-users can browse within a large set of media files and conveniently select the media they want to see.
Read a more detailed overview of the KGallery widget.
See Demo
Integration Steps
Integration of the KGallery services in your web-site requires the following steps to be followed. Steps 1 and Step 2 may be skipped if you have already integrated your web application with another Kaltura widget.
Please make sure you review these sections as well as the related FAQ before starting your integration project. Spending a moment to read this now may save you hours during your integration project.
- Step 1 - Obtain Partner Identifiers.
- Step 2 - Prepare your web application environment.
- Step 3 - Edit your web application scripts to integrate with KGallery Services.
Edit your web page to integrate with Kaltura Gallery Services
Integrating KGallery services into your web site requires that you put the following additions into your web page:
- Include of External Scripts
- Definition of constants and variables
- Construction of Kaltura objects for session initiation
- Media entries list retrieval
- Population of media entries within Gallery layout
- Java Script Implementation for showing selected media
Full Example Script
The following example of PHP/JavaScript script demonstrates the integration of the KGallery services into a PHP based web application. To run this script, please make sure you set your partner identifiers at the KALTURA_PARTNER_ID and KALTURA_PARTNER_SERVICE_SECRET constants.
Look for detailed information on this example in the following sections.
Download Simple KGallery script.
Include of External Scripts
<head>
</head>
<body>
<!--include external scripts-->
<?php
require_once("kaltura_client_v3/KalturaClient.php");
In the example lines above, external script required for the KGallery Services is included.
The KalturaClient.php scripts are part of the PHP Kaltura API Client Library being included to enable the use of Kaltura objects.
This script should be available from within the web application after proper preparation for integration.
Define constants and variables
In the example lines above, the PHP code defines 2 constants and one variable, later to be used within implementation.
| Parameter | Type | Default | Description |
|---|---|---|---|
| KALTURA_PARTNER_ID | Numeric | N/A | Here you should put your Partner ID. Please refer to the How to Obtain Partner Identifiers page for reference. |
| KALTURA_PARTNER_SERVICE_SECRET | String | N/A | Here you should put your Web Service Secret. Please refer to the How to Obtain Partner Identifiers page for reference. This Secret string is used within Kaltura objects to create a secured session ID, preventing hacking and abuse attempts aiming to damage Partner/end-user’s content. |
| partnerUserID | String | N/A | This is an example of a variable that could be used for content filtering. This variable may be used to populate the relevant content within the Gallery layout. It makes sense to apply this specific identifier as filter criteria only if it was assigned to media content upon media uploading. For the benefit of a generic example script, this parameter was not actually assigned as a filter, but was only defined and set for example purposes. |
Construct Kaltura objects for session initiation
$client = new KalturaClient($config);
$ks = $client->session->start(KALTURA_PARTNER_WEB_SERVICE_SECRET, $partnerUserID, KalturaSessionType::USER);
$client->setKs($ks); // set the session in the client
In the example lines above, the PHP code constructs the relevant Kaltura objects, used for session initiation. The objects are constructed as defined and implemented at the relevant Kaltura API Client Library. A unique session (KS) is then generated and set.
Media entries list retrieval
$filter->statusEqual = KalturaEntryStatus::READY;
$filter->mediaTypeEqual = KalturaMediaType::VIDEO ;
$pager = new KalturaFilterPager();
$pager->pageSize = 5;
$pager->pageIndex = 1;
$list = $client->media->listAction($filter,$pager); // list all of the media items in the partner
?>
In the example lines above, the PHP code constructs a filter object and a pager object for controlling the selection of media elements to be displayed within the gallery layout. These objects are passed as arguments to the Kaltura media:list service for setting the proper selection criteria.
The KalturaMediaEntryFilter object allows specific filters to apply on media selection and order. The filter parameters set in the example are only a few of the possible sets of filter parameters. A full list of filter parameters is available at the KalturaMediaEntryFilter page within the Kaltura API documentation site.
The KalturaFilterPager object enables paging management while retrieving media elements. This is an optional mechanism which may be in use when gallery design includes pages layout. When no pager object is passed as an argument to the Kaltura media:list service, the returned list will include all media items (according to filter object only). Look for more information on this object in the KalturaFilterPager page within the Kaltura API documentation site.
The Kaltura media:list service, returns a KalturaMediaListResponse Object. This is an array of KalturaMediaEntry objects, holding information on the entries to be presented within the Gallery implementation. The common parameters to be used within a gallery implementation are: thumbnailUrl, mediaType, id, name and description. Look for more information on these parameters at the KalturaMediaEntry page within the Kaltura API documentation site
Population of media entries within the Gallery layout
<table>
<?php foreach ($list->objects as $mediaEntry): ?>
<?php
$name = $mediaEntry->name; // get the entry name
$id = $mediaEntry->id;
$thumbUrl = $mediaEntry->thumbnailUrl; // get the entry thumbnail URL
$description = $mediaEntry->description;
?>
<td>
<ul style="list-style:none;">
<li style="width:120px; height:90px;"><a href="javascript:LoadMedia('<?php echo $id; ?>')">
<img border="0" src="<?php echo $thumbUrl; ?>" >
</a></li>
<li style="width:120px; height:40px;"><?php echo $name; ?></li>
</ul>
</td>
<?php endforeach; ?>
</table>
</div>
In the example lines above KalturaGallary div is set to contain a simple html table based layout Gallery. The PHP script loops over the returned list of media entries and for each entry it lays out its thumbnail and its name. Clicking on a gallery thumbnail image will activate media loading for the selected entry. In this example media loading is triggered using selected entryId as a unique identifier.
Java Script Implementation for showing selected media
function LoadMedia(entryId) {
alert (entryId);
// show media implementation should go here.
}
</script>
</body>
</html>
In the example lines above a Java Script method is defined, receiving media’s entryId as an argument. This is where the implementation of media loading should be set. An example for such an implementation could be loading the selected media to be played by the Kaltura Dynamic Player widget.
In case of using media components which are not based on Kaltura technology, a content url could be constructed out of entryId and Partner’s identifiers according to the following format:
http://cdn.kaltura.com/p/{partner_id}/sp/{subpartner_id}/flvclipper/{entryid}
Integrating Kaltura Gallery Services into a scrollable gallery layout
Several open source projects implement built-in technology for scrollable media galleries. Integrating Kaltura Gallery Services into such a layout is easy and following the same logic described ain this integration guide. The following example demonstrates such an integration with jQuery scrollable tools. More information on these tools is available in the jQuery Scrollable page. To run this script, please make sure you set your partner identifiers at the KALTURA_PARTNER_ID and KALTURA_PARTNER_SERVICE_SECRET constants.
Download Scrollable based KGallery script.
For further problem solving and details please refer to the Frequently Asked Questions on the KGallery Integration.
| Attachment | Size |
|---|---|
| kgalleryScrollable.tgz | 15.51 KB |
| kgallery.tgz | 14.77 KB |
Comments
Great tutorial and amazing script... with one small error!
First of all... Thanks so much for this tut/script! I'm definitely going to read every little piece of documentation in the next days but for now it just saved me a LOT of time!
I would like to bring to your attention a little error in the downloadable package though (http://www.kaltura.org/sites/default/files/kgallery.tgz)
In line 11 of Kgallery.php you define the constant KALTURA_PARTNER_SERVICE_SECRET but when constructing the object to initiate the session you call the constant "KALTURA_PARTNER_WEB_SERVICE_SECRET" instead of the previously defined KALTURA_PARTNER_SERVICE_SECRET.
They are so similar that I didn't catch it at first time but just after a second look. It might make this great script non-functional for people without any experience with PHP who wouldn't understand the well written explanation of the code in this page.
Other than that... it works perfectly!
Thanks again.
Thanks Emerson, I just
Thanks Emerson,
I just updated the script with the fix.
Uncaught exception 'KalturaException' with message 'Error while
error while using the gallary scritp..
I have written..
//define constants
define("KALTURA_PARTNER_ID", 1);
define("KALTURA_PARTNER_SERVICE_SECRET", "f270eeaa493d41f8c0ca89372038b7a0");
//define session variables
$partnerUserID = '31';
## I thing the problem is with $partnerUserID
New Player KDP 3.3.7
Hi
In the new Player hostet on OEM Version the load Media function dont work anymore?
Message:
$("#mykdp").get(0).insertMedia is not a function
[Break on this error] $('#mykdp').get(0).insertMedia("-1",entryId,'true');
My Code:
<script type="text/javascript">
if (swfobject.hasFlashPlayerVersion("9.0.0")) {
var fn = function() {
var att = { data:"http://medianac.nacamar.de/index.php/kwidget/cache_st/1277397923/wid/_119/uiconf_id/1000135/",
width:"<?php echo($player_width); ?>",
height:"<?php echo($player_height); ?>",
id:"mykdp",
name:"mykdp" };
var par = { flashvars:"&entryId=<?= $entryId; ?>" +
"&autoPlay=<?php echo($autoPlay); ?>",
allowScriptAccess:"always",
allowfullscreen:"true",
bgcolor:"<?php echo($backgroundColor); ?>"
};
var id = "content";
var myObject = swfobject.createSWF(att, par, id);
};
swfobject.addDomLoadEvent(fn);
}
</script>
<div id="container" style="text-align:center;float:left;">
<div id="content">KDP Should be loaded here...</div>
<div class="navi"></div>
<a class="prev"></a>
<div class="scrollable">
<div class="items">
<?php foreach ($list->objects as $mediaEntry): ?>
<?php
$name = $mediaEntry->name; // get the entry name
$id = $mediaEntry->id;
$thumbUrl = $mediaEntry->thumbnailUrl; // get the entry thumbnail URL
$description = $mediaEntry->description;
?>
<a title="<?php echo $name; ?>" href="javascript:LoadMedia('<?php echo $id; ?>')"><img alt="Kaltura Thumbnail: <?php echo $name; ?>" title="<?php echo $name; ?>" src="<?php echo $thumbUrl; ?>" ></a>
<?php endforeach; ?>
</div>
</div>
<a class="next"></a>
</div>
<script language="javascript">
function LoadMedia(entryId) {
$('#mykdp').get(0).insertMedia("-1",entryId,'true');
}
</script>
[html]