| eBay JavaScript SDK Resources: | Tutorial | JSDocs | eBay JavaScript SDK |
Welcome to the eBay JavaScript SDK
Anatomy of a JavaScript Component
Including the Required Resources in Your Widget
Overview of the eBay API Structure
Example - Portions of the Item Badge Widget
Example - Implementing a Callback Function
Deploying a Widget that Contains Input Values
Using Your Scripts in a Wiki Page or Blog
The JavaScript SDK will allow you to create an interactive JavaScript UI component that can access data on the eBay Shopping API Servers.
To create a JavaScript component:
<SCRIPT TYPE='text/javascript' SRC='http://w-1.ebay.com/js/2.2/min/Shopping.js'/></SCRIPT>NOTE: The /min/ part of URL path above means the file is minified. Non-minified files are located under /js/2.2/src/...
<SCRIPT TYPE='text/javascript'> com.ebay.widgets.needs(/*com.ebay.widgets.util.Resource*/);</SCRIPT>NOTE: Steps 3-7 below are added to the <SCRIPT> tag defined in step 2. The variations of com.ebay.widgets.needs(...) are explained in a later section.
var config = new com.ebay.shoppingservice.ShoppingConfig({appId: 'YOUR APPID'});
var shopping = new com.ebay.shoppingservice.Shopping(config);
var callback = new com.ebay.shoppingservice.ShoppingCallback({success: onSuccess, failure, onFailure});
shopping.findItems({QueryKeywords: "ipod"}, {success: onSuccess, failure: onFailure});
NOTE: The second parameter is an object literal. You could alternatively provide an instance of the class: com.ebay.shoppingservice.ShoppingCallback.
This class is detailed in a later section.
<!-- Blog, Social Home Page, etc -->
<HTML>
<HEAD>
<script TYPE='text/javascript' SRC='http://w-1.ebay.com/js/2.2/min/Shopping.js'></script>
</HEAD>
<BODY>
<script TYPE='text/javascript'>
function onSuccess(/*com.ebay.shoppingservice.FindItemsResponseType*/ data) {
}
function onFailure(/*[com.ebay.shoppingservice.ErrorType]*/ errors) {
}
com.ebay.widgets.needs(/*com.ebay.widgets.util.Resource*/ {
baseUrl: 'http://w-1.ebay.com/js/2.2/min',
files: ['FindItems.js'],
resources: com.ebay.shoppingservice.Shopping.findItems,
callback: function() {
var config = new com.ebay.shoppingservice.ShoppingConfig({appId: 'YOUR APPID'});
var shopping = new com.ebay.shoppingservice.Shopping(config);
var request = new com.ebay.shoppingservice.FindItemsRequestType({QueryKeywords: 'ipod'});
var callback = new com.ebay.shoppingservice.ShoppingCallback({success: onSuccess, failure, onFailure});
shopping.findItems(request, callback);
}
});
</BODY>
</HTML>
This section describes the basic sections that a JavaScript SDK program must contain to work successfully. As long as your script contains these elements (with the correct syntax), and is deployed like a standard JavaScript program, you can substitute other SDK calls for the ones in these examples, and you can display the results in numerous ways.
In this manual, we will begin with a simple widget embedded within an html page, called FindItemsAdvancedSample.html as a guide, to help you become familiar with the basics of eBay JavaScript widget development.
The following diagram shows the elements that your script should contain:
The following example shows the code for some of the these elements:
//Include the following within the header
<script TYPE='text/javascript' SRC='http://w-1.ebay.com/js/2.2/min/Shopping.js'></script>
//Within the body include the following:
<script TYPE='text/javascript' SRC='ItemListUI.js'></script>
<script type="text/javascript" src="FindItemsAdvancedSample.js"></script>
<script TYPE='text/javascript'>
com.ebay.widgets.needs({
baseUrl: 'http://w-1.ebay.com/js/2.2/min',
files: [FindItemsAdvanced.js],
resources: com.ebay.shoppingservice.Shopping.findItemsAdvanced,
callback: function() {
image = 'http://w-1.ebay.com/images/stockimage1.jpg';
FindItemsAdvancedSample.goSearch({g_queryKeywork: "iPod"});
}
});
Back to Top
The 2.2 JavaScript SDK provides on-demand downloads of javascript classes that are needed to invoke the Shopping Web Service methods. These classes can be downloaded in several ways.
If you look in the /src folder in your JavaScript SDK, you will see these call-specific .js files.
Since each of the Shopping Web Service calls is available as a .js file, you can easily create an application that
incorporates any of these calls, without writing them from scratch. Each call-specific .js file instantiates the
types used by that call.
Within the src/com/ebay/shoppingservice directory, you will see all of the type files used by the
eBay Shopping Web Service (in the form of .js files). You can either store all of the shoppingservice
directory files locally, or link to the Shopping Web Service within your .html file.
We have provided the dynamic download methods because the time to download one file which contains all classes is significantly greater than the time to download each file containing a single class. See Yahoo's YSlow Firefox plugin for an example of dynamic download times.
com.ebay.widgets.needs({
baseUrl: 'http://w-1.ebay.com/js/2.2/min',
resources: com.ebay.shoppingservice.Shopping.findItemsAdvanced, // static array
callback: function() {
// code to invoke Shopping service methods
}
});
com.ebay.widgets.needs({
baseUrl: 'http://w-1.ebay.com/js/2.2/min',
files: ['FindItemsAdvanced.js'],
resources: com.ebay.shoppingservice.Shopping.findItemsAdvanced,
callback: function() {
// code to invoke Shopping service methods
}
});
If you want or need to run your applications without dynamically downloading the JavaScript class and type files, you can Store the .js type classes (included in the JavaScript SDK download) locally, and reference them directly by including them in the needs statement.
The example below shows how to include all of the .js files that you will need to perform any of the calls for the Shopping Web Service. Note that these files are not all located in the same directory or package within the download:
com.ebay.widgets.needs({
baseUrl: 'http://w-1.ebay.com/js/2.2/min',
files: ['FindItemsAdvanced.js'],
resources:
[
'com.ebay.widgets.util.Duration',
'com.ebay.widgets.io.Factory',
'com.ebay.widgets.io.XSSRequest',
'com.ebay.shoppingservice.Utils',
'com.ebay.shoppingservice.AbstractRequestType',
'com.ebay.shoppingservice.AbstractResponseType',
'com.ebay.shoppingservice.AckCodeType',
.
.
.
.
'com.ebay.shoppingservice.SortOrderCodeType',
'com.ebay.shoppingservice.StoreSearchCodeType',
'com.ebay.shoppingservice.StorefrontType',
'com.ebay.shoppingservice.TaxJurisdictionType',
'com.ebay.shoppingservice.TaxTableType',
'com.ebay.shoppingservice.TradingRoleCodeType',
'com.ebay.shoppingservice.UserStatusCodeType',
'com.ebay.shoppingservice.Shopping',
'com.ebay.shoppingservice.ShoppingConfig'
],
callback: function() {
// code to invoke Shopping service methods
}
});
To make it easier for you to include all of the dependencies for a specific Shopping class method, we have included files that contain dependent classes and types for each method. The table below shows the mapping and location of the URI's which include the classes required to call a Shopping method.
| Method/TH> | Minified File with Classes Included | Non-Minified File with Classes Included |
|---|---|---|
| findHalfProducts | /js/2.2/min/FindHalfProducts.js | /js/2.2/src/FindHalfProducts.js |
| findItems | /js/2.2/min/FindItems.js | /js/2.2/src/FindItems.js |
| findItemsAdvanced | /js/2.2/min/FindItemsAdvanced.js | /js/2.2/src/FindItemsAdvanced.js |
| findProducts | /js/2.2/min/FindProducts.js | /js/2.2/src/FindProducts.js |
| getItemStatus | /js/2.2/min/GetItemStatus.js | /js/2.2/src/GetItemStatus.js |
| getMultipleItems | /js/2.2/min/GetMultipleItems.js | /js/2.2/src/GetMultipleItems.js |
| getShippingCosts | /js/2.2/min/GetShippingCosts.js | /js/2.2/src/GetShippingCosts.js |
| getSingleItem | /js/2.2/min/GetSingleItem.js | /js/2.2/src/GetSingleItem.js |
| getUserProfile | /js/2.2/min/GetUserProfile.js | /js/2.2/src/GetUserProfile.js |
| findPopularItems | /js/2.2/min/FindPopularItems.js | /js/2.2/src/FindPopularItems.js |
| findPopularSearches | /js/2.2/min/FindPopularSearches.js | /js/2.2/src/FindPopularSearches.js |
| findReviewsAndGuides | /js/2.2/min/FindReviewsAndGuides.js | /js/2.2/src/FindReviewsAndGuides.js |
| getCategoryInfo | /js/2.2/min/GetCategoryInfo.js | /js/2.2/src/GetCategoryInfo.js |
| geteBayTime | /js/2.2/min/GeteBayTime.js | /js/2.2/src/GeteBayTime.js |
This section gives you an overview of what you need to know to get started, and provides resources and links to other parts of the JavaScript Widget documentation.
In order to create JavaScript widgets, you only need a text editor, an .html page, and an internet browser. However, if you want to deploy your widgets after you create them, you will need to have access to a working .html page. This means that you will need to have a web site where you can host the widget, or you will need to have someone else host your widget where you can access it through a URL.
Note that knowledge of JavaScript is required to implement your callback function. Some knowledge of error handling is recommended, but you can use code that is similar to what is presented in the samples and tutorials. Knowledge of JSON is not required, but the link is provided here for your convenience.
The following table describes the resources that we have provided to help you learn about creating JavaScript widgets. Click the links within the table to become familiar with any of the resources listed in the table.
| Resource | Link(s) | Description |
|---|---|---|
| JavaScript SDK .zip File | eBay JavaScript SDK | This is the bundle of JavaScript SDK files. It includes: Documentation, source code, and samples. If you have not already downloaded this file, please download it now. |
| JavaScript SDK Readme File | README | This document discusses the JavaScript SDK in general, what is included, how to download the SDK, recommended steps to follow, migration issues, other known issues, and SDK license information. |
| JavaScript SDK Developer Guide | you are here | (THIS guide.) This is the overview of the JavaScript SDK. It includes a general description of how to create and deploy an eBay JavaScript widget and provides links to related resources. |
| JavaScript Widget Tutorials | Widget Tutorials | To give you hands-on experience with the JavaScript SDK, in case you would like a more in-depth understanding before creating your own widgets. |
| Sample Widget Center | Sample Widget Center | Allows you to create the JavaScript code to imbed an existing eBay widget into an .html page. |
| JSDoc (library reference) | JSDocs | To help you understand the call structure and parameters for each of the classes provided with the JavaScript SDK. |
| Shopping Web Services Call Reference | Shopping Web Services Call Reference | To help you understand what the SDK calls are retrieving from the eBay API servers. |
| Getting Started with eBay Shopping Web Services | Shopping Web Services Getting Started Guide | To give you an overview of the eBay Shopping API and how it is related to other eBay services. |
| eBay Shopping Web Services Tutorial | Shopping Web Services Tutorial | To give you hands-on experience with the eBay Shopping API, in case you would like a more in-depth understanding before creating widgets. |
| JavaScript Information | JavaScript | To help you understand the JavaScript document methods and learn how to display your returned data in an interface format. When using the SDK, you will need to implement a JavaScript display function - there is no display interface class in the kit, because each developer will want to create their own implementation, depending on what they're creating. |
| JSON Information | JSON | To increase your understanding of the JSON request and response methods that are used to send and retrieve data from the eBay API servers. |
eBay is continually expanding and specializing the API libraries so that developers can build applications with the exact calls they need. Currently, there are two main libraries: the Trading API (original API that uses tokens for calls) and the Shopping API (tokenless calls).
The JavaScript SDK gives you the ability to create scripts that retrieve data from the eBay Servers. The JavaScript objects that you will use correspond to the calls in the eBay Shopping API. This means that you can make any of the supported calls without having to include a token. However, you still have to get an Application ID (AppID) from the ebay.developer.com site and include it in your calls to the eBay API server.
To create a JavaScript widget with this SDK, you need to instantiate an Shopping object, passing in data, such as the application id (AppID), site id, and affiliate tracking information, using the ShoppingConfig object.
If you do not already have an eBay Application ID, you can get one here.
The Shopping class requires a ShoppingConfig object in order to instantiate and its instantiation is generalized for the JavaScript bindings:
var config = new com.ebay.shoppingservice.ShoppingConfig({appId: ‘yourappid’, siteId: 0});
var shopping = new com.ebay.shoppingservice.Shopping(config);
The Shopping service methods match the same-named WSDL operations with the exception that
they begin with a lowercase character to adhere to JavaScript common naming
conventions. Each method takes an input object that corresponds to the
<wsdl:input message=‘methodName’/> WSDL tag.
As an example, invoking a method that matches the WSDL operation of ‘FindItems’ looks
like the following:
var config = new com.ebay.shoppingservice.ShoppingConfig({appId: ‘yourappid’, siteId: 0});
var shopping = new com.ebay.shoppingservice.Shopping(config);
var request = new com.ebay.shoppingservice.FindItemsRequestType({QueryKeywords: "ipod"});
var callback = new ShoppingCallback({object: this, success: this.onSuccess, failure: this.onFailure});
shopping.findItems(request, callback)
The onSuccess and onFailure above are references to global functions that receive the FindItemsResponseType or an array of ErrorType types respectively. Note that object literals can be used to shorten the amount of code required to invoke the method above. Using object literals, the javascript example becomes just 2 lines:
var shopping = new com.ebay.shoppingservice.Shopping({appId: ‘yourappid’, siteId: 0});
shopping.findItems({QueryKeywords: "ipod"}, {success: onSuccess, failure: onFailure});
Note: all input is normalized to match what is exposed in the WSDL.
The classes that are autogenerated for both JavaScript and ActionScript following similar naming conventions and usage. Unlike the WSDL elements and enumerations, the JavaScript names have been changed to begin with a lowercase character for naming conventions. However they accept either upper or lower case for assignment. For example:
new com.ebay.shoppingservice.FindItemsRequestType({QueryKeywords: 'ipod'});
or
new com.ebay.shoppingservice.FindItemsRequestType({queryKeywords: 'ipod'});
To see the similarity of the WDSL complexType and the associated class we can look at the AbstractRequestType. The class contains 2 member attributes: messageID and any. Its definition is as follows:
/**
@name AbstractRequestType
@fileOverview Base type definition of the request payload, which can carry
any type of payload content plus optional versioning information and detail
level requirements. All concrete request types are derived from the abstract
request type. The naming convention we use for the concrete type names is the
name of the service (the verb or call name) followed by "RequestType":
VerbNameRequestType
*/
com.ebay.widgets.createClass('com.ebay.shoppingservice.AbstractRequestType')
.methods({
/**
@type String
If you pass a value in MessageID in a request, we'll return the same value in
CorrelationID in the response. If you're making a lot of calls, you can use
this for tracking that a response is returned for every request and to match
particular responses to particular requests. (In this case, specify a different
value for each request.) You can specify any value that is useful to you.
*/
messageID: null,
any: null,
constructs: function (props) {
this.messageID = props.MessageID || props.messageID;
this.any = props.any;
}
});
The WSDL complexType is below:
<xs:complexType name="AbstractRequestType" abstract="true"> <xs:annotation> <xs:documentation> Base type definition of the request payload, which can carry any type of payload content plus optional versioning information and detail level requirements. All concrete request types are derived from the abstract request type. The naming convention we use for the concrete type names is the name of the service (the verb or call name) followed by "RequestType": VerbNameRequestType </xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="MessageID" type="xs:string" minOccurs="0"> <xs:annotation> <xs:documentation> If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you. </xs:documentation> <xs:appinfo> <MaxLength/> <CallInfo> <AllCalls/> <RequiredInput>No</RequiredInput> </CallInfo> </xs:appinfo> </xs:annotation> </xs:element> <xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>
The SortOrderCodeType is shown below:
/**
@name SortOrderCodeType
@fileOverview Indicates the order of sorting.
*/
com.ebay.widgets.createClass('com.ebay.shoppingservice.SortOrderCodeType')
.props({
Ascending: null,
Descending: null,
CustomCode: null
})
.methods({
constructs: function (object) {
this.value = object.hasOwnProperty('value')? object.value: object;
},
toString: function() {
return this.value;
},
toJSONString: function() {
return this.value;
}
})
.inits(function() {
com.ebay.shoppingservice.SortOrderCodeType.Ascending = new com.ebay.shoppingservice.SortOrderCodeType("Ascending");
com.ebay.shoppingservice.SortOrderCodeType.Descending = new com.ebay.shoppingservice.SortOrderCodeType("Descending");
com.ebay.shoppingservice.SortOrderCodeType.CustomCode = new com.ebay.shoppingservice.SortOrderCodeType("CustomCode");
});
The associated WSDL simpleType is as follows:
<xs:simpleType name="SortOrderCodeType"> <xs:annotation> <xs:documentation> Indicates the order of sorting. </xs:documentation> </xs:annotation> <xs:restriction base="xs:token"> <xs:enumeration value="Ascending"> <xs:annotation> <xs:documentation> Sorts results in ascending (low to high) order. </xs:documentation> </xs:annotation> </xs:enumeration> <xs:enumeration value="Descending"> <xs:annotation> <xs:documentation> Sorts results in descending (high to low) order. </xs:documentation> </xs:annotation> </xs:enumeration> <xs:enumeration value="CustomCode"> <xs:annotation> <xs:documentation> Placeholder value. See <a href="types/simpleTypes.html#token">token</a>. </xs:documentation> </xs:annotation> </xs:enumeration> </xs:restriction> </xs:simpleType>
This sample includes code snippets from a more elaborate widget that is included in the JavaScript SDK. You can see some of the syntax and structure of the Shopping functions in this complex widget code. The entire widget is located in the ItemBadgeWidget.js file within the .zip file for the JavaScript SDK.
//ItemBadgeWidget calls the Shopping service twice. First, it calls findItems
//to find items using a specific keyword. Then, it will call getSingleItem to
//get item details using a specific item id (the id of the first item returned
//by findItems).
this.getItem = function () {
var service = new com.ebay.shoppingservice.Shopping(this.config);
var fiRequest = new com.ebay.shoppingservice.GetSingleItemRequestType({itemID: this.itemID,
includeSelector: "Details"});
var url = service.getSingleItem(fiRequest, {object: this, success: this.displayItem, failure: this.displayError});
};
this.findItems = function()
{
if (typeof(this.keyword) !== undefined && this.keyword !== "")
{
var service = new com.ebay.shoppingservice.Shopping(this.config);
var fiRequest = new com.ebay.shoppingservice.FindItemsRequestType({queryKeywords: this.keyword,
itemSort: com.ebay.shoppingservice.SimpleItemSortCodeType.EndTime,
maxEntries:10});
var url = service.findItems(fiRequest, {object: this, success: this.filterResults, failure: this.displayError});
}
};
You can implement one of the parse methods from the data object classes to handle the data once it is returned.
The JavaScript SDK does not include an interface for displaying your data through a series of UI components. You can display the data returned in any way that you can code the UI elements using JavaScript. The example below, from the ItemBadgeWidget sample shows one way to implement a callback function to process your returned data. In this case, the callback function is called, "filterResults". It retrieves the item ID from findItemsResponse and then uses that item ID to call getItem.
this.filterResults = function(findItemsResponse)
{
var items = findItemsResponse.item;
if(items.length === 0) {
alert("no items found!");
return;
}
for (i=0;i<items.length;i++)
{
if (items[i].listingStatus != 'Ended')
{
this.itemID = items[i].itemID;
this.getItem();
break;
}
}
};
There are two ways that you can deploy your completed JavaScript
widgets:
1. Upload them to a widget-hosting site, and then refer to the
location from your web page.
2. Host the widgets on your own web server.
With either of these methods, you need to point to the location of the widget by adding a source tag to your .html page that contains the URL of the web page that contains your widget.
The examples below shows a source tag for a widget on an .html page and the way the page looks when the widget is displayed.
You can create a widget that contains input values, so that users can change the look or parameters of your widget. See the JavaScript Developer Center for an example of a wizard widget that allows users to interact with it.
If your widget can accept parameters, have the user add the parameters following a question mark, as part of the widget source in their .html file. If your widget takes more than one parameter, the parameters should be separated by an ampersand symbol.
<http://en.mywebpage.org/FindItems.js?color=grey&keywordQuery=apple+iPod >
You can add your widget to a wiki or blog by including the URL for the web page where the widget is hosted, much like you would include it in a web page.
If the blog is written in .html, you would use a source tag, just like you would for a web page.
If you are using a wiki, you may have to use a different syntax. For example, many wiki pages use brackets with a URL followed by the title of the link after a space. The URL must begin with http:// or another common protocol, such as ftp:// or news://.
[http://en.mywebpage.org My Widget]
© 2007-2008 eBay Inc. All rights reserved.
eBay and the eBay logo are
registered trademarks of eBay Inc.
All other brands are the property of their
respective owners.