ListMembersByCategory, script PHP
Une classe PHP facile à utiliser pour afficher des enregistrements groupés en catégories

  • Souhaitez-vous afficher des membres groupés par catégorie sur votre site web?
  • Vous êtes à la recherche d'un composant facile d'emploi ?

ListMembersByCategory est certainement le script dont vous avez besoin.

fren

Qu'est-ce que ListMembersByCategory ?

ListMembersByCategory (LMBC) est un script PHP orienté objet permettant d'extraire et d'afficher des membres par catégorie. Chaque membre peut appartenir à une ou plusieurs catégories.
Le script est très facile à utiliser. Son indépendance de tout système de gestion de contenus (CMS), assure son fonctionnement avec n'importe quel site web hébergé avec PHP/MySQL.

Apprendre par l'exemple

La meilleure manière d'apprendre à utiliser ListMembersByCategory est de se pencher sur un cas pratique.
Notre exemple de listage de membres sera une école de musique ou chaque professeur enseigne un ou plusieurs instruments. Pour chaque instrument, nous voulons lister les professeurs qui l'enseignent.

Paramètres disponibles

Choix des tables

catTable
Le nom de la table qui dresse la liste des catégories disponibles (sans préfixe de table)
membersTable
La table qui détermine quels membres appartiennent à quelles catégories. Cette table peut éventuellement contenir d'autres champs relatifs à chaque membre.
membersExtendedTable
Une table optionnelle contenant des attributs étendus se rapportant aux membres listés.

Liaison des tables

catMatchField
Le nom du champ se trouvant dans "catTable" utilisé pour réaliser la liaison avec "membersTable".
membersMatchField
Le nom du champ se trouvant dans "membersTable" utilisé pour réaliser la liaison avec les catégories contenues dans "catTable".
Si ce paramètre n'est pas fourni le nom du champ de liaison de la table des catégories (catMatchField) est repris.
membersJoinField
Si "membersExtendedTable" est spécifié, il s'agit du nom de la colonne présente dans les deux tables "membersTable" et "membersExtendedTable" qui sera utilisée pour mettre en relation lesdites tables.

Filtrage des catégories

catFilterField
Le nom de la colonne de "catTable" utilisée pour sélectionner les catégories.
Lorsqu'il n'est pas fourni, ce paramètre prend la valeur de "catMatchField".
catFilterString
Une chaîne de caractères listant les catégories à sélectionner. Par défaut, toutes la catégories sont retenues.
catDelimitor
Un caractère utilisé pour séparer entre elles les valeurs de la chaîne "catFilterString". Par défaut: ',' (la virgule).

Formatage de la sortie

catDisplayField
Optionnel. Lorsque fourni, ce paramètre indique une colonne de "catTable" dont la valeur pourra être affichée au moyen de l'espace réservé [+lmbc.category.displayfield+] placé dans le modèle spécifié par "categoryTpl". Ceci permet d'afficher un titre pour chaque catégorie.
membersDisplayFields
Liste de noms de champs, séparés par des virgules, à extraire de la table des membres et/ou de la table des attributs étendus des membres pour chaque membre extrait.
Pour distinguer les champs devant être extraits de la table "membres" de ceux devant être extrait de la table "attributs étendus (des membres)", les champs de la table "attributs étendus" doivent être précédés d'une astérisque.
Si membersDisplayField prend la valeur d'une astérisque (seule), tous les champs de "membersTable" sont extraits.
Si "membersExtendedTable" est également fournie, tous ses champs seront alors également extraits.

Exemples

  • prenom,nom : demande les champs "prenom" et "nom" de "membersTable"
  • *loisirs : demande le champ "loisirs" de la table membersExtendedTable
  • id,*prenom,*nom : demande le champ "id" de la table membersTable et les champs "prenom" et "nom" de la table membersExtendedTable.
  • * : demande tous les champs de membersTable et également tous ceux de membersExtendedTable si celle-ci est fournie
splitIn
Entier positif optionnel.
Si supérieur à 1, les modèles HTML représentant les membres sont, pour chaque catégorie listée, répartis de manière égale en "splitIn" groupes. Dans le modèle "categoryTpl", l'espace réservé [+lmbc.category.members+] n'est alors plus disponible, mais remplacé par autant d'espaces réservés que spécifié par le paramètre "splitIn" : [+lmbc.category.members_group1+], ..., [+lmbc.category.members_groupN+].

Choix des modèles pour la mise en page

Les fichiers de modèles sont placés dans le dossier "chunks" de votre installation de ListMembersByCategory.
Si vous souhaitez appliquer un modèle particulier (autre que l'un de ceux appliqués par défaut), vous pouvez fournir le nom d'un fichier se trouvant dans le dossier "chunks" (sans le chemin).
outerTpl
Modèle qui sera appliqué comme enveloppe principale des données retournées par le script.
categoryTpl
Modèle qui sera appliqué à chaque catégorie retournée
memberTpl
Modèle qui sera appliqué à chaque membre de chaque catégorie

Ces paramètres sont optionnels. Par défaut les modèles décrits par les fichiers "outer.tpl", "category.tpl" et "members.tpl" sont utilisés.

Espaces réservés disponibles

Les espaces réservés disponibles dépendent du modèle considéré.

Espaces réservés de outerTpl

[+lmbc.categories+]
Indique où insérer les catégories listés à l'intérieur du modèle le plus externe.

Espaces réservés de categoryTpl

[+lmbc.category.displayfield+]
La valeur correspondant au parmètre catDisplayField. Grâce à cet espace réservé, vous pouvez facilement donner un titre aux catégories.

[+lmbc.category.members+]
Disponible seulement si le paramètre splitIn n'est pas établi, ou inférieur à 2. Indique où la liste formatée des membres retournés doit être insérée dans le modèle utilisé par la catégorie.

[+lmbc.category.members_groupJ+]
Disponible seulement si le paramètre splitIn est ≥ 2. Où J appartient à {1,2,...N}. Ces espaces réservés permettent d'indiquer à quels emplacements les N blocs listant les membres doivent être insérés dans le modèle utilisé par la catégorie.

Espaces réservés de memberTpl

[+lmbc.member.champ+]
Où "champ" représente n'importe quel nom de colonne de l'une des tables membersTable ou membersExtendedTable que vous avez passé comme valeur du paramètre membersDisplayFields.

FAQ

Questions de nature commerciale

Je ne suis pas certain que ce script permettra ce que je veux faire...

Si vous avez le moindre doute, contactez-nous. Nous vous répondrons dans un maximum de trois jours ouvrables et vous poserons les bonnes questions afin de savoir si ListMembersByCategory est le script qu'il vous faut.

Existe-t-il un service d'aide pour l'utilisation du logiciel ?

La licence "Professional" inclut un mois d'assistance gratuite quant à l'utilisation du script.

Que faire si je ne parviens pas à faire fonctionner le script correctement?

Commencez par lire la documentation et en particulier l'exemple que nous donnons.
Ensuite, contactez-nous. Nous vous répondrons dans un maximum de 3 jours ouvrables après que vous nous ayez contacté par téléphone ou email.
Si le dysfonctionnement est du à un bogue, un correctif vous sera fourni dans un maximum de 5 jours ouvrables, quel que soit le type de la licence que vous avez acquise ("Standard" ou "Professional").

Si vous avez acheté la licence "Professional", vous obtiendrez une assistance utilisateur directe par le développeur du composant.
A l'opposé, si vous acheté la license "Standard", vous n'obtiendrez aucune aide, sauf si le dysfonctionnement devait venir d'un bogue.

Questions techniques

Quels sont les exigences techniques pour pouvoir faire tourner What are the requirements to run the script ?

Vous avez pour cela besoin d'un hébergement PHP/MySQL avec la possibilité d'y transférer des fichiers et d'exécuter des scripts PHP. Vous devrez également connaître les paramètres de connexion à la base de données où se trouvent les tables dont le script exploite les données.
La classe est indépendante de tout CMS, mais pour les utilisateurs de MODx nous fournissons un "snippet" s'interfaçant avec celle-ci. Ainsi, si vous êtes un utilisateur de MODx, vous n'aurez pas le souci de créer un tel snippet.

Comment créer un objet ListMembersByCategory ?

Tout ce dont vous avez besoin est de régler quelques paramètres pour la connexion à votre base de données au début du fichier ListMembersByCategory.class.php, d'importer ce fichier dans votre code PHP et d'instancier un nouvel objet LMBC avec les paramètres appropriés.
Regardez notre exemple de listage de membres par catégorie pour découvrir comme ceci est facile.

Est-il possible d'appeler ListMembersByCategory plusieurs fois sur une page unique ?

Aucun problème. LMBC est écrit en code orienté objet et permet donc cela.

Quelles sont les tables MySQL nécessaires au fonctionnement du script ?

Lorsque vous créez un objet ListMembersByCategory, vous devez passer le nom de deux tables en paramètres. La table des catégories et la table des membres. Le nom des tables est libre.

La table "catégories" stocke les informations propres à chaque catégorie.

La table "membres" stocke la relation "membre-appartient-à-la-catégorie" pour chaque membre, plus tout champ additionel souhaité.

Puis-je utiliser une table supplémentaire pour stocker séparément les données relatives aux membres?

Absolument. Vous pouvez utiliser une troisième table, pour stocker les informations de chaque membre en dehors de la table établissant la relation "membre-catégorie(s)".

De quel nature doivent être les membres?

Il n'y a aucun type prédéfini.

Les membres qui doivent être affichés, groupés en catégories, peuvent représenter ce que vous voulez: des voitures, des animaux, des logiciels, etc. Le terme "membre" ne désigne donc pas obligatoirement des données se rapportant à une personne.

Le script PHP ListMembersByCategory est très flexible car il n'impose pas des champs prédéfinis tels que le nom, numéro de téléphone, etc. Comme les membres peuvent être ce que vous voulez, vous pouvez par exemple utiliser LMBC pour lister des voitures, groupées par marque, type de véhicule (limousine, break, SUV,...), et afficher les données que vous voulez (année d'imatriculation, couleur, prix, puissance, etc.).

Les noms de mes tables ont un préfixe commun. Puis-je spécifier ce préfixe?

Oui. Vous pouvez régler plusieurs détails de configuration comme celui-ci au début du fichier de classe. Cette opération est très facile à réaliser.

Comment le script met-il en page ce qu'il retourne ?

Les résultats des requêtes réalisées sur votre base de données sont insérés dans des morceaux (chunks) de code HTML agissant comme de mini modèles. Dans ces modèles, vous indiquez au moyen d'espaces réservés (placeholders) à quels emplacements les données issues des différents champs doivent être insérées.

Des exemples de modèles HTML sont-ils fournis avec le script?

Oui, vous les trouverez dans le dossier nommé "chunks".

A quoi reconnaît-on les espaces réservés?

La syntaxe retenue pour les espaces réservés est similaire à celle utilisée l'environnement de gestion de contenus MODx; des parenthèses carrées et des signes "plus" : [+espace_réservé+].

Quels espaces réservés (placeholders) le script met-il à disposition?

Les espaces réservés disponibles varient selon le modèle.
Pour les détails, veuillez consulter la section "Espaces réservés" située plus haut dans ce document.

Existe-il un raccourci pour rendre disponibles en tant qu'espaces réservés tous les champs des tables "membres"?

Oui, mettez une astérisque: *.

Passez simplement une astérisque au paramètre membersDisplayFields:
$membersDisplayFields='*';
(ou &memberDisplayFields=`*` dans MODx)

Passer une astérisque est équivalent à un listage explicite de tous les champs de la table spécifiée par membersTable (ainsi que de celle spécifiée par membersExtendedTable si elle existe).

Est-ce que le logiciel est livré avec MySQL?

Non. Vous devez obtenir MySQL de manière indépendante.

Licence

  • Vous obtenez un droit non exclusif d'utiliser le composant logiciel.
    ListMembersByCategory est distribubué selon une licence commerciale open source.
  • Redistribuer ou sous-licencier le composant logiciel n'est pas permis, mais vous pouvez cependant l'incorporer aux sites web que vous créer pour vos clients.
  • La licence standard permet l'utilisation du composant logiciel avec un (seul) site web/nom de domaine et vient sans aide aucune.
  • La licence professionnelle est la plus adaptée aux agences web. Elle permet l'utilisation dans chaque site web que vous créez.
  • Sous-traitance: Si vous travaillez avec des sous-traitants, chaque sous-traitant doit acquérir au moins une license "standard" pour avoir le droit d'accéder au composant lociciel.
  • Chaque licence vous permet de modifier le code pour l'adapter à vos besoins particuliers.

J'en ai besoin !

LMBC Professional Multisites. Avec assistance. LMBC Standard Pour un site. Sans assistance.