|
AJAX API Reference Documentation
The Truveo AJAX API provides useful functionality for building a wide variety of video search and video browsing applications.
This functionality can be accessed in any web application using JavaScript. As described in the overview
of the AJAX API, the JavaScript class 'TruveoVideoSearch' defines all of the attributes, methods, data objects, and events supported by the
AJAX API. This API interface is detailed below.
Attributes of the TruveoVideoSearch Object
The TruveoVideoSearch object supports several read/write attributes that can be used to configure the settings of the AJAX API.
Assuming that you have created an instance of the TruveoVideoSearch object named 'TVS', these attributes can be accessed as follows.
To set the 'results' attribute, for example, to the value 20, the following JavaScript can be used:
TVS.results = 20;
Similarly, to display the value of this attribute in an alert message, the following JavaScript can be used:
alert(TVS.results);
A complete listing of the supported attributes of the TruveoVideoSearch object is provided in the table below.
|
appid
|
String value. Required.
The Application ID, which is a unique identifier, assigned by Truveo, for your application. To view your current Application ID or request a new one, please consult your My API Account page.
|
|
results
|
Integer between 1 and 50. Optional. Default value of 10.
The number of results the search engine should attempt to return in response to your request.
|
|
start
|
Integer not less than zero. Optional. Default value of 0.
The starting position of the first result, out of the entire set of matching results, that should be returned in response to your request.
|
|
showRelatedItems
|
Integer equal to 0 or 1. Optional. Default value of 0.
The flag which indicates if related tags, channels, categories and users should be included in the results returned in response to your request. A value of 1 indicates that these items should be included, and a value of 0 indicates that they should not.
|
|
tagResults
|
Integer between 1 and 50. Optional. Default value of 10.
The number of related tags the search engine should attempt to return in response to your request. This parameter is only relevant if 'showRelatedItems' is set to 1.
|
|
channelResults
|
Integer between 1 and 50. Optional. Default value of 10.
The number of related channels the search engine should attempt to return in response to your request. This parameter is only relevant if 'showRelatedItems' is set to 1.
|
|
categoryResults
|
Integer between 1 and 50. Optional. Default value of 10.
The number of related categories the search engine should attempt to return in response to your request. This parameter is only relevant if 'showRelatedItems' is set to 1.
|
|
userResults
|
Integer between 1 and 50. Optional. Default value of 10.
The number of related users the search engine should attempt to return in response to your request. This parameter is only relevant if 'showRelatedItems' is set to 1.
|
|
showAdult
|
Integer equal to 0 or 1. Optional. Default value of 0.
The flag which indicates if adult content should be included or excluded in the results returned in response to your request. A value of 1 indicates that adult content should be included, and a value of 0 indicates that adult content should be excluded.
|
Methods of the TruveoVideoSearch Object
The TruveoVideoSearch object exposes several methods that can be used to send AJAX requests to the Truveo video search service.
The available methods are described in the table below.
|
getVideos
|
This method can be used to submit a query to the Truveo video search service. This method returns the set of video results that match the submitted query.
|
|
getRelatedTags
|
This method returns the set of tags that are associated with the videos that match the submitted query.
|
|
getRelatedChannels
|
This method returns the set of channels that are associated with the videos that match the submitted query.
|
|
getRelatedCategories
|
This method returns the set of categories that are associated with the videos that match the submitted query.
|
|
getRelatedUsers
|
This method returns the set of users that are associated with the videos that match the submitted query.
|
|
submitRating
|
This method assigns the submitted rating value to the specified video.
|
|
login
|
This method begins the process for a user to sign in to the Truveo video search service using their AOL or AIM screen name.
|
|
logout
|
This method logs a user out of the Truveo video search service.
|
|
isLoggedIn
|
This method checks if the user is currently logged in to the Truveo video search service.
|
|
getFavoriteVideos
|
This method gets the set of favorite videos for a user.
|
|
addFavorite
|
This method adds a video to the list of favorite videos for a user.
|
|
removeFavorite
|
This method removes a video from the list of favorite videos for a user.
|
|
getRecentVideos
|
This method returns the set of recently viewed videos for a user.
|
|
addRecentVideo
|
This method adds a video to the list of recently viewed videos for a user.
|
|
clearRecentVideos
|
This method clears the list of recently viewed videos for a user.
|
|
getWatchlists
|
This method returns the set of watchlists for a user.
|
|
addWatchlist
|
This method adds a watchlist to the list of watchlists for a user.
|
|
removeWatchlist
|
This method removes a watchlist from the list of watchlists for a user.
|
|
getRecommendedVideos
|
This method returns a set of recommended videos for a user. To personalize recommendations, the user should add to their favorites list and watchlists.
|
|
hasNextPage
|
This method checks to see if an additional page of results is available for the current set of videos.
|
|
hasPreviousPage
|
This method checks to see if a previous page of results is available for the current set of videos.
|
|
nextPage
|
This method retrieves the next page of video search results for the current set of videos.
|
|
previousPage
|
This method retrieves the previous page of video search results for the current set of videos.
|
|
goToPage
|
This method retrieves the specified page of video search results for the current set of videos.
|
|
attachEvent
|
This method attaches the specified handler function to the specified event.
|
|
initialize
|
This method initializes the state of the TruveoVideoSearch object.
|
Data Objects of the TruveoVideoSearch Object
The TruveoVideoSearch object can be used to send AJAX requests and receive responses containing
data from the Truveo video search engine. Every time a response is received, the information contained in
this response is stored in the TruveoVideoSearch object and made accessible through a set of
data objects. By accessing these data objects, it is possible to retrieve video-related information
to use in your application. For example, following a call to the AJAX API getVideos method, the
title of the first video in the response can be displayed in an alert message using the VideoSet data object as follows:
alert(TVS.VideoSet.Video[0].title);
The complete set of data objects that is available through the TruveoVideoSearch object is shown in the table below.
|
VideoSet
|
The container for all of the video records in the set of returned videos.
|
|
TagSet
|
The container for all of the tags associated with the entire set of matching videos. The TagSet is returned only if the parameter 'showRelatedItems' is set to 1.
|
|
ChannelSet
|
The container for all of the channels associated with the entire set of matching videos. The ChannelSet is returned only if the parameter 'showRelatedItems' is set to 1.
|
|
CategorySet
|
The container for all of the categories associated with the entire set of matching videos. The CategorySet is returned only if the parameter 'showRelatedItems' is set to 1.
|
|
UserSet
|
The container for all of the users associated with the entire set of matching videos. The UserSet is returned only if the parameter 'showRelatedItems' is set to 1.
|
|
WatchlistSet
|
The container for all of the watchlists for a user.
|
|
Result
|
The container for the response code, response message and any other information returned in this response.
|
Events of the TruveoVideoSearch Object
The TruveoVideoSearch object provides an asynchronous interface to the Truveo video search service. As a result, any calls to
the methods of this object will be non-blocking. In other words, these method calls will return immediately, however
the response to each request will be received at a later time. In order to handle responses received by the AJAX API,
the TruveoVideoSearch object exposes a set of events. These events can be used by your application to trigger specific
actions that should be taken in response to information retrieved by the AJAX API. The following code sample illustrates
how an event handler function called 'myHandler' can be attached to the 'onupdate' event of the TruveoVideoSearch instance
named 'TVS':
TVS.attachEvent('onupdate', 'myHandler(methodName);');
The complete set of events that can be fired by the TruveoVideoSearch object is shown in the table below. Additional information
about each event can be found in the reference documentation for the methods of the AJAX API.
|
onload
|
This event fires when the TruveoVideoSearch object
initialization is complete. When this event fires, it will pass one argument, 'reloadStateFlag', to any handler attached to this event. The value
of 'reloadStateFlag' will be true if the TruveoVideoSearch object was just initialized following a return from the AOL account login page.
|
|
onupdate
|
This event fires when a response to an AJAX request
is received by the TruveoVideoSearch object. When this event fires, it will pass one argument, 'methodName', to any handler attached to this event. The value
of 'methodName' will be set to the name of the method that issued the original AJAX request associated with this onupdate event.
|
|
onerror
|
This event fires when an error occurs.
When this event fires, it will pass two arguments, 'errorCode' and 'errorMessage', to any handler attached to this event. The value
of 'errorCode' will be the numerical code assigned to the error and 'errorMessage' will be a text message that describes the error.
|
|
