Extending Social Commerce features in WebSphere Commerce V7

Store developers can extend Social Commerce widgets and services to provide additional capabilities for their end users. This short tutorial will cover an extension scenario that modifies both a widget and its underlying service provider.

Guruprasad Shamanna (gshamann@in.ibm.com), Staff Software Engineer, IBM

Photo of Guruprasad ShamannaGuruprasad Shamanna is a Staff Software Engineer at the IBM India Software Lab in Bangalore, India. He has been part of the WebSphere Commerce team since 2004, specializing in WebSphere Commerce starter stores, Social Commerce, and Web 2.0 technologies.



Saravanan Sathyanarayanan (sarsathy@in.ibm.com), Staff Software Engineer, IBM

Photo of Saravanan SathyanarayananSaravanan Sathyanarayanan is a Staff Software Engineer at the IBM India Software Lab in Bangalore, India. He has been part of the WebSphere Commerce team since 2005, specializing in functional verification testing and automation-related areas.



17 November 2010

Also available in Portuguese

Before you start

You can extend Social Commerce widgets and services to provide additional capabilities for your end users. This short tutorial will cover an extension scenario that modifies both a widget and its underlying service provider. The tutorial supplements the information described in the Information Center topic, Creating new service adapters.

Extension activities are considered a more advanced topic than customization. You need to be familiar with the Dojo JavaScript toolkit, the Java™ programming language, and web services development. This topic is for members of the WebSphere® Commerce services and business partner community.

Objectives

The final objective is to extend the existing Review Widget to display the rating distribution using a Dojo dialog widget. The overall rating section listens to a mouse over event and opens up the dialog widget to display the rating distribution as shown in Figure 1. The underlying service provider implementation is extended to send the rating distribution data back to the widget to support this new feature. You can use this new extended Review Widget at the store front in the category or sub-category pages or product quick view widgets to display the rating distribution to the shopper. Actual reviews are then displayed in the detailed product pages.

Figure 1. Rating distribution
Rating distribution

Prerequisites

This tutorial is for Java programmers with skills and experience at a beginner level. You need to be familiar with the WebSphere Commerce development environment. Additionally, you also need to be familiar with using WebSphere sMash and the Dojo toolkit.

System requirements

To create the examples in this tutorial, you need WebSphere Commerce Developer V7 installed and configured. To configure WebSphere Commerce Developer V7 with the Social Commerce feature, see Enabling and configuring Social Commerce.

Duration

This tutorial takes about one hour to complete.

Introduction

The Social Commerce feature packaged with WebSphere commerce environment comes with a set of custom Dojo widgets to display blogs, photos, and reviews by connecting to different service providers. However, merchants might need to extend these widgets or connect to a different service provider to capture or display additional data at the store front. This tutorial shows you how to extend the existing Review Widget and the service provider implementations to display the rating distribution. With this extension, the Review Widget can display a breakup of users against each rating value (hereafter referred to as the rating distribution), along with the overall average rating.

Instructions

Several steps are needed to extend the widget and service adapters and to publish the assets into the zero repository. At a high level, the steps are:

  1. Set up the development environment.
  2. Prepare Social Commerce applications to use the test adapters.
  3. Prepare Social Commerce applications to use the test application.
  4. Test Social Commerce applications with the test adapters.
  5. Extend and implement the service provider layer.
  6. Extend the Review Widget to display the rating distribution.
  7. Configure the soccom application to use the extended service adapter.
  8. Update SocApp to put dependencies on the new project.
  9. Publish the assets into the zero repository.
  10. Update the test application to test the new feature.
  11. Configure the Madisons store to use the new widget.

Step 1. Setting up the development environment

In this step, you will set up the development environment to create WebSphere sMash applications.

To set up the development environment:

  1. Install the WebSphere sMash Eclipse -in. For more information about installing this -in, see IBM WebSphere Commerce sMash Getting Started Guide.
  2. Start WebSphere Commerce Developer and switch to the Enterprise Explorer view.
  3. Select Window > Preferences to open the Preferences window.
  4. In the left pane, click WebSphere sMash to open the WebSphere Commerce sMash preference page.
  5. In the Zero home textbox, type the full path of the location where the sMash application runtime SocCore project is stored. For example, workspace directory/SocCore.

Step 2. Preparing the Social Commerce applications to use the test adapters

The Social Commerce package provides you with test adapters that you can use during the development and testing phase to test the functionalities and other features of the widgets. These test adapters simulate the service providers and store all the data in the in-memory database. You can use these test adapters until the time your account is provisioned with the actual service providers like Baazar voice, Pluck, or Lotus® Connections.

Note: These adapters are basic and cannot be used in the production environment. All the data is lost once the Social Commerce application is restarted.

To use these test adapters:

  1. Edit WC_TOOLKIT\workspace\SocApp\config\adapter.config to configure the test service adapter in the SocApp project.
  2. The following code snippet shows the addition of code to identify test adapter as the implementation of the blog service adapter. Search for /config/soccom/adapter/blog and change it as shown below:
    /config/soccom/adapter/blog = testadpter
  3. Similarly, configure profile, photo, and reviews to use testadapter by updating these properties as shown below:
    /config/soccom/adapter/photoGallery = testadpter
    /config/soccom/adapter/profile = testadpter
    /config/soccom/adapter/review = testadpter

Step 3. Preparing the Social Commerce applications to use the test application

The Social Commerce application also provides you with a test application to test the widgets and service adapter functionality before they are used in the actual store front. This speeds up the development cycle since you are testing the widgets and service adapters in a standalone environment without integrating it with the WebSphere Commerce store front.

To configure the Social Commerce application to use the test application:

  1. Open WC_TOOLKIT\workspace\SocApp\config\ivy.xml in the development environment.
  2. In the Dependencies tab, select com.ibm.commerce.soccom.appCore and click the Remove button.
  3. Click on Add, select com.ibm.commerce.soccom.testapp, and add it as a dependency.
  4. Save the ivy.xml file.

Step 4. Testing the Social Commerce applications with the test adapters

In this step, you will make sure that the test application and test adapters are configured properly before you proceed with the actual customization. To use the test application, just start the soccom zero application. There is no need to start the WebSphere Commerce application.

To test the application with the test adapters:

  1. Set zero home in the path by adding this to the enviroment path variable WC_TOOLKIT\workspace\SocCom.
  2. In command prompt, change to the WC_TOOLKIT\workspace\SocApp directory and run this command: zero resolve.
  3. Once the resolve is successful, start the application by executing this command: zero start. You will see this output at the prompt:
    Application started and servicing requests at http://localhost:9980/soccom/
    CWPZT0600I: Command start was successful
  4. Open a new browser window and go to http://localhost:9980/soccom/.
  5. The test application opens and you can use it to log-in and create social content such as blogs, photos, and reviews.
  6. Execute the following command to stop the soccom application: zero stop.

Step 5. Extending and implementing the service provider layer

In this step, you will extend the existing review test adapter to include the rating distribution in the response object, which will be used by the new Review Widget.

The existing review response JSON object is shown in Listing 1 and explained in detail in the following section.

Listing 1. Review response JSON structure
reviewData
{
	"id":{ "type": "string" },
	"ratingStatistics":{ "type": "ratingStatistics" },
	"paginationDetails":{ "type":"paginationDetails" },
	"reviews":{ "type": "array", "arrayType": "review"}
}

ratingStatistics

{
	"numOfOverallRatings":{ "type": "integer" },
	"ratingRange":{ "type": "ratingRange" },
	"avgOverallRating":{ "type": "float" }
}

ratingRange
{
	"lowerBound":{ "type": "integer" },
	"upperBound":{ "type": "integer" }
}

paginationDetails
{
	"noOfTotalEntries":{ "type": "integer" },
	"noOfTotalPages":{ "type": "integer" },
	"noOfEntriesPerPage":{ "type": "integer" },
	"pageNum":{ "type": "integer" },
	"sortType":{ "type": "string" },
	"sortDirection":{ "type": "string" }
}

review
{
	"reviewId":{ "type": "integer" },
	"itemId":{ "type": "string" },
	"userId":{ "type": "string" },
	"ItemDescription":{ "type": "string" },
	"isRatingOnly":{ "type": "boolean" },
	"title":{ "type": "string" },
	"reviewText":{ "type": "string" },
	"rating":{ "type": "float" },
	"submissionTime":{ "type": "string" },
}
  • reviewData is the high level data structure that contains the identifier of type String, ratingStatistics, paginationDetails, and an array of reviews data structure.
  • ratingStatistics data structure contains details about the number of ratings, average ratings, and the ratings range.
  • paginationDetails data structure contains details about the total number of entries, the total number of pages, the number of entries per page, the current page number, and the sorting type and sort direction (either ascending or descending). This data structure is used by the Review Widget to display the pagination header.
  • review data structure encapsulates individual review details. It contains review details such as reviewId, itemId (product or catalogId of the store), userId (the user who reviewed this product), itemDescription (product name or catalog name), isRatingOnly (true if entry contains only rating value, false if entry contains a review text or comment about the product), title, reviewText (comments about the product), rating (actual rating given by the user), and submissionTime.

The new Review Widget created in this tutorial will expect an array of rating distribution object to be present in the response object. The modified response object structure is shown in bold in Listing 2.

Listing 2. Modified review response JSON structure

Click to see code listing

Listing 2. Modified review response JSON structure

reviewData
{
	"id":{ "type": "string" },
	"ratingStatistics":{ "type": "ratingStatistics" },
	"paginationDetails":{ "type":"paginationDetails" },
	"reviews":{ "type": "array", "arrayType": "review" },
	“ratingDistribution”:{“type”:”array”,”arrayType”:”                                 ratingDistribution” }
}
ratingDistribution
{
	"ratingValue":{ "type": "integer" },
	"percentage":{ "type": "integer" },
	"count":{ "type": "integer" }
}

You will create a new service adapter by extending the review service test adapter and pass this additional rating distribution information back to the Review Widget.

To create the new service adapter:

  1. In the Enterprise Explorer view and from the File menu, select New > Other > WebSphere sMash > WebSphere sMash Application.
  2. Specify a name for the project to add your new service provider adapter code to. For example, specify com.ibm.commerce.soccom.custom.adapter for this tutorial project that contains the code for a new Review adapter.
  3. Expand Project name > config and open the ivy.xml file.
  4. In the ivy.xml file, use the organization field to specify the organization that owns the adapter. For example, com.ibm.commerce.
  5. Save and close the file.
  6. Click the Dependencies tab and click the Add button in the upper-right hand corner to open the Dependency Selection dialog.
  7. From the list of dependencies, click on com.ibm.commerce.soccom.testadapter to add a dependency on this project that includes the review test adapter that will be extended later.
  8. From the list of dependencies, click on com.ibm.commerce.soccom.adapter to add a dependency on this project that includes the service adapter interfaces.
  9. Save the ivy.xml file.
  10. Create a new Java class, TestReviewAdapterImplExt, under the com.ibm.commerce.soccom.custom.adapter/java folder with the package com.ibm.commerce.soccom.bv.
  11. Override the list method in this new adapter to add the ratingDistribution element to the response object:
    public Map<String, Object> list(String itemHandle, int pageSize, int onPage,
     List<Map<String,String>> sortOptions) throws AdapterException {
    	//Your custom implementation code comes here.
    		}
  12. The provided zip file contains the sample implementation code. Copy TestReviewAdapterImplExt if you are using the test adapter as the underlying service provider, or ReviewAdapterImplExt if you are using Bazaar voice as the underlying service provider.
  13. Compile and build the project.

Step 6. Extending the Review Widget to display the rating distribution

In this step, you will extend the existing Dojo Review Widget to add the additional feature of displaying the rating distribution.

To create and extend the Review Widget:

  1. As in previous step, create a new sMash project in the Enterprise explorer view and name the project com.ibm.commerce.soccom.custom.dojo.
  2. Update ivy.xml and add com.ibm.commerce.soccom.dojo as the dependency project because you will be extending the Review Widget.
  3. For this tutorial, you will use the WCDialog widget to display the rating distribution, which is a WebSphere Commerce extension of the Dojo dialog widget, instead of using out-of-the-box Dojo dialog widget. This widget provides additional functionalities, such as displaying the widget relative to some HTML element (instead of always displaying it at the center of the page), hiding the title bar and Close button in the widget, and so on. To use this widget, unzip the zip file that contains WCWidget.zip into the com.ibm.commerce.soccom.custom.dojo/public folder, or copy the WC_TOOLKIT\workspace\Stores\WebContent\dojo131\wc folder into the com.ibm.commerce.soccom.custom.dojo/public/wc folder.
  4. Unzip the zip file that contains ReviewWidget.zip into the com.ibm.commerce.soccom.custom.dojo/public folder. This folder contains the ReviewExt widget, which extends from the Review Widget and adds a new view to display the rating distribution.
  5. Refer to the Dojo tutorial on how to create new custom widgets.

Step 7. Configuring the Social Commerce application to use the extended service adapter

In this step, you will configure the Social Commerce application to use the new service adapter that you just created.

To configure the soccom application:

  1. Edit WC_TOOLKIT\workspace\SocApp\config\adapter.config.
  2. Find and update the property /config/soccom/adapter/review as shown below:
    /config/soccom/adapter/review = “customAdapter”
  3. Add the following code snippet to use the new implementation of the service provider interface:
    /config/soccom/adapter/impl/customAdapter =
    {
    "review":"com.ibm.commerce.soccom.bv.TestReviewAdapterImplExt"
    }

Step 8. Updating SocApp to put dependencies on the new project

In this step, you will update the SocApp dependencies to include the newly created sMash projects:

  1. Open WC_TOOLKIT\workspace\SocApp\config\ivy.xml in the development environment.
  2. Click on Add, select com.ibm.commerce.custom.testadapter, and add it as a dependency.
  3. Click on Add, select com.ibm.commerce.custom.dojo, and add it as a dependency.
  4. Save the ivy.xml file.

Step 9. Publishing the assets into the zero repository

In this step, you will export and publish the service adapter project to the SocCore repository. Exporting the service adapter project creates an archive file that contains all of the classes and web artifacts associated with the service adapter in the export directory of the project.

To publish the assets into the zero repository:

  1. In the Enterprise Explorer view, right-click the com.ibm.commerce.soccom.custom.adapter project that you just created and click Export > WebSphere sMash > WebSphere sMash Export Wizard. By default, the project is exported to the adapter project or export directory as an archive file.
  2. Optional: There are two checkboxes displayed on this screen. One is the “Include Source” checkbox and the other is the “Overwrite” checkbox. You can select either of them or both of them.
  3. From the command prompt, change to the SocApp directory.
  4. Publish the archive file by executing the following command:
    zero publish -f=<full path to adapter archive file which was exported 
    in the previous step>
  5. Expand SocCore > zero-repository > stable > modules to verify that the service adapter module you created and published above appears.
  6. Repeat the above steps for the com.ibm.commerce.soccom.custom.dojo project

Step 10. Updating the test application to test the new feature

In this step, you will update the existing Soccom test application project to test the new functionality that you just created.

Note: The changes you make in the expanded directory will be temporary and will be lost next time you run the zero resolve command. These changes are made to test the functionality from the test application in the current session. If you want the changes to be persistent, then you need to import the com.ibm.commerce.soccom.testapp project into your development environment, make the changes, and publish the project again into the Soccore repository.

Steps:

  1. At command prompt, change to WC_TOOLKIT\workspace\SocApp and run this command: zero resolve.
  2. Open the following in Explorer:
    WC_TOOLKIT\workspace\SocCore\zero-repository\stable\expanded\com.ibm.commerce\
     com.ibm.commerce.soccom.testapp-x.x.x.xxxxxxxx-xxxx\public\ibm\social\testapp
  3. Unzip the attached TestApp.zip folder, which will replace ReviewsWidgetSection.html and WidgetSection.js. These files update the current testapp to use the newly created Review Widget.
  4. Change to WC_TOOLKIT\workspace\SocApp and run this command: zero start.
  5. Open a new browser window and go to http://localhost:9980/soccom/.
  6. Log in as some user using the Login button available at the top left of the navigation bar.
  7. Select some product under the Get Product Reviews select box.
  8. Click on the Create review link and in the resulting screen, select a rating and enter comments, and then click on the Create button to create a new review.
  9. Log in as some other user in the same window.
  10. Click on Create review and Create a new review and repeat this to create a few more reviews for the same product.
  11. Select the same product under the Get Reviews Summary select box.
  12. The overall rating is displayed.
  13. Mouse over this overall rating – a new dialog widget with the rating distribution is displayed.

Step 11. Configuring the Madisons store to use the new widget

You can use this newly created Review Widget at the store front in the product and item display pages. Follow the steps in Working with Social Commerce widgets to include these widgets in your store front.


Conclusion

This tutorial covered an end-to-end customization scenario in a Social Commerce application. In this tutorial, you created a new Review Widget and service adapters by extending the existing review widgets and service adapters to display the rating distribution feature. You also configured a Social Commerce application to use the test adapters and test application.


Download

DescriptionNameSize
Code sampleCodeChanges.zip106KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Commerce on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Commerce, WebSphere
ArticleID=587805
ArticleTitle=Extending Social Commerce features in WebSphere Commerce V7
publish-date=11172010