Search Field Generator
Search-As-You-Type is one of the most common use cases for the Rhymba Search AJAX Client, and one we've encountered so often that we wrote a user-interface script just for it. Using it, you can turn any text input into a Search Field for the Rhymba OData Search API in just a few steps.
- First get yourself a current version of jQuery, because it's great, and also because the Rhymba javascript libraries need it to work.
- Second, add the Rhymba Search script at this link to your page. We recommend adding it shortly before your closing </body> tag so that it won't get in the way of your page's content.
-
Now pay close attention, because there are a couple of variations in how to create your Search Field.
If you like things nice and object-oriented, you can use a conventional constructor function:
var mySearchField = rhymba.search.SearchField({ token: "[YourContentToken]", element: [YourTargetInput] });
var $searchFieldSet = $("[YourTargetInput]").rhymbaSearchField({ token: "[YourContentToken]" });
-
Of course, you probably want to be able to do something once your user's search results come in. That's why the Search Field gives you event callbacks for when searches are submitted, completed, or get cancelled. You can assign these callback functions when you create your Search Field as configuration options, or you can add (and remove) them later. Check it out:
//* Adding event callbacks on construction var mySearchField = rhymba.search.SearchField({ token: "[YourContentToken]", element: [YourTargetInput], onSubmit: function(event){ console.log("Submitting search: " + event.data.terms); }, onResult: function(event){ console.log("Search Results For: " + event.data.terms); } }); //* Adding event callbacks later var myCallbackToken = mySearchField.onCancel(function(event){ console.log("Cancelled search: " + event.data.terms); }); //* And removing them mySearchField.removeEventListener(myCallbackToken);
The Rhymba Search Field
The Rhymba Search Field is highly configurable, giving you the ability to create a Search Field that performs exactly as you need.
Options
Field Name | Type | Description | Example |
---|---|---|---|
token | string | A javascript string containing your Rhymba Access Token. Required. |
token: "[YourRhymbaAccessToken]"
|
element | Text Input | A Text Input to use as the source of input for Rhymba searches. Note: This value is required if creating your Search Field directly using the 'rhymba.search.SearchField' method, but will be populated automatically if you use the jQuery plugin. |
element: $("#mySearchField") |
autoSubmit | boolean | Indicates whether to automatically execute searches as a user types into the input element. |
autoSubmit: true |
beforeSubmit | function(term, searchField) | A function to be invoked prior to submitting any search terms to the Rhymba Search API. The function will be passed two arguments: the term being searched for, and the Search Field instance. If the 'beforeSubmit' function returns a string, that string will be searched for instead. If it returns false, the search will not be submitted. |
beforeSubmit: function(term, searchField){ if(term === "A Band You Don't Like") { return false; } } |
endpoints | array[string] | An array of strings or a whitespace-delimited string indicating which Rhymba Search Endpoints to include when executing your searches. |
endpoints: ['media', 'artists', 'albums'] |
simultaneousEndpoints | number | The number of Rhymba Search endpoints to query simultaneously when executing your searches. '0' indicates no limit and is the default value. |
simultaneousEndpoints: 0 |
debounce | number | The time in milliseconds to wait after a user completes typing before beginning to execute a search. This gives them time to hit 'backspace' and prevents initiating numerous searches for incomplete terms. '300' is the default value. |
debounce: 300 |
minLength | number | The minimum number of characters a user must enter before searches begin to be submitted automatically. |
minLength: 3 |
triggerEvents | array[string] | An array of strings or whitespace-delimited string indicating which DOM events should trigger automatic submission when dispatched by the input element. If the autoSubmit option is false, these events will set the Search Field's search terms, but not automatically execute the search. |
triggerEvents: ['input'] |
triggerKeys | array[number] | A number or array of numbers indicating the keyCodes of keys that should submit the search when pressed. These keys will trigger searches even if autoSubmit is false. The default is '13', the Enter key. |
triggerKeys: [13] |
cache | number | The time, in milliseconds, to keep Rhymba Search results for a given search term in memory. After this time, subsequent searches for the same term will result in new Search API requests. The default value is ten minutes (600,000 milliseconds). |
cache: 600000 |
any Event Handler | function(event) | Any of the Rhymba Search Field's Event Handlers can be included as a construction option. |
onResult: function(event){ console.log(event.data.results); } |
Search Field Methods
Name | Arguments | Description | Returns | Example |
---|---|---|---|---|
terms | string | Gets or Sets the current search term. If the 'autoSubmit' option is true, the search will execute immediately. Always returns the current search term. | string |
|
submit | string | Immediately submits the current search term. If invoked with an argument, that string will be set as the current term. Returns true if the term was submitted, or false if the term is too short or if any 'beforeSubmit' function vetoes the term. | boolean |
|
cancel | string | If invoked with an argument, aborts any pending search for that term. If invoked without any argument, aborts all pending and active searches. Returns true if any searches were cancelled. | boolean |
|
Event Handlers
The Rhymba Search Field emits a variety of events reflecting changes in the status of new and ongoing searches. Callback functions for these events can be assigned using the convenience methods listed here, or as construction options. You can assign as many callback functions to a given event as you need, and release them later using the .removeEventListener() method: all of the methods below return a numeric string identifying the particular callback-function + event-type pairing created, so when you don't need that callback any longer, you can use the token with .removeEventListener() to get rid of it.
Callback functions will be invoked with an event argument containing details about the related search. These details are stored in the event's .data property.
Name | Arguments | Description | Returns | Example |
---|---|---|---|---|
onSubmit | function( event ) | Invoked once the Rhymba Search Field submits a new search. | string |
|
onResult | function( event ) | Invoked when results for a give search term are received. | string |
|
onCancel | function( event ) | Invoked when a search is cancelled. Searches can be cancelled either manually, using the .cancel() method, or automatically if a beforeSubmit function returns false. | string |
|
onError | function( event ) | Invoked if a search AJAX request results in an error. | string |
|
removeEventListener | string | Cancels an existing event handler callback based on its token. |
|