VL Group

Rhymba v3.6 Documentation

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.

  1. First get yourself a current version of jQuery, because it's great, and also because the Rhymba javascript libraries need it to work.
  2. 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.
  3. 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]
    	});
    	
    
    But if you prefer things jQuery-flavored, you can have it that way as well:
     
    	var $searchFieldSet = $("[YourTargetInput]").rhymbaSearchField({
    		token: "[YourContentToken]"
    	});
    	
    
  4. 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
mySearchField.terms("Fifth Symphony");
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
mySearchField.submit("Sixth Symphony");
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
mySearchField.cancel("Fourth Symphony")

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
mySearchField.onSubmit(function(event){
	console.log(event.data.terms);
});
onResult function( event ) Invoked when results for a give search term are received. string
mySearchField.onResult(function(event){
	console.log(event.data.results);
});
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
mySearchField.onCancel(function(event){
	console.log(event.data.terms);
});
onError function( event ) Invoked if a search AJAX request results in an error. string
mySearchField.onError(function(event){
	console.log(event.data.terms);
});
removeEventListener string Cancels an existing event handler callback based on its token.
myPlayer.removeEventListener("23")