Interface PHP pour Jamendo : JamendoLib

[modifier] Description

JamendoLib est un wrapper pour l'API de Jamendo. Voila, tout est dit :)

JamendoLib permet d'effectuer des requêtes sur Jamendo afin de réaliser différents types de recherches dans les bases Jamendo afin d'afficher ces résultats sur son propre site. JamendoLib ne couvre pas toutes les possibilités de l'API Jamendo mais est essentiellement orienté autour de la recherche d'album en vue d'afficher les pochettes et de gérer une popup permettant de jouer l'album sélectionné.

L'objectif de JamendoLib n'étant pas de donner la possibilité de refaire le site Jamendo en exploitant leur API, mais de permettre de faire la promotion de Jamendo et ses artistes en offrant la possibilité de faire découvrir leurs albums.

[modifier] Pour commencer : Quelques exemples

Rien de mieux pour commencer que quelques exemples d'utilisation de JamendoLib. Une partie de ces exemples utilisent les possibilités offertes par l'extension Mediawiki Jamendo qui est elle même en soit un exemple d'utilisation de JamendoLib.

[modifier] Exigences

PHP 5
PECL_HTTP

Le module PECL HTTP est utilisé pour interroger l'API Jamendo. Sans ce module JamendoLib continue à fonctionner, mais aucune des fonctions de recherche ne fonctionnera (toutes les fonctions utilisant les profiles), seule l'affichage d'album à partir des albumid pourra être utilisée.

Un wrapper HTTP pour remplacer le module PECL HTTP n'est pas très compliqué à faire, mais il est probable que si ce module n'est pas installable, les fonctions d'écriture et lecture de socket soient également désactivées.

Toute fois si vous rencontrez un problème à ce niveau, contactez moi sur le forum, et j'essayerais de vous aider.

[modifier] Installation

Nous vous conseillons très vivement de procéder à une installation sur un serveur de test avant de modifier votre serveur de production. Un backup est toujours une bonne chose avant d'apporter des modifications.

Après avoir téléchargé l'archive : JamendoLib_v1.0.0.tgz

Décompactez là à la racine de votre site, vous devez alors avoir l'arborescence suivante :

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

Cette extension s'accompagne d'une série de tests unitaires utilisant phpunit qui permettent de s'assurer que l'extension est bien compatible avec votre configuration.

Pour lancer les tests, appelez avec votre navigateur l'Url http://Monsite.org/Jamendo/Tests/MainPackage.php

Vous devez obtenir :

PHPUnit 3.0.6 by Sebastian Bergmann.

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

Time: 00:02


OK (33 tests)

Certain tests utilisant les données de Jamendo, les résultats peuvent varier, en particulier si Allison Crowe sort un nouvel album. Si les tests ne passent pas, envoyez moi le résultat (affichez le source de la page) sur le forum.

Si vous ne souhaitez pas utiliser les tests, ou lorsque vous avez fini de vous en servir, rendez les répertoires Jamendo/Tests et Jamendo/SearchTypes/Tests/ indisponibles, surtout sur votre serveur de production.

[modifier] Configuration

La configuration du module utilise un tableau associatif contenant les différents paramètres. Plusieurs configurations peuvent être enregistrées dans le tableau static Config de la classe Jamendo. Ces tableaux sont définis dans JamendoDisplayConfiguration.php

[modifier] Les structures de configuration

Par défaut, toutes les structures de configuration dérivent de la configuration Default. Ainsi pour créer une nouvelle configuration, il n'est pas nécessaire de renseigner tous les champs, mais seulement ceux qui diffèrent de la configuration par défaut.

La configuration Default ne doit en aucun cas être supprimée.

Les champs du tableau de configuration :

PopupParameters : La liste des paramètres à passer à window.open
Target : Le nom de la fenêtre popup
ScriptBaseUrl : L'url du script de gestion de la popup
HasTable : Doit ont placer les albums dans une table ?
TableClass : La classe CSS de la table
TableCols : Le nombre d'album par ligne
HasDiv : doit on placer chaque album dans un div ?
DivClass : La classe CSS du div
LinkClass : La classe CSS du lien (balise a)
ImgClass : La classe CSS de l'image
CoverWidth La largeur de l'image de l'album (toutes les tailles ne sont pas supportées par l'API Jamendo)
ErrorCover : l'image d'erreur à afficher en cas de problème

[modifier] Chargement d'une configuration

Pour obtenir une configuration, on n'utilise pas directement le tableau Configs. On utilise la fonction static Jamendo::config qui prend en entrée un nom de config et retourne le tableau de configuration fusionné avec la configuration par défaut.

La configuration peut alors être chargée par JamendoDisplayCover en utilisant loadConfiguration

[modifier] Les CSS

Toutes les classes CSS utilisées sont listées dans les configurations. Sur Art122-5 on utilise les CSS suivantes :

img.jamendo, img.jamendo_right, img.jamendo_left{
	padding:10px;
   	margin:5px;
   	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;
}

img.jamendo_menuleft {
	border:0px;
}

img.jamendo_right{
 	float:right;
 	margin-left:10px;
}
img.jamendo_left{
 	float:left;
 	margin-left:10px;
}

[modifier] Les profiles

Les profiles correspondent aux configurations de recherche d'album, ils se basent sur les classes de recherche. Ils sont utilisés pour afficher des listes d'albums, des albums au hasard, ou passer à l'album suivant dans la popup.

[modifier] Les structures Profiles

Les structures de profile sont propre à chaque classe de recherche mais doivent au minimum contenir un champ type contenant le nom de la classe à utiliser.

JamendoLib est livré avec 3 types de profiles

[modifier] UserStarredAlbumRequest

Permet de rechercher les albums associés à un utilisateur Jamendo:

type : UserStarredAlbumRequest
what : définie le type d'objet recherché, c'est l'index correspondant aux valeurs suivantes:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howMany est le nombre d'objet recherché, all pour tous, un entier positif sinon
order est l'ordre de tri utilisé, c'est l'index correspondant aux valeurs suivantes:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
direction : True pour trié par ordre montant, false descendant
option : le nom de l'utilisateur Jamendo

[modifier] ArtistAlbumRequest

Permet de rechercher les albums d'un artiste:

type : ArtistAlbumRequest
what : définie le type d'objet recherché, c'est l'index correspondant aux valeurs suivantes:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howMany est le nombre d'objet recherché, all pour tous, un entier positif sinon
order est l'ordre de tri utilisé, c'est l'index correspondant aux valeurs suivantes:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
direction : True pour trié par ordre montant, false descendant
option : le nom de l'artiste

[modifier] TagAlbumRequest

Permet de rechercher les albums correspondant à un tag donné:

type : TagAlbumRequest
what : définie le type d'objet recherché, c'est l'index correspondant aux valeurs suivantes:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howMany est le nombre d'objet recherché, all pour tous un entier positif sinon
order est l'ordre de tri utilisé, c'est l'index correspondant aux valeurs suivantes:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
direction : True pour trié par ordre montant, false descendant
option : le tag à rechercher

[modifier] Création d'un nouveau profile

Pour créer un nouveau profile à partir de méthode de requête existante, il suffit d'ajouter un élément au tableau Jamendo::$Profile dans le fichier JamendoProfile.php

[modifier] Les méthodes de requête

Pour créer une nouvelle méthode de recherche il faut créer une nouvelle classe dans le dossier SearcTypes héritant de JamendoRequest et l'ajouter de JamendoLib.php.

[modifier] Profiles génériques avec le champ option

Il n'est pas toujours pratique de devoir créer un profile pour chaque recherche. En effet si on souhaite par exemple proposer une extension MediaWiki pour permettre aux utilisateurs d'afficher tout ou partie de leurs albums favoris, on ne va pas leur demander d'éditer le fichier JamendoProfiles.php à chaque fois.

C'est pourquoi on a donné la possibilité de modifier la valeur du champ option d'un profile existant.

On utilise pour cela la fonction Jamendo::setProfileOption($profile,$option) ou $profile est le nom du profile et $option la nouvelle valeur de l'option. La fonction Jamendo::getProfileOption($profile) permet elle de récupérer la valeur du champ option d'un profile.

Les fonctions displayAnAlbumCover displayAlbumCoversFromProfile prennent en compte ce paramètre pour le propager à la popup de manière à en tenir compte lors du changement d'album.

Pour utiliser ce paramètre avec displayAlbumCoversFromProfile, vous pouvez par exemple utiliser:

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

[modifier] Fonctionnement

[modifier] JamendoLib

Le fichier JamendoLib.php est le point d'entrée pour utiliser ce module. C'est ce fichier que vous devez inclure pour pouvoir accéder aux autres objets.

require_once $root_directory . "Jamendo/JamendoLib.php"

Où $root_directory est le path du dossier contenant Jamendo.

[modifier] JamendoRequest

JamendoRequest contient toutes les méthodes utilisées par les classes profiles pour effectuer les appels à l'API Jamendo. Cette classe ne peut pas être directement instanciée, vous devez la surcharger pour créer un nouveau type de recherche.

Elle contient également les méthodes permettant de valider les paramètres utilisés par les profiles. Vous devez également surcharger ces méthodes si elles ne correspondent pas à vos besoins.

On notera également la présence de deux tableaux contenant des options valides :

$validWhatTag : les tags d'objet valides (id, title, page ...)
$validOrderTag : Les tags de tri

Un objet JamendoRequest est construit en utilisant la fonction static factory qui retourne un objet dérivant de JamendoRequest en fonction du profile.

[modifier] SearchTypes

Le répertoire SearchType contient les différentes classes utilisées pour effectuer des recherches sur Jamendo. Ces classes sont en faite les différents types de profiles utilisables par JamendoLib.

[modifier] UserStarredAlbumRequest

Cette classe permet de rechercher les albums associés à un utilisateur Jamendo:

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

whatTag est défini par le tableau validWhatTag et peut prendre les valeurs:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howManyTag est le nombre d'objet recherché, all pour tous, un entier positif sinon
orderTag est l'ordre de tri utilisé, les valeurs possibles sont les valeurs par défaut:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
option : le nom de l'utilisateur Jamendo

Dans la structure profile, c'est les index qui sont utilisés pour whatTag et orderTag

[modifier] ArtistAlbumRequest

Cette classe permet de rechercher les albums d'un artiste:

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

whatTag est défini par le tableau validWhatTag et peut prendre les valeurs:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howManyTag est le nombre d'objet recherché, all pour tous, un entier positif sinon
orderTag est l'ordre de tri utilisé, les valeurs possibles sont les valeurs par défaut:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
option : le nom de l'artiste recherché

Dans la structure profile, c'est les index qui sont utilisés pour whatTag et orderTag

[modifier] TagAlbumRequest

Cette classe permet de rechercher les albums associés à un tag donné:

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

whatTag est défini par le tableau validWhatTag et peut prendre les valeurs:
1. id : l'id de l'objet recherché
2. title : le titre de l'album
3. p2p : le lien vers le tracker
4. page : l'url de la page sur Jamendo
5. desc1 : La description de l'album
6. desc3 : La description de l'album au format HTML
7. artworkurl : le lien vers l'image de l'album
howManyTag est le nombre d'objet recherché, all pour tous, un entier positif sinon
orderTag est l'ordre de tri utilisé, les valeurs possibles sont les valeurs par défaut:
1. random : aléatoire
2. id : par id
3. alpha : alphabétiquement
4. rating_week : popularité
5. release_date : date de publication
6. public_date : date de mise à disposition du public
option : le nom du tag recherché

Dans la structure profile, c'est les index qui sont utilisés pour whatTag et orderTag

[modifier] JamendoDisplayCover

Cette classe gère l'affichage des albums en utilisant la configuration choisie. Si aucun des rendus paramétrables disponibles au travers de cette classe ne vous convient, vous devez envisager de l'adapter ou de réécrire votre propre classe de rendu.

En règle générale c'est cette classe que vous devez instancier pour utiliser JamendoLib.

[modifier] loadConfiguration

Charge une nouvelle configuration qui sera utilisée pour les prochains affichages.

[modifier] displayAnAlbumCover

C'est la fonction utilisée pour produire le rendu d'un album unique. Elle utilise les paramètres suivants :

album [Required]: L'album id à afficher
lang [Optional]: Le code de langue à utiliser pour les textes de la popup
searchProfile [Optional]: le nom du profile à utiliser pour pouvoir changer d'album dans la popup
option [Optional]: La valeur du champ option surchargeant celle du profile

[modifier] displayAlbumCoversFromProfile

Cette fonction est utilisée pour afficher une liste d'album à partir d'un profile. La liste d'albums affichée peut être plus petite que la liste d'albums retournée par la requête en utilisant le paramètre howMany de cette fonction.

La liste des paramètres :

searchProfile [Required]: le nom du profile à utiliser pour la recherche
howMany [Optional]: Le nombre d'album à afficher (1 par défaut)
lang [Optional]: Le code de langue à utiliser pour les textes de la popup
option [Optional]: La valeur du champ option surchargeant celle du profile

[modifier] JamendoPopup

JamendoPopup s'occupe de gérer la popup utilisée pour jouer les albums. Le script accepte différents paramètres :

album : l'id de l'album à jouer
search : Le nom du profile de recherche pour passer à un autre album
new : Si présent, provoque le changement d'album
lang : La langue à utiliser
searchindex : l'index de l'album courant dans la liste de recherche (permet de passer au suivant dans une liste non aléatoire)
option : surcharge la valeur de la clé option du profile sélectionné

[modifier] Licence

Cette extension est distribuée sous licence GPL v2

 * 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
 */

Vous avez la liberté de :

modifier
distribuer
utiliser

cette extension, dans un but commercial ou non.

Toute fois vous ne pouvez redistribuer cette extension en dehors du cadre prévu par la GPL, en particulier :

Même si vous la modifiez, cette extension reste sous GPL
Vous n'êtes pas autorisé à supprimer les informations relatives à son auteur ou à la licence

Récupérée de « http://www.art122-5.net/index.php/Interface_PHP_pour_Jamendo_:_JamendoLib »

Sommaire

[modifier] Description

[modifier] Pour commencer : Quelques exemples

[modifier] Exigences

[modifier] Installation

[modifier] Tests Unitaires

[modifier] Configuration

[modifier] Les structures de configuration

[modifier] Chargement d'une configuration

[modifier] Les CSS

[modifier] Les profiles

[modifier] Les structures Profiles

[modifier] UserStarredAlbumRequest

[modifier] ArtistAlbumRequest

[modifier] TagAlbumRequest

[modifier] Création d'un nouveau profile

[modifier] Les méthodes de requête

[modifier] Profiles génériques avec le champ option

[modifier] Fonctionnement

[modifier] JamendoLib

[modifier] JamendoRequest

[modifier] SearchTypes

[modifier] UserStarredAlbumRequest

[modifier] ArtistAlbumRequest

[modifier] TagAlbumRequest

[modifier] JamendoDisplayCover

[modifier] loadConfiguration

[modifier] displayAnAlbumCover

[modifier] displayAlbumCoversFromProfile

[modifier] JamendoPopup

[modifier] Licence