Have ideas to improve npm?Join in the discussion! »

    @usig-gcba/autocompleter

    2.1.5 • Public • Published

    Autocompleter

    Warning: Version 2.0.0 contains potentially breaking changes for frontend projects. Please refer to the demo to see how to implement the newest version.

    This autocompleter is a library which gives a list of suggestions given a certain text. This is done using a list of suggesters, which can be loaded dinamically, in case you don't want to use one of the defaults. A set of callbacks should be set so the autocompleter can call them after certain events.

    Features

    • Add suggesters with personalized functionality.
    • Subscribe to events by passing callbacks for different events.
    • Override the default options.
    • Look up suggestions for a given text.
    • Get the global state at any time.

    Demos

    A simple create-react-app can be found in demo/react-demo with an example showing how the module can be used in a React environment.

    Also, an Angular CLI app can be found in demo/angular-demo showing integration in this framework.

    Getting started

    1. Installing the library
    • Run npm install @usig-gcba/autocompleter command in your project root.
    1. Import the library
    • Add the import tag in your file import {Autocompleter} from '@usig-gcba/autocompleter'
    1. Create a new instance
    • Just use the new command to create a new instance const autocompleter = new Autocompleter(callbacks, options). You can save it in a variable for further use.

    Configuration

    constructor

    • Creates a new instance of the autocompleter.

    • Parameters:

      • callbacks: Object containing the callbacks for event handling. Here's a list of all the possible callbacks:
        • OnSuggestions: called when a suggester brings new suggestions. Returns the list of results.

          Note: If a suggester brings 0 results, the onSuggestions callback won't be called.

        • OnCompleteSuggestions: called when all the active suggesters are done.
        • OnMessage: called when a message should be displayed (for example, no results were found).
        • OnError: called when an error occurred in any of the suggesters.
        • OnUpdate: called every time the state of the autocompleter changes.
        • OnBufferResults: if a flushTimeout is set, the autocompleter will buffer the results calling this callback.
      • options: Object containing default options to be overwritten. Available options:
    Parameter Description Default
    inputPause Time each suggester waits before looking for suggestions 200
    maxSuggestions Total limit of suggestions 10
    serverTiemout Timeout in case an http call is made 3000
    minTextLength Minimun text length in order to start looking for suggestions 3
    maxRetries Maximum retries in case of failure 1
    flushTimeout Time to wait before flushing results from suggesters. 0
    • Example
    const autocompleter = new Autocompleter(
          {
             onSuggestions: suggestionsCallback,
             onUpdate: updateCallback,
             onError: errorCallback,
             onMessage: messageCallback
           },
           {
             inputPause: 400,
             maxRetries: 2
           }
    );
    

    addSuggester(suggesterName)

    • By default, the autocompleter initializes empty. This method adds a suggester for the autocompleter to use when updating suggestions.

    • Parameters:

      • suggesterName: String name of the suggester.
    • The name must be a valid suggester name. By default, 4 suggesters are registered in the autocompleter:

      • "Direcciones"
      • "DireccionesAmba"
      • "Lugares"
      • "DeficitHabitacional"
      • "Catastro"

    updateSuggestions(text)

    • Calls the getSuggestions function in all the active suggesters.

    • Parameters:

      • text: String to be searched.

    updateCoordenadas(suggestions)

    • Calls the coordinates of an endpoint of normalized directions for CABA and AMBA suggestions.

    • Parameters:

      • suggestions: String to be searched.

    getSuggestionPromises(suggestion)

    • Some suggestions getted in the callback onSuggestions are affected by promises, these promises can be obtained using this method.

    removeSuggester(suggesterName)

    • Removes a suggester from the autocompleter. This suggester will still be a valid one, but the autocompleter won't take it into account when updating suggestions.

    • Parameters:

      • suggesterName: String name of the suggester.

    Suggesters

    The suggesters contain the core functionality of the autocompleter. They are in charge of looking for suggestions. Up next is a list of the suggesters available by default.

    Default suggesters

    Directions

    This suggester looks for directions inside the City of Buenos Aires. So, for the input text we give to the autocompleter, the suggester looks for directions matching that text.

    AMBA Directions

    This suggester looks for directions inside AMBA.

    Places of interest

    This suggester looks for places inside the City of Buenos Aires (airports, museums, parks, entertainment).

    Vulnerable Areas

    This suggester looks for vulnerable areas inside the City of Buenos Aires.

    Cadastre

    This suggester allows locating a coordinates from its smp, in format: seccion-manzana-parcela, inside the City of Buenos Aires.

    Adding a custom suggester

    You can see an example of a suggester that can be used as a template here

    Custom suggesters can be added via de addSuggester function. This function can take either a String or an Object as parameters.

    • Parameters:
      • String containing the name of the suggester to be added. In this case, the suggester should be already registered in the autocompleter.
      • Object containing the suggester to be added. In this case, we are registering a new type of sugester to the autocompleter.

    Suggester structure

    Any new suggester added should implement all the Suggester methods. The library exports the Suggester interface, so a custom class can be created extending from this one.

    Example
    import {Suggester} from '@usig-gcba/autocompleter'
    
    class MySuggester extends Suggester {
      getSuggestions(text, callback, maxSuggestions){
          callback([...results]);
      }
    }
    

    Troubleshooting

    If you are trying to implement Autocompleter in an Angular project, you will have to install @babel/polyfill and import it at your app.component.ts file as can be seen in the angular demo.

    Install

    npm i @usig-gcba/autocompleter

    DownloadsWeekly Downloads

    99

    Version

    2.1.5

    License

    USIG

    Unpacked Size

    99.8 MB

    Total Files

    22987

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar