tvExplorer: beta test - documentation et explications

salut à tous,

posez vos questions relatives à l’usage de tvexplorer ici.
J’éditerai ce post au fur et à mesure pour communiquer la documentation du snippet.

L’archive contenant le snippet est dispo dans ce fil. :
http://modxcms.com/forums/index.php/topic,15270.0.html

L’installation du module tvEditor est obligatoire

A quoi sert tvExplorer ?

tvExplorer permet de créer trés facilement des formulaires de recherches avancées combinant recherche fulltext, arborescence et tvs.
La liste de résultats est générée grace à ditto.

DOCUMENTATION

Les paramètres obligatoires:

&dittoName => le nom du snippet ditto à utiliser
&dittoSnippetParameters => les parametres de ditto
Ils doivent être écrits sous la forme
param:value|param:value
&formTPL => nom du chunk contenant les tags de tvexplorer

IMPORTANT:

Pour que tvexplorer fonctionne vous devez donner à l’attribut name="" de votre <submit> la valeur "search" pour que la recherche soit activée.
Si vous utilisez le parametre &tveID, pensez à rajouter comme préfixe la valeur de &tveID suivi de ’_’ à la valeur "search"
Ex: &tveID=`tvx` => name="tvx_search".

Les paramètres optionnels:

&tveID => Dans le cas d’appels multiples du snippet dans la page, ce parametre rend unique chaque formulaire.
Vous devrez rajouter cette valeur comme prefixe suivi de ’_’ devant chaque placeholder placé à la suite de l’appel.
Ex: &tveID=`tvx`
[+tvx_tve.searchForm+]
[+tvx_tve.dittoList+]

&extraTVs => Si dans votre/vos chunks Ditto vous utilisez le placeholder [+tagLinks+] , extraTVs vous permet d’afficher des tvs qui ne font pas partie du formulaire.
Elles seront passées à ditto par l’intermédiaire de tagData.

&cssStyle => liste de fichiers css(séparés par une virgule) à inclure dans le head du document.

&jScript => liste de fichiers js (séparés par une virgule) à inclure dans le head du document.

Les tags

La syntaxe à utiliser pour construire un tag est la suivante.

[+tve.nomElement:param->value:param2->value2+]


Les tags pour les tvs

- Les proprietes des tags tvs

• tvtype:
• fullText:
• filter:
• filterOff:

- La méthode #RANGE

Les tags speciaux

[+tve.keywordsSearch+]
- Les proprietes de keywordsSearch

• searchStyle
• label
• excludeTVs
• includeTVs

à compléter

[+tve.parentElt+]

parentElt sert à restituer l’arbre de documents sous la forme de son choix pour offrir aux visiteurs la faculté de restreindre la recherche à un folder et ses enfants en particulier.

Ex de tag: [+tve.parentElt:type->select:start->10,15:depth->2,3:label->Choisissez une rubrique:blankLabel->-+]

- Les proprietes de parentElt

• start : liste des ids des folders que vous souhaitez afficher séparés par une virgule.
  Ex: start->5 ou bien start->5,14,47
• depth: fixe la profondeur pour chaque folder contenu dans la liste start.
  on peut définir une profondeur pour chaque folder contenu dans start
  Ex: start->5,14,47:depth->2,3,1
  Dans ce cas le:
  pour le folder 5, on affichera les folders enfants de 5 sur 2 niveaux (5 inclus)
  pour le folder 14, on affichera les folders enfants de 14 sur 3 niveaux (14 inclus)
  pour le folder 47, on affichera les folders enfants de 47 sur 1 niveau (47 inclus)
  
• excludeStart :
• hideFolders :
• type: le type d’element a utiliser dans le formulaire (checkbox, dropdown/select, radio/option)
  La denomination modx et html est supportée.
• label: Le texte contenu dans la balise <label>
  Ex: label->Mots Clés
• blankLabel: pour les selects/dropdown vous pouvez déterminer le texte à afficher dans la première valeur vide.
  blankLabel->sélectionnez une valeur
• addBlank: Si vous souhaitez activer/désactiver la première valeur vide du select (par defaut la valeur est 1)
  Ex: addBlank->0 on désactive l’inclusion de la premiere option vide du select.

[+tve.dateElt+]

Ex de tag: [+tve.dateElt:source->createdon:name->dateCreation:filter->dateFilter:label->Créé le+]

• source
• name
• dateFormat
• dateSplitter
• filter

Le systeme de templates

- Les chunks par type

Lors de l’installation du module tvEditor, des chunks par défaut seront installés pour tvExplorer.
Voici le contenu de chacun d’entre eux.
J’uniformiserai leur contenu pour les prochains release.
La construction de chaque input est réalisée en utilisant la class MakeForm de Jason (OpenGeek)
Je reviendrai plus tard sur les régles de substitution des placeholders de la classe MakeForm.

à compléter
&checkboxTPL

<label class="checkbox" [+for+]><input class="checkbox" type="checkbox" [+id+] name="[+name+]" [+value+][+size+][+checked+][+disabled+][+style+][+events+]/>[+label+]</label>
[+extra+]

&textTPL

<label class="[+required+][+optional+][+className+]" [+for+]>[+label+]</label>
<input type="text" [+id+] name="[+name+]" [+value+][+size+][+maxlength+][+readonly+][+disabled+][+class+][+style+][+events+][+onclick+]/>
[+extra+]

&hiddenTPL

<input type="[+type+]" [+id+] name="[+name+]" [+value+] />[+extra+]

&selectTPL

<label class="select[+required+][+optional+][+className+]" [+for+]>[+label+]</label>
<select [+id+] name="[+name+]" [+size+][+disabled+][+multiple+][+class+][+style+][+onchange+]>
[+tve.wrapper+]
</select>
[+extra+]

&optionTPL

<option [+value+][+selected+]>[+label+]</option>

&radioTPL
ndlr: celui-ci devra être modifié dans la nouvelle version de tvexplorer (<label> mal placé)

<input class="radio" type="radio" [+id+] name="[+name+]" [+value+][+size+][+checked+][+disabled+][+style+][+events+]/>
<label class="radio[+required+][+optional+]" [+for+]>[+label+]</label>
[+extra+]

- Les chunks personnalisés
à compléter

Les placeholders

- A placer après l’appel
à compléter

[+tve.searchForm+]

[+tve.dittoList+]

- A placer dans les chunks
à compléter


EXEMPLES:

http://www.dixsix.fr/explorer/

Le code du chunk &formTPL

<form action="[~[*id*]~]" method="get" >
<fieldset>
[+tve.keywordsSearch:excludeTVs->all:label->Mots clés+]
</fieldset>
<fieldset>
[+tve.Appellation:filter->9+]
</fieldset>
<fieldset>
[+tve.categorie:filter->9:c_blankLabel->-+]
</fieldset>
<fieldset>
[+tve.Couleur:filter->9+]
</fieldset>
<fieldset class="sendForm">
<input type="submit" name="tve_search" value="Search" />
</fieldset>
</form>

L’appel et les placeholders

[[tvExplorer? &dittoName=`Ditto` &formTPL=`formVin` &dittoSnippetParameters=`tpl:testPHX2|summarize:30|debug:1|paginate:1|depth:5|parents:23` ]]
[+tve.searchForm+]
<h3>nb documents:[+total+]</h3>
<div id="ditto_list">[+tve.dittoList+]</div>
<p class="ditto_pagination">Page <strong>[+currentPage+]</strong> of <strong>[+totalPages+]</strong></p>
<p class="ditto_pagination"> <span id="ditto_pages">[+previous+] [+pages+] [+next+]</span></p>

FAQ
Questions:
je veux effectuer une recherche en front sur le titre d’un produit par exemple, dois-je créer une tv titre ou puis-je utiliser le champ titre d’un doc ...même question pour le [*content*] ?

Réponse :

Pour la recherche fullText on a deux possibilités.

Soit on utilise le tag prévu à cet effet [+tve.keywordsSearch+] et dans ce cas la recherche sera effectuée sur :
- les champs du document (pagtitle, longtitle, description, introtext et content)
- toutes les tvs (champ value de la table site_tmplvar_contentvalues)

on peut parametrer cette recherche:
- en excluant une ou des tvs (parametres excludeTVs-> liste id ou nom des tvs séparées par des virgules )
"all" élimine toutes les tvs.


Soit on veut seulement chercher sur une tv et pas les champs du document et dans ce cas, on ajoute au tags de la tv le parametre
fullText->true
[+tve.nomTV:fullText->true+]
Ici il y a au moins une contrainte si la tv sur laquelle vous souhaitez déclencher la rehcerhce n’est pas de type texte vous devrez forcer ce type sur le front.
Ex: [+tve.nomTV:fullText->true:tvtype->text+]


:-)

LE FONCTIONNEMENT DES FILTRES de tvExplorer

Prenons l’exemple en ligne:  http://dixsix.fr/explorer/

TV1: Appellation (checkbox)
Valeurs des options: Bordeaux, Côtes du Rhône, Bourgogne, Chateauneuf du pape

TV2: Couleur (listbox-Multiple)
Valeurs des options: Rouge, Rosé, Blanc.

TV3: Categorie(select)
Valeurs des options: Vin de Pays, Vin AOC, Grand crû.


Si on recherche les vins de ChateauNeuf du Pape (ET) Rouge,(ET) Grand crû
Les filtres seront:
F1 : &filter:tvAppellation,ChateauNeuf du Pape,7|tvCouleur,Rouge,7|&Categorie,Grand crû,7
ou
F2 :&filter:tvAppellation,ChateauNeuf du Pape,1|tvCouleur,Rouge,1|&Categorie,Grand crû,1
dans les deux cas le tagMode est "onlyTags"

Maintenant si on souhaite aller plus loin et permettre une recherche du type
les vins de ChateauNeuf du Pape OU Bourgogne (ET) Rouge OU Rosé (ET) Grand crû
Les filtres F1 et F2 produiront des résultats insatisfaisants
on obtiendra les vins de ChateauNeuf du Pape OU Bourgogne (OU) Rouge OU Rosé (ET) Grand crû
on retrouvera dans la liste les bordeaux rouges grands crus,  bordeaux rosés grands crus, Côtes du Rhône rosés grands crus et Côtes du Rhône rouges grands crus alors que notre recherche visait seulement deux appellations.

On est donc loin du résultat escompté.

tvExplorer va produire les filtres complémentaires pour assurer une meilleure liste de résultats correspondant exactement à la requête.
Pour se faire, on va exclure de la liste de résultats, les documents qui ont parmi leurs propriétés une des options
non sélectionnées.

Ce qui donnera:
F1 : &filter:tvAppellation,ChateauNeuf du Pape,7|tvAppellation,Bourgogne,7|tvCouleur,Rouge,7|tvCouleur,Rosé,7|Categorie,Grand crû,7

ou

F2 : &filter:tvAppellation,ChateauNeuf du Pape,1|tvAppellation,Bourgogne,1|tvCouleur,Rouge,1|tvCouleur,Rosé,1|Categorie,Grand crû,1

+ filtres tvExplorer
=> tvAppellation,Côtes du Rhone,2|tvAppellation,Bordeaux,2|tvCouleur,Blanc,2|Categorie,Vin AOC,2|Categorie,Vin de Pays,2|

On obtiendra le résultat attendu à savoir
Les vins de bourgogne OU Chateauneuf du pape ET Rouge OU Rosé ET Grand Crû

A noter que les filtres ne sont pas passés à Ditto sous cette forme.
On construit directement un tableau pour éviter à Ditto de parser les filtres.

Bonsoir les djeunz ! (La folie me guette, je viens de passer 2H à régler un bug sur IE6 sur du positionnement css... je divague... mais au final, je suis heureuse, Déco’In est enfin en 0.9.6 ! )
Bref tout ça pour dire, aussi, que merci beaucoup Helio... mon héro !

Je vous invite à voir tvExplorer en action (qu’Helio et moi surnommons tvx) sur http://www.deco-in.com/recherche-avancee

Sur cette recherche, nous (je dis nous car Helio me coach pas mal en matière de recherche ^^) avons souhaité pouvoir afficher une recherche de produits de déco, et une recherche de professionnels de la déco. L’idée a été de présenter ça sous forme d’onglet. Et ce fut possible grâce à la dernière trouvaille d’Helio qui, grâce au paramètre &tveID, permet de faire plusieurs appels du snippet (à l’identique du &id de Ditto).

L’appel de la recherche de produits est le suivant :


Si on décortique l’appel en lui-même :

&tveID : l’id de l’appel tvx pour réaliser plusieurs appels sur la même page

&cssStyle et &jScript : appellent les fichiers nécessaires pour la gestion des onglets

&formTPL : le template de mon formulaire, je le décrypterai plus bas

&dittoName : le nom du snippet contenant Ditto (par défaut Ditto mais vous pouvez très bien l’avoir renommé)

&dittoSnippetParameters : tous les paramètres Ditto qui définissent l’affichage des résultats (entre autres, les templates de la liste de résultats, si oui ou non on affiche la pagination, etc...)

[+tvxVitrine_tve.searchForm+] : tvx construit le form à partir de tous les éléments vu au-dessus et l’insère à la place de ce placeholder.

J’en profite pour vous indiquer le template de mon formulaire de recherche produits :



C’est imposant car il y a le code pour les onglets mais sinon, c’est facile. Chaque placeholder ( [+tve.MaTV:blabla+] )construit lui-même le couple label / input.

[+tve.keywordsSearch:label->Mots-clés+] : Génère le premier input pour rechercher un mot-clé. label->blabla définit le label associé à l’input. tvx se charge ensuite de faire coincider le for du label et le id de l’input pour les lier.

[+tve.parentElt:type->dropdown:start->4:depth->3:blankLabel->-:label->Choisissez une rubrique+] : Permet de construire une liste déroulante (type->dropdown) pour limiter la recherche à la rubrique Vitrine id4 (start->4), jusqu’à 3 niveaux (depth->3). Ce placeholder peut ne pas être utilisé. Par ex, quand vous allez dans une rubrique de l’annuaire (par ex, http://www.deco-in.com/annuaire/architectes/), il apparait logique de ne pas demander à l’utilisateur de reselectionner la rubrique architecte alors qu’il y est déjà dedans. Dans ce cas-là, on supprime le placeholder parentElt et on indique dans l’appel tvExplorer les paramètres &parents ou &documents dans &dittoSnippetParameters pour indiquer dans quel dossier on lance la recherche. Suis-je claire ?

[+tve.ObjetPrix:#RANGE{tvtype->dropdown:elements->@CHUNK intervalPrix:filter->4:label->Votre budget (prix max.)}+] : Là encore chapeau Helio : ce placeholder permet de définir des intervalles. Voici le chunk intervalPrix, ça parle de lui-même tellement c’est fastoche


[+tve.ObjetStyle:label->Quel(s) style(s) ?:filter->9:size->8+] : Ensuite, pour chacune des tvs que j’ai créé pour gérer les caractéristiques des objets déco, on crée un placeholder. ObjetStyle est la TV qui sert à stocker le style de l’objet.. On retrouve ensuite ObjetColoris, ObjetMateriau, ObjetPiece etc...

<input type="submit" class="tve_search" name="tvxVitrine_search" value="Chercher" /> : Enfin le bouton de recherche où name doit être identique à &tveID_search

Reste la fin de l’appel


[+tvxVitrine_tve.dittoList+] : tvxVitrine est le &tveID et tve.dittoList le placeholder pour afficher la liste des résultats

{{tvxPaginationListeVitrine}} : pagination de Ditto. Les placeholders qui sont contenues dans le chunk (voir ci-dessous) doivent aussi avoir le préfixe &tveID.


Et voilà un super formulaire, puissant et hautement flexible.

Pour illustrer un peu plus la méthode #RANGE

Voici l’élément prix avant que la méthode lui soit appliquée



Avec #RANGE



QQ explications

dans la base la tv prix a pour type "number"
Avec ce tag

[+tve.ObjectPrix:#RANGE{tvtype->dropdown:label->Votre budget (prix max.):elements->@Chunk intervalPrix:filter->4}+]

tvtype->dropdown => on affecte un nveau type à la tv pour le front

elements->@CHUNK intervalPrix => Comme le type de la tv est number elle ne possède pas d’options, alors on va lui en créer.
Ici on va appeler le @BINDINGS @CHUNK (tous les @BINDINGS sont supportés@EVAL @SELECT @DIRECTORY plus un nouveau que j’ai créé @TV)

Dans cet exemple le chunk contient:

Moins de 15€==15||Moins de 50€==50||Moins de 80€==80||Pas de limite==9999

Si vous avez besoin de créer deux éléments pour votre intervalle, séparer chacune des bornes par ||

[+tve.tvname:#RANGE{from || to }+]

:-)

Salut,

alors pour ceux ça intéresse ( je suis sur qu’il y en a qquns)
J’ai corrigé pas mal de bugs (merci à Laurent pour son fix pour le mode de recherche "relevant")
rajouter des options de configuration sur parentElt.
Je suis en train de rajouter le support des dates.
je tacherai de poster une mise à jour lorsque j’en aurai terminé.


:-)

Cool merci pour l’update !

Ca me rappelle qu’il faut que je passe la 2ème vitesse côté test de TVexplorer...

Bonjour,

Tout d’abord, bravo à vous pour ce magnifique outil.
Je viens de l’installer et de le tester, ça fonctionne vraiment bien.

Cependant, j’ai un petit souci.
En effet, j’utilise tvExplorer pour un moteur de recherche de biens immobiliers.
Mes critères de recherche sont les suivants :
- Nature du biens (menu déroulant avec : appartement, maison...etc)
- Nombre de pièces (champ texte)
- Villes ou codes postaux : 4 champs texte
- Ville la plus proche (menu déroulant) + 5 boutons radios pour spécifier la distance (5,10,20,30 ou 40 kms)

Ainsi, l’utilisateur peut en une seule recherche voir les appartements qu’il y a dans plusieurs villes ou plusieurs départements

et/ou à proximité d’une grande ville si besoin.
Pour les 4 champs textes, il faut donc pouvoir tester les mêmes TV lors de la même recherche.
Et pour la ville la plus proche, il faut faire un test des biens ayant la ville la plus proche sélectionnée ET le nombre de kilomètres coché (ou en dessous).

C’est là que je bloque...

Mon chunk contenant le formulaire est le suivant :




J’ai donc 2 questions :

- Comment puis-je faire pour faire apparaître 3 autres champs (en dessous de mon "keywordsSearch") avec des noms différents mais qui testent les mêmes TVs?
J’ai essayé de spécifier un nom mais l’attribut "name" n’existe pas pour keywordsSearch.
J’ai aussi essayé de dupliquer à l’identique mon appel [+tve.keywordsSearch:includeTVs->ville,code_postal:label->+] mais il les comprend comme étant un seul et même champ (puisque le même nom : "testsearch").

- Comment puis-je faire pour que le moteur de recherche ne tienne pas compte de la casse?
Pour l’instant, pour trouver un appartement à Paris, si je ne mets pas de majuscule à la ville, le moteur ne me trouve aucun résultat.

Merci d’avance pour vos réponses avisées.

Salut,

- Comment puis-je faire pour faire apparaître 3 autres champs (en dessous de mon "keywordsSearch") avec des noms différents mais qui testent les mêmes TVs?
J’ai essayé de spécifier un nom mais l’attribut "name" n’existe pas pour keywordsSearch.
J’ai aussi essayé de dupliquer à l’identique mon appel [+tve.keywordsSearch:includeTVs->ville,code_postal:label->+] mais il les comprend comme étant un seul et même champ (puisque le même nom : "testsearch").

Pour effectuer une recherche full text sur une TV seule.
[+tve.ville:fullText->true:label->Veuillez saisir une ville+]
[+tve.code_postal:fullText->true:label->Veuillez saisir un code postal+]

En revanche je deconseille le underscore dans le nom des tvs, je suis pas certain qu’il n’y ait pas de bugs possible avec tvEditor lors de l’édition des options des tvs dans le module (pour les tvs de types select, checkbox, etc..).

Il ne sera pas possible de multiplier les champs textes pour les memes tvs.
Je suis pas ceratin que cela soit utile en plus autant demander aux internautes de saisir plusieurs villes en les séparant d’une virgule.

Pour les recherches et la casse de caractères c’est étonnant tvexplorer execute AjaxSearch.
En suivant les exemples ci dessus, tout devrait rentrer dans l’ordre.

:-)

Tout d’abord, merci à toi pour ta réponse.

Je vais en effet opter pour ta solution avec un seul champ texte dans lequel on peut entrer plusieurs propositions.
Et je vais enelver les underscore de mes noms de TV.

Par contre, pour ce qui est de la casse, est-ce que cela à quelquechose à voir avec l’attribut "filter"?
Car je n’arrive pas à trouver de documentations explicant les correspondances des numéros utilisés pour cet attribut.

Par exemple, quand je mets :



A quoi correspond le chiffre 9?
Et si j’utilise d’autres chiffres, à quoi correspondent-il?

Merci à nouveau pour vos réponses.

Les filtres de 1à8 sont ceux de Ditto.
Le Filtre 9 agit comme le mode onlyTags de Ditto.
On verifie que la valeur recherchée appartient au tabelau de valeurs des options de la TV.
Il n’est pas adapté à une recherche fulltext, il convient d’avantage pour les tvs à choix multiples.

:-)