Jamendo PHP Interface : JamendoLib

[modifier] Description

JamendoLib is wrapper to the Jamendo API.

JamendoLib is used to request the Jamendo database using the Jamendo API and to display the result on another website. All the capabilities of the Jamendo's API are not covered by the JamendoLib. The wrapper is designed to search albums, to display their cover and playing them in a popup window.

The main goal of the JamendoLib is not to help to designe a website like Jamendo using their API, but to promote Jamendo and their artists with the diffusion of their albums

[modifier] Quick Start: Examples

The easiest way to demonstrate the capabilities of the JamendoLib is to show you some examples. Part of the examples use the Mediawiki Jamendo Extension that is itself an example of how to use the JamendoLib.

[modifier] Requirements

PHP 5
PECL_HTTP

The PECL HTTP module is used to request the Jamendo’s API. Without this module, only the capability to display an album still work. All of the search functions need this module.

[modifier] Installation

We very highly advise you to proceed to an installation on a test server before modifying your production server. A backup is always a good idea before making modifications.

First, download the file: JamendoLib_v1.0.0.tgz

Unzip it in your root directory:

Jamendo
Jamendo/Jamendo.php
Jamendo/JamendoDisplayConfiguration.php
Jamendo/JamendoDisplayCover.php
Jamendo/JamendoLib.php
Jamendo/JamendoPopup.php
Jamendo/JamendoProfiles.php
Jamendo/JamendoRequest.php
Jamendo/licence.txt
Jamendo/README.art122-5
Jamendo/SearchTypes
Jamendo/SearchTypes/ArtistAlbumRequest.php
Jamendo/SearchTypes/TagAlbumRequest.php
Jamendo/SearchTypes/UserStarredAlbumRequest.php
Jamendo/SearchTypes/Tests
Jamendo/SearchTypes/Tests/ArtistAlbumRequestTest.php
Jamendo/SearchTypes/Tests/TagAlbumRequestTest.php
Jamendo/SearchTypes/Tests/UserStarredAlbumRequestTest.php
Jamendo/Tests
Jamendo/Tests/JamendoDisplayCoverTest.php
Jamendo/Tests/JamendoRequestTest.php
Jamendo/Tests/JamendoTest.php
Jamendo/Tests/MainPackage.php
Jamendo/Tests/report

[modifier] Tests Unitaires

JamendoLib comes with unit tests using phpunit. You can use it to ensure you that this module is quite compatible with your configuration.

To run the tests, load this URL in your browser: http://Monsite.org/Jamendo/Tests/MainPackage.php

The result (use “show source code of the page”)

PHPUnit 3.0.6 by Sebastian Bergmann.

.................................

Time: 00:02


OK (33 tests)

Some of those tests use Jamendo data that can change and so breaking the tests. For example if Allison Crow publishes another album some tests may fail. The unit tests code comes with comments to help you to correct those tests.

When you stop using those tests, deactivate the directories Jamendo/Tests and Jamendo/SearchTypes/Tests/ especially in your main server.

[modifier] Configuration

To configure the JamendoLib we use a map array that contains all parameters. The static map Jamendo::Config is designed to store different configurations that you can use on the website. Those configurations are stored in the file JamendoDisplayConfiguration.php

[modifier] Configuration structures

All of the configurations derive of the Default configuration. When you want to create a new configuration, you don’t have to set all parameters, but only the parameters that have a different value from the Default.

You must never delete the default configuratio

The values of the configuration maps :

PopupParameters : The parameters list for window.open
Target : The popup name
ScriptBaseUrl : The url of the popup manager script (JamendoPopup.php)
HasTable : Use table element to display albums ?
TableClass : The css class of the table
TableCols : how many albums per row
HasDiv : Use div element to display an element ?
DivClass : The div css class
LinkClass : The link css class
ImgClass : The img css class
CoverWidth The width of the cover album
ErrorCover : The image to display if an error occurs

[modifier] Chargement d'une configuration

Don’t use the Jamendo:Configs map when you want to load a configuration, don’t use the Jamendo:Configs map, it only contains partial data. You have to use the Jamendo::config function that merges the requested configuration with the default one.

Then you can load the configuration choose in the JamendoDisplayCover object using loadConfiguration.

[modifier] The CSS

All the CSS class used are listed in the configurations maps. On the Art122-5’s website, we use :

img.jamendo {
	margin:5px;
	border:0px;
}

img.jamendo_menuleft {
	border:0px;
}

div.jamendo_cadre, div.jamendo_cadre_right{
	padding:10px;
   	margin:2px;
   	border: 1px;
	border-color: #0831A8;
	border-style:solid;
	-moz-border-radius-topright: 4px;
	-moz-border-radius-topleft: 4px;
	-moz-border-radius-bottomright: 4px;
	-moz-border-radius-bottomleft: 4px;
	background-color: #84AFD7;
}

div.jamendo_cadre_right{
 	float:right;
 	margin-left:10px;
}
div.jamendo_cadre_left{
 	float:left;
 	margin-right:10px;
}

[modifier] The profiles

The profiles are the configurations of the methods used to search albums. Those methods are defined by the search classes. They are used to load an album list, a random album or choose the next album from the popup.

[modifier] The profile structures

Like the configuration structures, the profiles structures are array maps. Their parameters list is defined by the search classes, but they must contain an element that defines the search method to be used .

JamendoLib comes with 3 kinds of profiles:

[modifier] UserStarredAlbumRequest

Use to search the starred albums of a Jamendo’s user.

type : UserStarredAlbumRequest
what : define the type of the search object. This is the index of the following list :
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option : The name of the Jamendo’s user

[modifier] ArtistAlbumRequest

Use to search all the albums of an artist.

type : ArtistAlbumRequest
what : define the type of the search object. This is the index of the following list :
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option The artiste’s name

[modifier] TagAlbumRequest

Use to search the albums that match a given tag.

type : TagAlbumRequest
what : define the type of the search object. This is the index of the following list :
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option : the search tag

[modifier] Création d'un nouveau profile

To create a new search profile using an existing search method, you just have to add a new profile structure in the profile map array Jamendo::Profiles in the JamendoProfiles.php file.

[modifier] Les méthodes de requête

To create a new serch method, you have to create a new class in the SearchTypes directory that extends the JamendoRequest class and add it in the JamendoLib.php file.

[modifier] Reusable profiles using the option field

It’s not really convenient to have to create a new profile for each search. For example if you want to create a Mediawiki extension to allow users to post their starred albums list on the wiki, you won’t ask them to edit the JamendoProfiles.php file.

So it’s possible to use an existing profile and overloading the option value. We use the Jamendo::setProfileOption($profile,$option) function where $profile is the profile name and $option the new value of the option parameter. The Jamendo::getProfileOption($profile) function returns the current value of the option parameter.

The functions displayAnAlbumCover and displayAlbumCoversFromProfile use this parameter and send it to the popup manager to use it when it chooses another album.

To use this parameter with the displayAlbumCoversFromProfile function, you can use for example:

Jamendo::setProfileOption($profile,$option);
echo $coverDisplay->displayAlbumCoversFromProfile($profile,$howMany,$wgLanguageCode,Jamendo::getProfileOption($profile));

[modifier] How that work?

[modifier] JamendoLib

The JamendoLib.php is the main entry point of the module. This is the file you have to include to use JamendoLib.

require_once $root_directory . "Jamendo/JamendoLib.php"

Where $root_directory is the path directory that contains the Jamendo folder..

[modifier] JamendoRequest

JamendoRequest is the main class of all the search type classes. It contains all methods you need for sending a request to the Jamendo’s API. You can’t instantiate it directly, you have to extends it in a new search type class.

The JamendoRequest also contains all methods you need for validating the correct value of the parameters used with profiles. When you create a new search method you have to overload these functions if they don’t work as you want.

There is two specials array that contain the list of valid option:

$validWhatTag : The available objects type (id, title, page ...)
$validOrderTag : The available order tags.

To instantiate a new JamendoRequest object, you have to use the JamendoRequest::factory that creates a new object of the type given in the profile structure.

[modifier] SearchTypes

The SearchTypes directory contains all the available search classes.

[modifier] UserStarredAlbumRequest

Use to search the starred albums of a Jamendo’s user

http://www.jamendo.com/get/album/list/album/".$whatTag."/plain/?n=".$howManyTag."&item_o=".$orderTag."&subset=user_star&uname=".$option

whatTag is defined in the array validWhatTag. Valid values are:
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option : The name of the Jamendo’s user

We use the index value for the whatTag and orderTag value.

[modifier] ArtistAlbumRequest

Use to search all the albums of an artist.

http://www.jamendo.com/get/album/list/artist/".$whatTag."/plain/?names=".$option."&n=".$howManyTag."&item_o=".$orderTag

whatTag is defined in the array validWhatTag. Valid values are:
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option : the artist’s name

We use the index value for the whatTag and orderTag value.

[modifier] TagAlbumRequest

Use to search the albums that match a given tag.

http://www.jamendo.com/get/album/name/tag/".$whatTag."/plain/".$option."/?n=".$howManyTag."&item_o=".$orderTag

whatTag is defined in the array validWhatTag. Valid values are:
1. id : The id of the search object
2. title : The title of the album
3. p2p : The bittorrent tracker
4. page : The url of the Jamendo’s page
5. desc1 : The album description
6. desc3 : The HTML album description
7. artworkurl : The link to the cover image
howMany an unsigned integer or the keyword “all”: how many object you want
order the field used to order the list. It‘s the index of the following list:
1. random
2. id
3. alpha
4. rating_week
5. release_date
6. public_date
direction : True for ascendant, false descendant
option : the search tag

We use the index value for the whatTag and orderTag value.

[modifier] JamendoDisplayCover

This class manages how the albums are displayed with the chosen configuration. you must create a new rendering class if none match your needs

This is the class you have to instanciate to use the JamendoLib.

[modifier] loadConfiguration

Load the new configuration.

[modifier] displayAnAlbumCover

This function is used to display one album. The parameter list:

album [Required]: The album id
lang [Optional]: The language code
searchProfile [Optional]: The name of the profile to use
option [Optional]: The overload value of option field

[modifier] displayAlbumCoversFromProfile

This function is used to display an album list from a profile. The album list can be smaller than the list returned by the API using the howMany parameter.

The parameter list:

searchProfile [Required]: The name of the profile
howMany [Optional]: how many album to display (default=1)
lang [Optional]: The language code
option [Optional]: The overload value of option field

[modifier] JamendoPopup

JamendoPopup the popup window used to play an album. The parameter list:

album : The album id
search : The name of the profile (used for next album)
new : if defined, choose another album
lang : The language code
searchindex : The index of the current album in the album list that is associated to the profile
option : The overload value of option field

[modifier] Licence

This extension is distributed under GPL v2 licence

 * Copyright (C) 2007  Marc Despland
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 */

You are free:

modify
distribute
use

this extension, with a commercial aim or not.

Any time you have to respect the licence clauses, in particular:

Even if you modify it, this extension remains under GPL
You are not authorized to remove information relating to its author or the licence

Retrieved from "http://www.art122-5.net/index.php/Jamendo_PHP_Interface_:_JamendoLib"

Sommaire

[modifier] Description

[modifier] Quick Start: Examples

[modifier] Requirements

[modifier] Installation

[modifier] Tests Unitaires

[modifier] Configuration

[modifier] Configuration structures

[modifier] Chargement d'une configuration

[modifier] The CSS

[modifier] The profiles

[modifier] The profile structures

[modifier] UserStarredAlbumRequest

[modifier] ArtistAlbumRequest

[modifier] TagAlbumRequest

[modifier] Création d'un nouveau profile

[modifier] Les méthodes de requête

[modifier] Reusable profiles using the option field

[modifier] How that work?

[modifier] JamendoLib

[modifier] JamendoRequest

[modifier] SearchTypes

[modifier] UserStarredAlbumRequest

[modifier] ArtistAlbumRequest

[modifier] TagAlbumRequest

[modifier] JamendoDisplayCover

[modifier] loadConfiguration

[modifier] displayAnAlbumCover

[modifier] displayAlbumCoversFromProfile

[modifier] JamendoPopup

[modifier] Licence