Customizing WebSphere Commerce Accelerator

slavecandleInternet και Εφαρμογές Web

14 Αυγ 2012 (πριν από 5 χρόνια και 3 μήνες)

644 εμφανίσεις

© Copyright IBM Corporation 2007, 2009
Trademarks
Customizing WebSphere Commerce Accelerator
Page
1
of
17
Customizing WebSphere Commerce
Accelerator
Vani Mittal
(
vanimi@in.ibm.com
)
Software Engineer
IBM
Skill Level: Intermediate
Date: 11 Jul 2007
(Updated Jun 2009)
This tutorial describes how to customize WebSphere® Commerce Accelerator. It
introduces a new feature by using two of the most commonly used user interface
elements in the Tools Framework, a dynamic list and a dialog.
Section 1. Before you start
WebSphere Commerce Accelerator is intended as a user interface for business
people to manage the day-to-day business operations of a site without having to
involve the IT staff. The user interface elements defined in the Tools Framework are
designed to minimize and simplify any customization efforts by providing a flexible
framework that you can easily extend and customize. This tutorial shows how to work
with two of the most commonly used user interface elements in the Tools Framework,
a dynamic list and a dialog
Section 2. Introduction
The example scenario described in this tutorial has been kept simple for easy
understanding. You will add a new menu item "Subsidy" under the "Marketing" menu
in the ConsumerDirect starter store. For the purpose of this tutorial, a subsidy is
simply an amount with a name attached to it. For example, an amount of $100 is
called "Subsidy for farmers".
Clicking on the Subsidy menu item takes the user to a page displaying a list of
subsidies currently defined in the system. The list of subsidies is displayed using a
dynamic list element. From this page, the user can create a new subsidy, update an
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
2
of
17
existing subsidy, or delete an existing subsidy. The New and Change functions use a
dialog to display the relevant pages where a user can enter the details of a Subsidy.
Figure 1 shows a dynamic list that is used to display the list of defined subsidies.
Figure 1. Dynamic List
Figure 2 shows the New Subsidy dialog that is used to create a new subsidy.
Figure 2. New Subsidy Dialog
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
3
of
17
Figure 3 shows the Change Subsidy dialog that is used to update an existing subsidy.
Figure 3. Change Subsidy Dialog
Section 3. Adding a new menu item to WebSphere
Commerce Accelerator
To add a new menu item, you need to modify the CommerceAcceleratorB2C.xml file.
This file defines the different menu options that are available within the WebSphere
Commerce Accelerator for the ConsumerDirect B2C starter store. To add a new
menu item "Subsidy" under the "Marketing" menu, do the following steps:
1.
Open the
CommerceAcceleratorB2C.xml
file found in the <WCDE_installdir>\xml
\tools\common directory, where <WCDE_installdir> is the installation directory
for the WebSphere Commerce development environment.
2.
Search for the following line:
<menuitem name="marketing" enabled="true"
taskUsages="all" users="buyer catMgr makMgr
podMgr seller">
3.
Add the following text immediately after the above line:
<node name="subsidy" url="/webapp/wcs/tools/
servlet/NewDynamicListView?ActionXMLFile=order.SubsidyList&
cmd=SubsidyListView" users="makMgr podMgr seller"/>
4.
Save and close the file.
5.
Open the
mccNLS_<locale>.properties
file found in the <WCDE_installdir>
\properties\com\ibm\commerce\tools\properties directory.
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
4
of
17
6.
Add the following text at the end of the file:
#
# Sample code
#
subsidy=Subsidy
7.
Save and close the file.
8.
Restart the WebSphere Commerce Test Server.
Note the following points:

The node name ("subsidy" in this case) should match the key defined in the
mccNLS_<locale>.properties file.

The roles makMgr, podMgr, seller and so on are defined in Roles.xml found in
the <WCDE_installdir>\xml\tools\common directory. The roles name and value
defined in the Roles.xml file should match with those in the database table,
ROLE. Later in the tutorial, you will load access control policies to allow the
three roles - Marketing Manager, Product Manager, and Seller - to access the
new feature.
Figure 4 shows the newly added menu item Subsidy under the Marketing menu.
Figure 4. Subsidy Menu Item
Section 4. Defining the SUBSIDY table, entity bean,
and access bean
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
5
of
17
Define the SUBSIDY table by doing the following steps:
1.
Open the DB2® Command Line Processor and connect to the database.
2.
Run the following queries:
CREATE TABLE SUBSIDY (
SUBSIDY_ID BIGINT NOT NULL,
AMOUNT BIGINT,
NAME VARCHAR (64),
OPTCOUNTER SMALLINT NOT NULL
);
ALTER TABLE SUBSIDY
ADD CONSTRAINT p_SUBSIDY PRIMARY KEY (SUBSIDY_ID);
INSERT INTO KEYS (KEYS_ID, TABLENAME, COLUMNNAME,
COUNTER) VALUES (-2000, 'subsidy',
'subsidy_id', 10000);
3.
Ensure that the table was created successfully.
Create the entity bean and access bean for the SUBSIDY table by doing the following
steps:
1.
Download the
sample_code.zip
file available with this tutorial.
2.
Extract
WebSphereCommerceServerExtensionsData.jar
file to a temporary
directory.
3.
In the Project Explorer view, select the
WebSphereCommerceServerExtensionsData
project.
4.
From the project's pop-up menu, select
Import > EJB JAR file
.
5.
In the EJB JAR file field, browse to or enter the fully qualified path of the
WebSphereCommerceServerExtensionsData.jar file.
6.
From the EJB Project list, select
WebSphereCommerceServerExtensionsData
.
7.
Select
Overwrite existing resources without warning
.
8.
Click
Finish
.
9.
Generate the test deployment code:
a.
From the WebSphereCommerceServerExtensionsData project's pop-up
menu, select
Deploy
.
b.
Ensure no errors display in the console view.
10.
Restart the WebSphere Commerce Test Server.
Section 5. Creating the required data beans,
controller commands, and task commands
To create the data beans, controller commands, and task commands required for this
tutorial, perform the following steps:
1.
Extract the
WebSphereCommerceServerExtensionsLogic.zip
file available in
sample_code.zip
to a temporary directory.
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
6
of
17
2.
In the Project Explorer view, navigate to the
WebSphereCommerceServerExtensionsLogic project.
3.
From the src folder's pop-up menu, select
Import
.
4.
Select
Zip file
and click
Next
.
5.
In the "From zip file" field, browse to or enter the full path of the
WebSphereCommerceServerExtensionsLogic.zip file. Click
Open
.
6.
Click
Finish
.
7.
Refresh the WebSphereCommerceServerExtensionsLogic project in the
workspace.
8.
Restart the WebSphere Commerce test server.
Section 6. Registering controller commands and
task commands
Register the controller commands and task commands by doing the following steps:
1.
Open the DB2 Command Line Processor and connect to the database.
2.
Run the following queries:
insert into cmdreg (storeent_id, interfacename, description, classname,
properties, lastupdate, target) values (0, 'com.sample.commerce.
tools.order.commands.SubsidyAddUpdateCmd', null,
'com.sample.commerce.tools.order.commands.
SubsidyAddUpdateCmdImpl', null, null, 'Local');
insert into cmdreg (storeent_id, interfacename, description, classname,
properties, lastupdate, target) values (0, 'com.sample.commerce.
tools.order.commands.SubsidyAddTaskCmd', null,
apos;com.sample.commerce.tools.order.commands.
SubsidyAddTaskCmdImpl', null, null, 'Local');
insert into cmdreg (storeent_id, interfacename, description, classname,
properties, lastupdate, target) values (0, 'com.sample.commerce.
tools.order.commands.SubsidyUpdateTaskCmd', null,
'com.sample.commerce.tools.order.commands.
SubsidyUpdateTaskCmdImpl', null, null, 'Local');
3.
Register the SubsidyAddUpdateCmd interface, which is a controller command,
in the Struts Configuration File by doing the following steps:
a.
Open
struts-config-ext.xml
in the Struts Configuration File editor. The
file is found in the <WCDE_installdir>\workspace\CommerceAccelerator
\WebContent\WEB-INF directory.
b.
In the
Action Mappings
tab, in the
Action Mappings
section, click
Add
.
Delete the default path value <no path> and enter
/SubsidyAddUpdateCmd
.
c.
In the
Action Mapping attributes
section, in the
Type
field, enter
com.ibm.commerce.struts.BaseAction
.
d.
In the
Action Mapping attributes
section, in the
Parameter
field, enter
com.sample.commerce.tools.order.commands.SubsidyAddUpdateCmd
.
4.
Refresh the Struts Configuration registry component by doing the following
steps:
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
7
of
17
a.
Open the Administration Console and select
Site
on the Administration
Console Site/Store Selection page.
b.
From the Configuration menu, click
Registry
. A list of registry components
for the site displays.
c.
Click
Update All
to update all of the listed Registry components. The
Registry window reloads listing the status for all component as "Updating".
d.
Click
Refresh
to reload the Registry window and check on the status of
components you are updating. When updating is complete, the status
column reads "Updated".
Section 7. Defining the dynamic list
The following files are created for a dynamic list:

A dynamic list definition XML file, SubsidyList.xml, to describe the frameset.

A resource bundle file, SampleNLS_en_US.properties.

SubsidyList.jsp to fill the panel contents.
To add the dynamic list, do the following steps:
1.
Create the XML file, SubsidyList.xml, in the <WCDE_installdir>\xml\tools\order
directory. The XML file is also available in
sample_code.zip
. Following are the
contents of the file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE action SYSTEM "../common/List.dtd">
<action resourceBundle="order.SampleNLS" formName
="subsidyForm">
<parameter listsize="20" startindex="0"
resultssize="0"/>
<scrollcontrol title="SubsidyListPrompt" display="
true" />
<controlpanel display="true" />
<button>
<menu name="new" action="basefrm.newSubsidy
()" />
<menu name="properties" action="basefrm.
changeSubsidy()" selection="single" />
<menu name="delete" action="basefrm.
eleteSubsidy()" selection="multiple" />
</button>
</action>
The following table describes the above attributes.
Element
Attribute
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
8
of
17
<action> </action>
This element is the primary element defining a
dynamic list.
resourceBundle
This is a required attribute that specifies which
resource bundle is used.
formName
This is a required attribute that specifies the form
name. A dynamic list is rendered as an HTML
form.
<parameter> </parameter>
This element defines parameters passed to the
dynamic list.
listsize
This is a required attribute that sets the
maximum number of list items that display on
each page.
startindex
This is a required attribute that sets the index
value of the first item in the list.
resultsize
This is a required attribute that defines the length
of the entire list. This value is not known until
runtime, and is dynamically calculated. However,
this property must be defined as a placeholder.
It does not matter what the initial value is, as it is
recalculated.
<scrollcontrol> </scrollcontrol>
This element defines the scroll control frame.
title
This is an optional attribute that defines the page
title.
display
This is a required element that determines
whether the scroll control frame is displayed.
<controlpanel> </controlpanel>
This element defines the control panel.
display
This is a required element that determines
whether the control panel is displayed.
<button> </button>
This element defines the button frame. The
button element contains <menu> elements.
<menu> </menu>
This element defines a button.
name
This is a required attribute that specifies a name
for the button.
action
This is a required attribute that defines the action
performed when the button is clicked.
selection
This is an optional attribute that defines how
selected items in the dynamic list affect the
button. Permitted values include "single",
"multiple", or "none". These values specify that
the button is enabled when only one item is
selected, when one or more items are selected,
or when no items are selected, respectively. In
the case of "single" and "multiple", the action
associated with the button is performed on the
selected items.
2.
Register SubsidyList.xml in the resources.xml found in the <WCDE_installdir>
\xml\tools\order directory. Add the following text anywhere within the <resource>
element:
<resourceXML name="SubsidyList" file="order/SubsidyList.xml" />
3.
Extract the resource bundle SampleNLS_en_US.properties from
sample_code.zip
and place it in the <WCDE_installdir>\properties\com\ibm
\commerce\tools\order\properties directory.
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
9
of
17
4.
Register SampleNLS_en_US.properties in the resources.xml found in the
<WCDE_installdir>\xml\tools\order directory. Add the following text anywhere
within the <resource> element:
<resourceBundle name="SampleNLS"
bundle="com.ibm.commerce.tools.order.properties.SampleNLS" />
5.
Extract the JSP file, SubsidyList.jsp, from
sample_code.zip
and place it in the
<WCDE_installdir>\workspace\CommerceAccelerator\WebContent\tools\order
directory.
6.
Register SubsidyList.jsp in the Struts Configuration File by doing the following
steps:
a.
Open struts-config-ext.xml in the Struts Configuration File editor. You can
find this file in the <WCDE_installdir>\workspace\CommerceAccelerator
\WebContent\WEB-INF directory.
b.
In the
Action Mappings
tab, in the
Action Mappings
section, click
Add
.
Delete the default path value <no path> and enter
/SubsidyListView
.
c.
In the
Action Mapping attributes
section, in the
Type
field, enter
com.ibm.commerce.struts.BaseAction
.
d.
In the
Global Forwards
tab, click
Add
. Delete the default name <no
name> and enter
SubsidyListView
.
e.
In the
Forward Attributes
section, in the
Path
field, enter
tools/order/
SubsidyList.jsp
.
f.
In the
Forward Mapping Extensions
section, in the
Class Name
field,
enter
com.ibm.commerce.struts.ECActionForward
.
Section 8. Defining the dialog
The following files are created for a dialog:

A dialog definition XML file, SubsidyCreateUpdate.xml, to describe the panel

SubsidyCreateUpdate.jsp, to fill the panel contents

Subsidy.js, a Java™Script file
To add the dialog, do the following steps:
1.
Create the XML file, SubsidyCreateUpdate.xml, in the <WCDE_installdir>
\xml\tools\order directory. The XML file is also available in
sample_code.zip
.
Following are the contents of the file:
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
10
of
17
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dialog SYSTEM "../common/DialogPanels.dtd">
<dialog resourceBundle="order.SampleNLS" windowTitle="
SubsidyCreateUpdate_Title"
finishURL="SubsidyAddUpdateCmd">
<panel name="Panel" url="SubsidyCreateUpdateView"
helpKey=""
passAllParameters="true" hasFinish="YES"
hasCancel="YES" />
<databean name="subsidyBean"
class="com.sample.commerce.tools.order.beans.
SubsidyDataBean" />
<jsFile src="/wcs/javascript/tools/order/Subsidy.js" />
</dialog>
The following table describes the above elements and attributes.
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
11
of
17
Element
Attribute
<dialog> </dialog>
This is the primary element defining a dialog.
resourceBundle
This is a required attribute that specifies which
resource bundle is used.
windowTitle
This is an optional attribute that defines the
window title. This name is a key in the resource
bundle file.
finishURL
This is an optional attribute that specifies which
command is to be executed to finish the dialog. If
it is not present, then nothing happens when the
user clicks the OK or Finish buttons.
<panel />
This element defines a panel to appear in the
content frame.
name
This is a required attribute that specifies a name
for the panel.
url
This is a required attribute that sets the contents
of the panel to this URL. This can link to a
viewCommand or be a direct link.
helpKey
This is an optional attribute that defines the
corresponding help key in the Tools UI Center
Help Map file.
passAllParameters
This is an optional attribute that, when true,
indicates that all of the parameters should be
passed to this panel from the parent frame (also
called DialogView).
hasFinish
This is an optional attribute that specifies
whether the panel provides a Finish button. This
value is either YES or NO. The default is NO.
hasCancel
This is an optional attribute that specifies
whether the panel provides a Cancel button. This
value is either YES or NO. The default is YES.
<databean> </databean>
This is an optional element that specifies a
data bean to hold user data and populate
the fields with existing data. If defined, this
bean is instantiated. If the bean is also a
smartDataBean, it is activated when the dialog
loads. Its properties are converted into a
JavaScript object with the name defined here.
name
This is a required attribute that defines a name
for the JavaScript object, which is populated
from the databean.
class
This a required attribute that specifies the class
of the data bean.
<jsFile/>
This element specifies a JavaScript file to be
included in the dialog. Files defined here are
included in the parent frame. Thus, access to
these functions require "parent." prefixed to
function calls to scope them to the parent frame.
src
This is a required attribute that specifies the
location of the JavaScript file.
2.
Register
SubsidyCreateUpdate.xml
in the resources.xml file found in the
<WCDE_installdir>\xml\tools\order directory. Add the following text anywhere
within the <resource> element:
<resourceXML name="SubsidyCreateUpdate" file="order/SubsidyCreateUpdate.xml" />
3.
Extract the
SubsidyCreateUpdate.jsp
file from
sample_code.zip
and place it
in the <WCDE_installdir>\workspace\CommerceAccelerator\WebContent\tools
\order directory.
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
12
of
17
4.
Register SubsidyCreateUpdate.jsp in the Configuration File by doing the
following steps:
a.
Open
struts-config-ext.xml
in the Struts Configuration File editor. The
struts-config-ext.xml file is found in the <WCDE_installdir>\workspace
\CommerceAccelerator\WebContent\WEB-INF directory.
b.
In the
Action Mappings
tab, in the
Action Mappings
section,
click
Add
. Delete the default path value <no path> and enter
/
SubsidyCreateUpdateView
.
c.
In the
Action Mapping
attributes section, in the
Type
field, enter
com.ibm.commerce.struts.BaseAction
.
d.
In the
Global Forwards
tab, click
Add
. Delete the default name <no
name> and enter
SubsidyCreateUpdateView
.
e.
In the
Forward Attributes
section, in the
Path
field, enter
tools/order/
SubsidyCreateUpdate.jsp
.
f.
In the
Forward Mapping Extensions
section, in the
Class Name
field,
enter
com.ibm.commerce.struts.ECActionForward
.
5.
Extract the JavaScript file, Subsidy.js from
sample_code.zip
and place it
in the <WCDE_installdir>\workspace\CommerceAccelerator\WebContent
\javascript\tools\order directory. This file contains the JavaScript function
submitFinishHandler(finishMessage), which is called upon successful
completion by the controller command. In the controller command,
SubsidyAddUpdateCmd, the finish message is picked up from the
SampleNLS_en_US.properties resource bundle and passed into the response
properties with the key "SubmitFinishMessage".
Section 9. Loading access control policies
To load access control policies for the new views and controller command, do the
following steps:
1.
Extract the access policy xml files,
MyNewViewACPolicy.xml
and
MyNewControllerCmdACPolicy.xml
, from
sample_code.zip
and place them in
the <WCDE_installdir>\xml\policies\xml directory.
2.
Open a command prompt and from the <WCDE_installdir>\bin directory, run the
following commands one by one:
acpload <db_name> <db_user> <db_pwd>
MyNewControllerCmdACPolicy.xml <schema_name>
acpload <db_name> <db_user> <db_pwd>
MyNewViewACPolicy.xml <schema_name>
<db_name> is the database name, <db_user> is the database user, <db_pwd>
is the database password, and <schema_name> is the schema name in upper
case letters.
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
13
of
17
3.
Check acpload.log in the <WCDE_installdir>\logs directory to make sure there
is no error and the policies were loaded successfully.
4.
Refresh the access control registry component by doing following steps:
a.
Open the Administration Console and select
Site
on the Administration
Console Site/Store Selection page.
b.
From the Configuration menu, click
Registry
. A list of registry components
for the site displays.
c.
Click
Update All
to update all of the listed Registry components.
The Registry window reloads listing the status for all components as
"Updating".
d.
Click
Refresh
to reload the Registry window and check on the status of
components you are updating. When updating is complete, the status
column reads "Updated".
Section 10. Common JavaScript files and functions
used
Following is a list of common JavaScript files and functions used throughout this
tutorial:

common.jsp

<%@ include file="../common/common.jsp" %>

This file must be included in all JSP pages.

You can find it in the <WCDE_installdir>\workspace\CommerceAccelerator
\WebContent\tools\common directory.

dynamiclist.js

<SCRIPT SRC="/wcs/javascript/tools/common/dynamiclist.js"></SCRIPT>

This file must be included in the JSP that defines a dynamic list.

dynamiclist.js contains the JavaScript functions that are needed to
create a dynamic list. For example, startDlistTable, endDlistTable,
startDlistRowHeading, endDlistRowHeading, and so on.

You can find it in the <WCDE_installdir>\workspace\CommerceAccelerator
\WebContent\javascript\tools\common directory.

Util.js

<SCRIPT SRC="/wcs/javascript/tools/common/Util.js"></SCRIPT>

This file must be included in all JSP pages.

It contains utility functions used throughout WebSphere Commerce.

If the page is in a wizard, notebook, or dialog, Util.js is already included in
the parent frame.

validatePanelData()

This function validates data entered by the user before submitting it.

This is called before savePanelData().
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
14
of
17

savePanelData()

This function stores data from the HTML form into the object model in the
parent frame.

This is called after validatePanelData().

submitFinishHandler(finishMessage)

This function is called upon successful completion by the controller
command.

setContentFrameLoaded(value)

This function sets the contentFrameLoaded variable to either true or false.
If true, then the user is allowed to switch to a different content panel. If
false, the user must wait until the panel has been loaded which sets the
value to true.

You must call setContentFrameLoaded(true) at the end of the panel's
onLoad() function. If this is not called, users are stuck on the current
content panel.
Section 11. Conclusion
In this tutorial, you learned how to add two of the most commonly used user interface
elements in the Tools Framework, a dynamic list and a dialog. You were also taken
through a simple customization scenario to help you get started with the Tools
Framework. If you have added a new feature to your WebSphere Commerce site,
you can customize WebSphere Commerce Accelerator to make the changes visible
to business users, so that they can manage the new feature without having to contact
the IT staff.
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
15
of
17
Downloads
Description
Name
Size
Download
method
Code sample for for this tutorial
sample_code.zip
147KB
HTTP
Information about download methods
developerWorks®
ibm.com/developerWorks/
Customizing WebSphere Commerce Accelerator
Page
16
of
17
Resources

WebSphere Commerce Information Center: Tools customizer

WebSphere Commerce Information Center: Tools framework

developerWorks WebSphere Commerce zone

WebSphere Commerce discussion forum
ibm.com/developerWorks/
developerWorks®
Customizing WebSphere Commerce Accelerator
Page
17
of
17
About the author
Vani Mittal
Vani Mittal
is a Staff Software Engineer with the Lab Services and
Solutions Group at the IBM Software Lab in Gurgaon, India. She has
been working as a WebSphere Commerce Consultant for the last six
years.
© Copyright IBM Corporation 2007, 2009
(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)