This add-on is operated by Constructor.io

Add autocomplete to your app in minutes.

Last updated 14 April 2016

Constructor.io Autocomplete is an add-on for providing autocomplete functionality to any search bar.

Autocomplete is a seemingly simple feature that’s very difficult to build well. With just a few lines of code, we provide you with autocomplete functionality that:

• is typo-tolerant and corrects spelling mistakes (super important with mobile devices particularly)
• learns over time to rank the suggestions based on popularity
• does this all while being lightning-fast

Setting up the Constructor.io Autocomplete is simple and easy. Just install our Javascript client and then upload your dataset or integrate with one of our client libraries for Ruby, Python, Javascript, PHP, Perl, Java, or C#, or by using our REST API.

Provisioning the add-on

Constructor.io Autocomplete can be attached to a Heroku application via the CLI:

$ heroku addons:create constructor-io
-----> Adding constructor-io to sharp-mountain-4005... done, v18 (free)

Once Constructor.io Autocomplete has been added, two config vars will be available in the app configuration: CONSTRUCTOR_IO_API_TOKEN and CONSTRUCTOR_IO_AUTOCOMPLETE_KEY. CONSTRUCTOR_IO_API_TOKEN is used to add or delete records from the autocomplete index. CONSTRUCTOR_IO_AUTOCOMPLETE_KEY is used with our JavaScript client to identify the autocomplete index you’re using. These variables can be confirmed using the heroku config:get command.

$ heroku config:get CONSTRUCTOR_IO_API_TOKEN
eKm96k0s3fth64Gd93mK

$ heroku config:get CONSTRUCTOR_IO_AUTOCOMPLETE_KEY
mrl4hoWfZP4bJBwxGwtt

After installing Constructor.io Autocomplete the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the CONSTRUCTOR_IO_API_TOKEN and CONSTRUCTOR_IO_AUTOCOMPLETE_KEY values retrieved from heroku config to your .env file.

$ heroku config -s | egrep '(CONSTRUCTOR_IO_API_TOKEN|CONSTRUCTOR_IO_AUTOCOMPLETE_KEY)' >> .env
$ more .env

For more information, see the Heroku Local article.

Using with Rails

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Constructor.io Autocomplete client library.

gem 'constructorio-rails'

Update application dependencies with bundler.

$ bundle install

Add an initializer file at config/initializers/constructor-io.rb

ConstructorIORails.configure do |config|
  config.api_token = ENV['CONSTRUCTOR_IO_API_TOKEN']
  config.autocomplete_key = ENV['CONSTRUCTOR_IO_AUTOCOMPLETE_KEY']
end

To add autocomplete to a model so that updates to its records are sent to Constructor.io to update the autocomplete index:

class MyModel < ActiveRecord::Base
  include ConstructorIORails
  constructorio_autocomplete(['attribute1', 'attribute2'])
end

To attach an autocomplete dropdown to an input field, insert this in your view:

<%= constructorio_autocomplete(dom_id: 'id_of_input_field') %>

To import an existing data set into Constructor.io, you can use the rake task:

rake constructorio:import:model CLASS='MyModel'

Using with other languages

We have client libraries for Ruby, Python, Javascript, PHP, Perl, Java, or C#.

You can include the autocomplete in any HTML code with the following snippet:

<script type="text/javascript" src="//cnstrc.com/js/ac.js"></script>
<script> $('#query').constructorAutocomplete({ key: '[your key]' }); </script>

Just replace #query with the DOM id of your search bar, and [your key] with the CONSTRUCTOR_IO_AUTOCOMPLETE_KEY environment variable.

You can upload data sets for your autocomplete index to our website directly or use our REST API.

Dashboard

The Constructor.io Autocomplete dashboard allows you to view your usage statistics and upload data sets for your autocomplete index.

The dashboard can be accessed via the CLI:

$ heroku addons:open constructor-io
Opening constructor-io for sharp-mountain-4005…

or by visiting the Heroku Dashboard and selecting Constructor.io Autocomplete from the Add-ons menu.

Troubleshooting

If your autocomplete bar is not returning results, please verify that you’re sending the correct autocomplete key to the client. For instance, you can look in the Network tab of Chrome or Firefox’s developer tools window and check the autocomplete_key in the query string of calls to the Constructor.io server.

You can also check the output of the request to the Constructor.io server. If the key is incorrect, you’ll get a message letting you know that.

If the autocomplete response is empty, that means there is not yet any data in your autocomplete index. You can visit your dashboard to upload data sets, or use our REST API to build the index.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade constructor-io:business
-----> Upgrading constructor-io:business to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: constructor-io:business

Removing the add-on

Constructor.io Autocomplete can be removed via the CLI.

$ heroku addons:destroy constructor-io
-----> Removing constructor-io from sharp-mountain-4005... done, v20 (free)

Support

All Constructor.io Autocomplete support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome by emailing info@constructor.io.