holmes

Recherche rapide et facile dans une page.

Holmes filtre une liste d'éléments en fonction de la valeur d'une input en seulement ~ 2 Ko.

Installation

Vous pouvez installer Holmes avec npm ou bower sous le nom du package holmes.js . Pour npm cela ressemble à ceci :

$ yarn add holmes.js # or via npm

Après quoi, vous pouvez l'ajouter à votre page avec, par exemple, webpack, rollup, browserify ou en chargeant le module dans une autre balise de script.

Vous devez vous assurer que vous disposez d'une règle css pour la classe .hidden qui masque les éléments comme vous le souhaitez. Une option est d'avoir ceci :

. hidden {
  display : none;
}

mais cela pourrait être n'importe quel css que vous voulez.

Usage

démo

Quand dois-je l’utiliser ?

Vous devriez utiliser Holmes lorsque

• vous disposez d'un nombre limité d'articles
• tu n'as pas besoin de tolérance aux fautes de frappe
• vous voulez seulement ajouter une très petite bibliothèque
• tous les éléments sont déjà visibles sur la page

Dans les cas où vos attentes sont plus compliquées, je vous suggère d'utiliser un service comme Algolia.

Divulgation équitable : je travaille actuellement chez Algolia, cela vous semble-t-il intéressant ? Rejoignez-nous !

Exemple simple

 holmes ( {
  input : '.search input' , // default: input[type=search]
  find : '.results div' // querySelectorAll that matches each of the results individually
} ) 

Possibilités

documentation complète

input

par défaut : input[type=search]

querySelector pour l'entrée

exemples : input , .search input

find requis

querySelectorAll pour les éléments dans lesquels rechercher

exemples : blockquote p , .result , .results div

class

class.hidden

par défaut : hidden

Classe à ajouter lorsque le fichier .find ne contient pas la requête de recherche.

exemples : hidden , dn , none

class.visible

par défaut : false

Classe à ajouter aux éléments visibles s’ils contiennent la requête de recherche.

exemples : visible , vis , nohidden

placeholder

par défaut : false

html pour montrer quand aucun résultat.

exemples : <p> No results </p> , Didn't find anything.

dynamic

par défaut : false

Activez cette option si vous souhaitez que Holmes interroge la valeur du .find à chaque entrée.

exemples : true , false

instant ️ DÉCONSEILLÉ

par défaut : false

Cette option est obsolète. Pour utiliser Holmes dans un environnement asynchrone, initialisez-le avec :

 holmes ( options ) . start ( ) ;
// or
const h = new holmes ( options ) ;
h . start ( ) ;

De cette façon, cela démarrera immédiatement, comme c'était le cas avec instant: true . Désolé pour le dérangement.

Par défaut, Holmes attendra un événement DOMContentLoaded pour lancer la recherche. Si vous chargez les éléments par AJAX par exemple, cet événement arrive trop tôt. Dans ce cas, vous pouvez activer instant et démarrer Holmes lorsque votre contenu est prêt.

exemples : true , false

minCharacters

par défaut : 0

Un minimum de caractères doit être saisi avant que Holmes ne commence le filtrage.

exemples : 2 , 5

mark

par défaut : false

Pour commencer à afficher le résultat dans une balise <mark> à l'intérieur du .find , vous devez l'activer. Pour changer la couleur dans laquelle cette match est affichée, vous devez styliser la couleur d'arrière-plan mark .

❗ cela brisera les auditeurs d'événements sur le contenu imbriqué

❗ cela ne fonctionnera pas si le caractère après la correspondance est un littéral > .

Si vous devez vraiment utiliser ce caractère, vous pouvez remplacer toutes les occurrences de > par >

exemples : true , false

hiddenAttr

par défaut : true

Ajoute hidden="true" aux éléments masqués. Lien intéressant expliquant son utilisation.

shouldShow

le jugement de correspondance par défaut est une correspondance partielle de la valeur d’entrée.

 function ( htmlText , search ) {
  return htmlText . indexOf ( search ) !== - 1 ;
}

Une fonction de correspondance personnalisée à appeler avec comme premier argument le texte d'un élément et comme deuxième argument le texte d'entrée actuel. Cela devrait renvoyer true si vous souhaitez que l'élément s'affiche et false s'il doit être masqué.

 var customMatching = function ( htmlText , search ) {
  return search . split ( / s+ / ) . every ( function ( v , i ) {
    if ( htmlText . indexOf ( v ) === - 1 ) {
      return false ;
    }
    return true ;
  } ) ;
}
holmes ( {
  shouldShow : customMatching
} )

onHidden

Rappel lorsqu'un élément est masqué.

 function ( el ) {
  console . log ( 'hide' , el ) ;
}

onVisible

Rappel lorsqu'un élément est à nouveau visible.

 function ( el ) {
  console . log ( 'show' , el ) ;
}

onEmpty

Rappel lorsqu'aucun élément n'a été trouvé.

 function ( placeholder ) {
  console . log ( 'nothing found' , placeholder ) ;
}

onFound

Rappel lorsque des éléments sont trouvés après avoir été vides.

 function ( placeholder ) {
  console . log ( 'something found' , placeholder ) ;
}

onInput

Rappel pour chaque entrée.

 function ( input ) {
  console . log ( 'current input' , input ) ;
} 

Méthodes et membres

Pour toutes les méthodes, vous devez initialiser une nouvelle instance de Holmes comme ceci :

 var h = new holmes ( options ) ;

Ensuite, vous pouvez utiliser les méthodes suivantes :

.clear()

Vous pouvez effacer une entrée Holmes par programme, en utilisant :

 h . clear ( ) ;

.count()

Vous pouvez recevoir des informations sur les éléments visibles, masqués et au total à tout moment :

 h . count ( ) ; // {all: 41, hidden: 34, visible: 7}

.start()

Démarrez un écouteur pair pour les options spécifiées. Holmes a toujours .start() en cours d'exécution lors de l'initialisation.

 h . start ( ) ;

.stop()

Arrête l'écouteur d'événements en cours d'exécution. Résout une promesse une fois celle-ci terminée.

 h . stop ( ) ;
h . start ( ) ; // could accidentally start too soon

h . stop ( ) . then ( h . start ) ; // might take a small time

.hidden

Il existe également un membre .hidden qui donne le décompte sans appel de fonction :

 console . log ( h . hidden ) ; // 34

.elements

Une NodeList de tous les éléments pris en compte par Holmes. Il existe également .elementsLength pour la quantité d'éléments et .elementsArray avec un tableau d'éléments.

.input

L'entrée dans laquelle Holmes recherche. Il y a aussi la dernière chaîne de recherche sous la forme .searchString

.placeholder

L'espace réservé actuel (nœud DOM).

.running

Si cette instance est en cours d'exécution ou non.

.options

Affiche les options choisies pour cette instance de Holmes. Vous pouvez également définir des options comme celle-ci après l'initialisation.

 console . log ( h . options ) ; // specified options

remarque : la définition des options après son exécution peut nécessiter h.stop().then(h.start)

Vitrine

Quoi	OMS	image
bullg.it	@haroenv
famille.scss	@lukyvj
wikeo.be	@bistory
lunchbreakapp.be	@AndreasBackx

J'aimerais découvrir comment les gens utilisent mon projet, faites-moi savoir si vous souhaitez être présenté !

Des questions ?

Compatible jusqu'à IE11. Pour la prise en charge des anciens navigateurs, vous devrez polyfill classList , addEventListener et l'événement input avec par exemple remy/polyfills. Je n'ai pas encore essayé moi-même, alors faites-moi savoir ce que vous avez utilisé si vous prenez en charge les anciens navigateurs !

Pour IE11, vous devez polyfill Object.assign et String.includes , vous pouvez le faire comme décrit dans #90

Faites-le moi savoir sur Twitter : @haroenv, ou dans un numéro.

Contribuer

Les contributions sont toujours les bienvenues ! Voici quelques directives générales :

• utiliser feature branches
• ne ralentis pas
• expliquez pourquoi vous souhaitez une fonctionnalité
• npm run doc pour recréer la documentation

La construction sur un UMD se fait via un rollup ( npm run build ).

Mais je ne mords pas, si vous avez des questions ou des insécurités, contactez-moi par exemple sur gitter.

Licence

Apache2.0