fancy 1.0.0-alpha

Released 2015-10-26.

To install, run:

haxelib install fancy 1.0.0-alpha

See using Haxelib in Haxelib documentation for more information.

Maintainermlms13
Websitehttps://github.com/mlms13/FancySearch
Current version1.0.0-alpha
StatisticsInstalled 12 times
LicenseMIT
Tags browser, js, search, typeahead

README.md

Fancy Search

Fancy Search is a typeahead search implementation for the web. It is written in Haxe and compiles to a JavaScript target. The library can be imported and used directly in Haxe projects, or it can be bundled into JavaScript projects using CommonJS (coming soon).

The result may look something like the following, or you can just try out a live demo.

Fancy Search screen capture

Getting Started

With Haxe

Grab the latest version of the library from Haxelib:

haxelib install fancy

Import the Search module, create a new instance, and away you go.

import fancy.Search;

class Main {
  static function main() {
    var search = Search.createFromSelector(".some-selector input", {
      suggestionOptions : {
        suggestions : ["Apple", "Banana", "Barley", "Black Bean", "Carrot", "Corn"]
      }
    });
  }
}

For a slightly larger example, see the demo in this repository.

With JavaScript

FancySearch has not yet been published to npm. Soon...

API Documentation

You can find more complete documentation on RawGit, but the following should be enough to get started.

Search

The Search class is the main entry point. When creating a new instance, you must provide an input element, and you may provide an options object (see FancySearchOptions below).

var inputEl = js.Browser.document.querySelector("input.my-input");
var mySearch = new Search(cast inputEl, {/* some options... */});

Alternatively, if you don't have a handy reference to your input element, you can create a Search instance from either a string selector, or from a parent container:

var mySearch = Search.createFromSelector("input.my-input", {});
// or...
var container = js.Browser.document.querySelector(".some-div");
var mySearch = Search.createFromContainer(container, {});

Regardless of how you create it, you'll end up with a Search instance that has only one public field: mySearch.list. The list is a reference to an instance of Suggestions that gets created automatically when you create an instance of Search.

Suggestions

A Suggestions instance is automatically created when you create a Search. Because of this, you shouldn't ever need to interact with its constructor directly. However, the instance does provide some public function which may be helpful:

  • mySearch.list.setSuggestions(suggestions : Array<String>)
    Change the list of suggestions after initialization by providing this method with a list of strings.
  • mySearch.list.filter(search : String)
    Given a string of text (usually this matches the value of the input), this method will re-filter the suggestion list. Your Search instance is already set up to handle this when the input's value changes, but you can call it directly if needed.
  • mySearch.list.open(), mySearch.list.close()
    Open or close the suggestion dropdown list by adding the appropriate class.
  • mySearch.list.selectItem(?key : String)
    Changes the selection in the suggestion dropdown to a given item. If no key is provided, the selection will be cleared.
  • mySearch.list.moveSelectionUp(), mySearch.list.moveSelectionDown()
    Changes the selection in the dropdown list to the previous or next list item.
  • mySearch.list.chooseSelectedItem()
    Calls the optionally-provided onChooseSelection function with the input and selection text. This happens on click and when the Enter key is pressed.

FancySearchOptions

The following options may be passed to the Search constructor. Any of these options may be omitted.

NameDefaultDescription
classesAllows overriding the default class names
clearBtnTrueWhether to show a clear button when the input is not empty
containerinput.parentElementElement containing the search input
keysNamed keyboard actions map to an array of keycodes
minLength1How many characters must be entered before suggestions will show
onClearButtonClickAction to be performed when the clear button is clicked
suggestionOptionsOptions that will be passed to the Suggestions constructor

SuggestionOptions

The following options may be passed to the Suggestions constructor. Any of these options may be omitted.

NameDefaultDescription
filterFnCustom function for filtering search suggestions
highlightLettersFnCustom function to determine which letters should be highlighted in the list of suggestions
limit5Max number of suggestions to show in the dropdown
onChooseSelectionFunction determines what happens when a selected item is chosen
inputProvided by Search, required for creating Suggestions
parentAlso provided by Search and required
showSearchLiteralItemFalseWhether the "Search for <literal text>" suggestion will be shown
searchLiteralPositionFirstFirst or Last determines where the literal suggestion is placed
searchLiteralValueFunction that provides literal search text given an InputElement
searchLiteralPrefix"Search for: "Text that comes before the literal search text
suggestions[]List of suggestion strings

Styling and Customization

Fancy Search is not opinionated when it comes to styles. In fact, most of the basic functionality (showing and hiding the suggestion list, for example) is the result of changing classes rather than hard-coded styles. This means that without some style guidance, Fancy Search probably won't behave the way you expect it to. A simple CSS example is provided to give you a starting point.