All Projects → Haroenv → Holmes

Haroenv / Holmes

Licence: apache-2.0
Fast and easy searching inside a page

Programming Languages

javascript
184084 projects - #8 most used programming language
HTML
75241 projects

Projects that are alternatives of or similar to Holmes

picoCSS
picoCSS - really small JavaScript Framework
Stars: ✭ 62 (-96.31%)
Mutual labels:  dom, minimal
Ngx Mat Select Search
Angular component providing an input field for searching / filtering MatSelect options of the Angular Material library.
Stars: ✭ 416 (-75.22%)
Mutual labels:  search, filter
crab
JavaScript library for building user interfaces with Custom Elements, Shadow DOM and React like API
Stars: ✭ 22 (-98.69%)
Mutual labels:  dom, minimal
Searchobject
Search object DSL
Stars: ✭ 152 (-90.95%)
Mutual labels:  search, filter
Monoapp
choo architecture without a renderer
Stars: ✭ 52 (-96.9%)
Mutual labels:  minimal, dom
Search
CakePHP: Easy model searching
Stars: ✭ 153 (-90.89%)
Mutual labels:  search, filter
React Search Input
🔍 Simple react.js component for a search input, providing a filter function.
Stars: ✭ 300 (-82.13%)
Mutual labels:  search, filter
AdvancedHTMLParser
Fast Indexed python HTML parser which builds a DOM node tree, providing common getElementsBy* functions for scraping, testing, modification, and formatting. Also XPath.
Stars: ✭ 90 (-94.64%)
Mutual labels:  dom, filter
Lara Eye
Filter your Query\Builder using a structured query language
Stars: ✭ 39 (-97.68%)
Mutual labels:  search, filter
Crab
JavaScript library for building user interfaces with Custom Elements, Shadow DOM and React like API
Stars: ✭ 22 (-98.69%)
Mutual labels:  minimal, dom
Laravel Api Handler
Package providing helper functions for a Laravel REST-API
Stars: ✭ 150 (-91.07%)
Mutual labels:  search, filter
Searchable
Search/filter functionality for Laravel's Eloquent models
Stars: ✭ 113 (-93.27%)
Mutual labels:  search, filter
Jquery Searchable
Tiny, fast jQuery plugin to search through elements as you type.
Stars: ✭ 142 (-91.54%)
Mutual labels:  search, filter
Fuzzysort
Fast SublimeText-like fuzzy search for JavaScript.
Stars: ✭ 2,569 (+53.01%)
Mutual labels:  search, filter
Ng2 Search Filter
Angular 2 / Angular 4 / Angular 5 custom pipe npm module to make a search filter on any input, 🔥 100K+ downloads
Stars: ✭ 137 (-91.84%)
Mutual labels:  search, filter
Choo
🚂🚋 - sturdy 4kb frontend framework
Stars: ✭ 6,637 (+295.29%)
Mutual labels:  minimal, dom
Faltu
Search sort, filter, limit an array of objects in Mongo-style.
Stars: ✭ 112 (-93.33%)
Mutual labels:  search, filter
Searchobjectgraphql
GraphQL plugin for SearchObject gem
Stars: ✭ 118 (-92.97%)
Mutual labels:  search, filter
Downloadsearch
search for any kinds of files to download
Stars: ✭ 124 (-92.61%)
Mutual labels:  search
Cyb
Immortal robot for the Great Web
Stars: ✭ 126 (-92.5%)
Mutual labels:  search

Holmes.js

Fast and easy searching inside a page.

Build Status Coverage Status npm version Bower version CDNJS version Join the chat at https://gitter.im/Haroenv/holmes gzipped size

Holmes filters a list of elements based on the value of a input in just ~2KB.

Installation

You can install Holmes with either npm or bower under the package name holmes.js. For npm that looks like this:

$ yarn add holmes.js # or via npm

After which you can add it in your page with i.e. webpack, rollup, browserify or loading the module in a different script tag.

You have to make sure that you have a css rule for the class .hidden that hides elements however you want. One option is to have this:

.hidden {
  display: none;
}

but this could be any css you want.

Usage

demo

When should I use it?

You should use Holmes when

  • you have a limited amount of items
  • you don't need typo-tolerance
  • you only want to add a really small library
  • all items are already visible on the page

In cases where you have a more complicated expectation, I'd suggest using a service like Algolia.

Fair disclosure: I currently work at Algolia, does it seem interesting? Join us!

Simple example

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

Options

full documentation

input

default: input[type=search]

querySelector for the input

examples: input, .search input

find required

querySelectorAll for elements to search in

examples: blockquote p, .result, .results div

class

class.hidden

default: hidden

Class to add when the a .find doesn't contain the search query.

examples: hidden, dn, none

class.visible

default: false

Class to add to visible items if they contain the search query.

examples: visible, vis, nohidden

placeholder

default: false

html to show when no results.

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

dynamic

default: false

Enable this option if you want Holmes to query the value of the .find at every input.

examples: true, false

instant ⚠️ DEPRECATED

default: false

This option is deprecated. To use Holmes in an async environment, initialise it with:

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

This way it'll start immediately, just like it used to do with instant: true. Sorry for the inconvenience.

By default Holmes will wait on a DOMContentLoaded event to start searching. If you're loading the elements by AJAX for example this event comes too early. In that case you can enable instant, and start Holmes when your content is ready.

examples: true, false

minCharacters

default: 0

A minimum amount of characters need to be typed before Holmes starts filtering.

examples: 2, 5

mark

default: false

To start showing the result in a <mark> tag inside the .find, you should enable this. To change the colour this match is shown in, you should style the mark background-color.

this will break event listeners on nested content

this won't work if the character after the match is a literal >.

🗣️ If you really have to use this character, you can replace all occurences of > by &gt;

examples: true, false

hiddenAttr

default: true

Adds hidden="true" to hidden elements. Interesting link explaining its use.

shouldShow

default match judgment is a partial match of the input value.

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

A custom matching function to be called with as first argument the text of an element, and as second argument the current input text. This should return true if you want the element to show, and false if it needs to be hidden.

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

Callback for when an item is hidden.

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

onVisible

Callback for when an item is visible again.

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

onEmpty

Callback for when no items were found.

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

onFound

Callback for when items are found after being empty.

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

onInput

Callback for every input.

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

Methods and members

For all of the methods you should initialise a new instance of Holmes like this:

var h = new holmes(options);

Then you can use the following methods:

.clear()

You can clear a holmes input programmatically, by using:

h.clear();

.count()

You can receive informations on what elements are visible, hidden and in total at any point:

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

.start()

Start an even listener for the specified options. Holmes always has .start() running on initialisation.

h.start();

.stop()

Stops the current running event listener. Resolves a Promise when this has been completed.

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

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

.hidden

There's also a member .hidden that gives the count without a function call:

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

.elements

A NodeList of all of the elements that holmes considers. There's also .elementsLength for the amount of elements and .elementsArray with an array of the elements.

.input

The input that holmes looks in. There's also the last search string as .searchString

.placeholder

The current placeholder (DOM Node).

.running

Whether or not this instance is running.

.options

Shows the options chosen chosen for this instance of holmes. You can also set options like this after initialisation.

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

note: setting options after it's running might require h.stop().then(h.start)

Showcase

What who image
bullg.it @haroenv screenshot of bullg.it
family.scss @lukyvj screenshot of family.scss
wikeo.be @bistory searching on wikeo.be for pages
lunchbreakapp.be @AndreasBackx searching on lunchbreak for items

I'd love to find out how people use my project, let me know if you want to be featured!

Questions?

Compatible up to IE11. For support of older browsers you'll need to polyfill classList, addEventListener and the input event with for example remy/polyfills. I haven't tried this myself yet, so let me know what you used if you support older browsers!

For IE11 you need to polyfill Object.assign and String.includes, you can do that as described in #90

Let me know on twitter: @haroenv, or in an issue.

Contributing

Contributions are always welcome! Here are some loose guidelines:

  • use feature branches
  • don't make it slower
  • explain why you want a feature
  • npm run doc to recreate the documentation

Building to a UMD is done via rollup (npm run build).

But I don't bite, if you have any questions or insecurities, hit me up for example on gitter.

License

Apache 2.0

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].