Constructor.io Autocomplete
Last updated April 14, 2016
The Constructor.io Autocomplete add-on is currently in beta.
Table of Contents
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:
A list of all plans available can be found here.
$ 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
Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env
file with: echo .env >> .gitignore
.
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
For more information on the features available within the Constructor.io Autocomplete dashboard please see the docs at constructor.io/docs.
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
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
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.
This will destroy all associated data and cannot be undone!
$ 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.