|
|
|
|
|
|
Customizing Webflow and Pipelines
The most important benefit of the Webflow and Pipeline mechanisms is that they allow people with different levels of technical skill to customize both the presentation and business logic within an e-commerce site.
Commerce engineers/JSP content developers, site administrators, and business analysts can now divide Web site customization (and subsequent maintenance) activities based on their own expertise, interests, and job responsibilities. While they are working with the Webflow/Pipeline infrastructure, the Java/EJB programmers on the development team can be extending the BEA WebLogic Commerce Server packages to add functionality. Thus, some bottlenecks in the site development and maintenance process are greatly reduced.
If the packages that the BEA WebLogic Commerce Server product provides completely meet your requirements, all you may need to do to have a fully functioning e-business is to customize some aspects of the Webflow and/or Pipeline. This topic describes how to accomplish this.
This topic includes the following sections:
Using Webflow
Since every e-business is different, the BEA WebLogic Commerce Server product utilizes an external properties file to manage the sequence (flow) in which Web pages are displayed. The WebLogic Commerce Server provides a default Webflow properties file to get you up and running quickly, and to provide you with a working example of this concept. You can modify this file to change the order of your pages, without having to edit each page individually.
This section provides information about the default Webflow and instructions for customizing it. This section also describes how to invoke the Webflow mechanism from your Web pages, and explains how missing transitions in the properties file are resolved.
Customizing Webflow Using the webflow.properties File
The Webflow properties file (webflow.properties) controls the display of your site's Web pages and initiates execution of the business logic associated with these pages. The Webflow properties file contains one section for each JavaServer Page (JSP) and includes comments for increased readability.
Generically, each transition in the webflow.properties file can be written as:
<origin>.[<event>][(<eventName>)]=<target>
Table 2-1 lists the valid values for each of these elements.
Notes: Valid characters for <page>, <inputprocessorName> and <pipelineName> are limited to A-Z, a-z, and an underscore.
Transitions in the webflow.properties file should never contain spaces. Including spaces can result in errors that are difficult to locate.
Text within the webflow.properties file is case sensitive.
Syntax of the webflow.properties File
Each transition in the webflow.properties file is comprised of a name/value pair, separated by an equal sign (=).
The name consists of the current state and a named event, and the value is a result state. In Listing 2-1, the current state is firstpage.jsp. The event is a button named Next, and the result state is nextpage.jsp.
Listing 2-1 Webflow Properties Example
firstpage.jsp.button(next)=nextpage.jsp
When a customer clicks the Next button from firstpage.jsp, the Webflow will load nextpage.jsp.
Note: The only exception to this syntax is the transition in the webflow.properties file that defines the initial state for the Webflow, as follows:
begin=home.jsp
Web pages used as current or result states in the Webflow may be .htm, .html, or .jsp files. In addition to the button event shown in the previous example, there is also a link event associated with these file types.
About Event Names
Events are given names because it is likely that a page has multiple events of the same type associated with it (that is, there are both previous and next buttons on firstpage.jsp, each requiring different result states). Event names are used to differentiate between these events, as shown in Listing 2-2.
Listing 2-2 Event Names Example
firstpage.jsp.button(previous)=previouspage.jsp
firstpage.jsp.button(next)=nextpage.jsp
Note: Although event names are arbitrarily selected, duplication of names for events of the same type would defeat their purpose and should be avoided. Because duplicate names would produce unpredictable results, the Webflow and Pipeline Editor's validation tool will check for and notify you about any such occurrences. For more information about using the Webflow and Pipeline Editor to validate your webflow.properties file, see How to Validate Your Properties Files.
Although all the states in the previous examples are JSPs, both current and result states can also be input processors or Pipelines. For more information on input processors and Pipelines, see Using Input Processors with Webflow and Using Pipelines with Webflow, respectively.
Using the Wildcard Character
In cases where you want all your Web pages to reach a certain target page, you can substitute the wildcard character (*) for a specific page name in the current state. For example, if you want customers to be able to reach the home page from every page within your Web site, a transition in the webflow.properties file would read:
*.jsp.link(home)=home.jsp
Default Webflow
Listing 2-3 shows the portion of the default Webflow that handles category browsing. It can also be viewed in a simple text editor by opening WL_COMMERCE_HOME/webflow.properties, where WL_COMMERCE_HOME is the top-level directory where you installed Campaign Manager for WebLogic (which includes WebLogic Commerce Server) or WebLogic Commerce Server.
Listing 2-3 Default Webflow for Category Browsing
###########################################
# Handle category browsing
###########################################
# Generic browse link gets browse parameters
*.jsp.link(browse)=BrowseCategory.inputprocessor
# Move intermediate results
BrowseCategory.inputprocessor.success=MoveSiblingResults.inputprocessor
# Get all category detail
MoveSiblingResults.inputprocessor.success=GetBrowseDetails.pipeline
# Display category detail
GetBrowseDetails.pipeline.success=commerce/catalog/browse.jsp
# Handle errors
BrowseCategory.inputprocessor.exception(ProcessingException)=commerce/catalog/
browse.jsp
MoveSiblingResults.inputprocessor.exception(ProcessingException)=commerce/
catalog/browse.jsp
GetBrowseDetails.pipeline.exception(PipelineFatalException)=commerce/catalog/
browse.jsp
# Define the input processor classes
BrowseCategory.inputprocessor=com.beasys.commerce.ebusiness.catalog.webflow. GetCategoryIP
MoveSiblingResults.inputprocessor=com.beasys.commerce.ebusiness.catalog.webflow.MoveAttributeIP
Dynamically Modifying Your Site's Webflow
To dynamically modify your site's Webflow, consider the following:
To modify your site's Webflow, use the Webflow and Pipeline Editor Administration Tool. For more information about this tool, see Using the Webflow and Pipeline Editor.
Note: You can also modify the Webflow by editing the webflow.properties file directly. However, this is not recommended. Once you edit the webflow.properties file by hand, you may not be able to use the Webflow and Pipeline Editor. If you are certain you want to edit the file directly, follow these steps:
Using Webflow in Your Web Pages
To utilize the Webflow mechanism, the URLs within your Web pages must include information that corresponds to a transition in the webflow.properties file. Specifically, the URL must contain a page name and an event that match a current state in the webflow.properties file, as shown in Listing 2-4 and Listing 2-5.
Listing 2-4 URL Within a <FORM> Tag in the Web Page
<FORM method="post" action="<%=WebflowJSPHelper.createWebflowURL(pageContext, "login.jsp", button(createUser), false)%>">
Listing 2-5 Corresponding Transition in the webflow.properties File
login.jsp.button(createUser)=nextpage.jsp
These URLs are dynamically generated by a utility class called WebflowJSPHelper.
Note: In most cases, a Web page will use the WebflowJSPHelper class multiple times. Therefore, it is a good idea to import the class at the beginning of your Web page as shown in the following statement:
<%@ page import="com.beasys.commerce.webflow.WebflowJSPHelper" %>
As shown in Listing 2-4, the WebflowJSPHelper class has a createWebflowURL() method that takes four parameters: pageContext, the name of the current JSP with extension (origin), the event type and name, and a URL type. A URL type of true causes the returned string to include the origin and event parameters as query parameters. Using the information from these four parameters, the createWebflowURL() method returns an absolute URL.
Although the parameters of the createWebflowURL()method are always the same, the way you specify these parameters depends on whether you are generating the URL within a <FORM> tag or an <A> (anchor) tag.
To incorporate a URL using the <FORM> tag, use the action attribute to construct the URL as shown in Listing 2-4 . To incorporate a URL using the <A> tag, call the createWebflowURL() method as shown in Listing 2-6.
Listing 2-6 Dynamic URL Generation Within an <A> Tag
<a href="<%=WebflowJSPHelper.createWebflowURL(pageContext, "login.jsp", button(createUser), false)%>">
In both cases, these statements are translated into login.jsp.button(createUser), which can be found in the webflow.properties file to the left of an equal sign, as shown in Listing 2-5. The value to the right of this equal sign initiates the result state, and thus allows the Webflow mechanism to continue.
Webflow Search Order
There may be times when a transition in the Webflow is missing (that is, no result state has been specified). To prevent any problem from being visible to your customer, the Webflow will attempt to resolve missing transitions by searching through several possibilities to locate an alternate flow. These search possiblities are examined by the Webflow mechanism in the following order:
Note: The configuration error page can be specified in the webflow.properties file under the property configurationerrorpage.
In summary, the search order attempts to prevent a missing transition in the Webflow from interrupting a customer's experience on your Web site. Rather, in the very worst case, the Webflow would load the configuration error page. If for some reason this file was missing, a predefined system error page (servererror.jsp), which is also beyond the scope of the Webflow mechanism, would be used instead.
Note: Using the Validate option in the Webflow and Pipeline Editor Administration Tool can help identify potential problems with your Webflow. For more information about the Validate option, see How to Validate Your Properties Files.
Search Order Examples
Suppose the Webflow mechanism is attempting to locate the missing transition login.jsp.link(home)in the webflow.properties file. The following list illustrates the alternate transitions that may be used by the Webflow:
The Webflow search order will also be performed for input processors and Pipelines that are missing in the webflow.properties file. The following list illustrates the alternate transitions that may be used by the Webflow for the missing transition ShoppingCartIP.inputprocessor.success:
Similarly, the following list illustrates the alternate transitions that may be used by the Webflow for the missing transition ShoppingCartPC.pipeline.success:
Note: For more information about input processors, see Using Input Processors with Webflow. For more information about Pipelines, see Using Pipelines with Webflow.
Using Input Processors with Webflow
States in the webflow.properties file are not restricted to other Web pages. Input processors are predefined classes that provide a way to indirectly carry out more complex tasks using the Webflow mechanism. Input processors reduce the need to incorporate complex Java code into your JSPs, and help maintain the separation between presentation and business logic.
The role of input processors is to read data from the HTTPServletRequest and use it to create or update Java objects in a Pipeline session. In addition to working with this data, some input processors may also validate information supplied by the customer.
Note: It is not required that you use input processors in your customized Webflow. If you do not wish to use input processors, simply do not specify any input processors in the webflow.properties file.
This section provides information about invoking input processors from theWebflow and about chaining input processors. This section also points you to additional information about extending or developing your own input processors.
Syntax of Input Processors in the webflow.properties File
Input processors extend the syntax used for JSPs in the webflow.properties file. For example, if you want to verify that the customer filled in the required form fields for their address before sending the customer to the next page, you could use the ValidateAddress input processor as shown in Listing 2-7.
Listing 2-7 Input Processor for Address Validation
#################################
# ValidateAddress input processor
#################################
# Invoke the input processor
addaddress.jsp.button(continue)=ValidateAddressIP.inputprocessor
# Specify the fully qualified class name for the input processor
ValidateAddressIP.inputprocessor=com.beasys.commerce.ebusiness.
customer.webflow.ValidateAddressIP
# Specify the result state for successful execution
ValidateAddressIP.inputprocessor.success=selectaddress.jsp
# Specify the result state for unsuccessful execution
ValidateAddressIP.inputprocessor.exception(ProcessingException)=
addaddress.jsp
In the first transition, a customer who clicks the Continue button causes the flow to be turned over to the input processor called ValidateAddressIP. The second line defines the full class name of the ValidateAddressIP input processor, which will validate the form fields. The transitions that follow make use of the event types defined for input processors: success and exception. If the validation is successful, the result state indicated by the success event is to load the selectaddress.jsp file. If the validation is not successful, the ValidateAddressIP input processor directs the customer back to addaddress.jsp to make corrections.
Notes: For the complete list of event types and more information on the syntax of input processors in the Webflow, see Table 2-1.
If execution of an input processor is not successful, you may specify different result states identified by more than one exception event.
Chaining Input Processors
In addition to using input processors between JSPs and Pipelines, you can also use more than one input processor, or chain input processors. In a chaining arrangement, the result state of one successfully executed input processor will be another input processor, as shown in Listing 2-8.
Listing 2-8 Example of Input Processor Chaining
#####################################
# Example of input processor chaining
#####################################
# Invoke the first input processor
webpage.jsp.link(continue)=firstInputProcessor
# Specify the fully qualified path name for the first input
# processor
firstInputProcessor.inputprocessor=com.beasys.commerce.webflow.
firstInputProcessorIP
# Invoke the second input processor if the execution of the first
# input processor succeeds
firstInputProcessor.inputprocessor.success=secondInputProcessor
# Specify the fully qualified class name for the second input
# processor
secondInputProcessor.inputprocessor=com.beasys.commerce.webflow.
secondInputProcessorIP
# Specify the result state for successful execution of the second
# input processor
secondInputProcessor.inputprocessor.success=nextwebpage.jsp
# Specify the result state for unsuccessful execution of the first
# input processor
firstInputProcessor.inputprocessor.exception(ProcessingException)=errorpage.jsp
# Specify the result state for successful execution of the second
# input processor
secondInputProcessor.inputprocessor.exception
(ProcessingException)=anothererrorpage.jsp
Further Customization of Input Processors
If you would like to customize your site even further, you might choose to create and implement your own input processors or define your own exceptions for use with input processors. However, there are some important rules you need to follow to accomplish these tasks. For more information, see Extending Webflow and Pipelines.
Note: Only Java/EJB programmers (or someone with similar technical knowledge and abilities) should attempt to customize input processors.
Using Pipelines with Webflow
Your site would not be considered an e-business if you simply displayed pages and performed some additional tasks with input processors. A customer's entire experience also relies upon the execution of back-end business processes that are related to where the customer is on your site and what the customer is trying to accomplish.
A Pipeline is an advanced mechanism invoked by the Webflow that initiates execution of specific tasks related to your business process. For example, if a customer attempts to move to another page on your site but you want to save the customer's identification information to a database first, you could use a Pipeline.
All Pipelines are collections of individual Pipeline components, which can be implemented as Java objects or stateless session EJBs. Pipeline components are the parts of a Pipeline that actually perform the tasks associated with the underlying business logic. When these tasks are complex, Pipeline components may also make calls to external services (other business objects). As in the case of input processors, the BEA Weblogic Commerce Server product provides predefined Pipeline components that you can use, or you can customize your site further by creating your own.
To successfully carry out business tasks, each Pipeline component must read attributes from a Pipeline session and if necessary, write modified versions of these attributes back to the Pipeline session. By default, attributes in the Pipeline session are available for the life of the HTTP session.
The WebLogic Commerce Server provides a default Pipeline properties file to get you up and running quickly, and to provide you with a working example of this concept. You can modify this file to change the business logic associated with your Web pages, without having to edit each page individually.
Note: It is not required that you use Pipelines to execute business logic in your customized Webflow. If you do not wish to use Pipelines, simply do not specify any Pipelines in the webflow.properties file. However, eliminating Pipelines and Pipeline components results in a less scalable, 2-tier architecture instead of the 3-tier architecture provided by the Webflow/Pipeline infrastructure.
This section provides information about the default Pipeline and instructions for customizing it, and describes how to invoke Pipelines from the Webflow.
Customizing Pipelines Using the pipeline.properties File
Much like the webflow.properties file specifies the flow of Web pages presented to a customer, the Pipeline properties file (pipeline.properties) specifies the flow of business logic as the customer moves through each page of the site. This properties file contains one section for each JavaServer Page (JSP) and includes comments for increased readability.
Generically, Pipeline definitions can be written as:
<pipelineName>.componentList
<pipelineName>.isTransactional=<true|false>
where componentList is a comma-separated list of Pipeline components to be executed in sequence.
Once all Pipeline definitions are complete, you must specify definitions for each Pipeline component in the Pipeline. Each Pipeline component definition consists of three properties: className, jndiName, and isEJBSessionBean.
Table 2-2 describes each of the Pipeline component properties in detail.
Notes: Lines in the pipeline.properties file should never contain spaces. Including spaces can result in errors that are difficult to locate.
Text within the pipeline.properties file is case sensitive.
Syntax of the pipeline.properties File
The top portion of the pipeline.properties file should contain only Pipeline definitions. Pipeline definitions include:
Listing 2-9 is a Pipeline definition that might be used in the pipline.properties file.
Listing 2-9 Pipeline Definition Example
orderPipeline=CalculateTaxPC,CalculateDiscountPC,TotalCartCostPC
orderPipeline.isTransactional=true
In this example, the Pipeline called orderPipeline consists of three Pipeline components (CalculateTaxPC, CalculateDiscountPC, TotalCartCostPC). The orderPipeline is also transactional.
Listing 2-10 shows the corresponding Pipeline component definitions that might be used in the pipeline.properties file.
Listing 2-10 Pipeline Component Definition Example
CalculateTaxPC.classname=com.beasys.commerce.ebusiness.order.
pipeline.CalculateTaxPC
CalculateTaxPC.isEJBSessionBean=false
CalculateTaxPC.jndiName=
CalculateDiscountPC.classname=com.beasys.commerce.ebusiness.order.pipeline.CalculateDiscountPC
CalculateDiscountPC.isEJBSessionBean=false
CalculateDiscountPC.jndiName=
TotalCartCostPC.classname=com.beasys.commerce.ebusiness.order
pipeline.TotalCartCostPC
TotalCartCostPC.isEJBSessionBean=true
TotalCartCostPC.jndiName=com.beasys.commerce.ebusiness.order.
pipeline.TotalCartCostPC
Default Pipeline
Listing 2-11 shows portions of the default Pipeline property file that handle obtaining product categories (with Pipeline components implemented as Java objects) and moving an item to a shopping cart (with a Pipeline component implemented as an EJB session bean). These can also be viewed in a simple text editor by opening WL_COMMERCE_HOME/pipeline.properties, where WL_COMMERCE_HOME is the top-level directory where you installed WebLogic Commerce Server.
Listing 2-11 Default Pipelines for Product Categories and Shopping Cart
#######################################################
# Java class Pipeline for obtaining product categories
#######################################################
# GetTopCategories Pipeline definition
GetTopCategories.componentList=GetCategoryPC,GetSubcategoriesPC
GetTopCategories.isTransactional=false
# GetCategoryPC Pipeline component definition
GetCategoryPC.classname=com.beasys.commerce.ebusiness.catalog.
pipeline.GetCategoryPC
GetCategoryPC.jndiName=
GetCategoryPC.isEJBSessionBean=false
# GetSubcategoriesPC Pipeline component definition
GetSubcategoriesPC.classname=com.beasys.commerce.ebusiness.
catalog.pipeline.GetSubcategoriesPC
GetSubcategoriesPC.jndiName=
GetSubcategoriesPC.isEJBSessionBean=false
#############################################################
# EJB session bean Pipeline for moving items to shopping cart
#############################################################
# MoveProductItemToShoppingCart Pipeline definition
MoveProductItemToShoppingCart.componentList=
MoveProductItemToShoppingCartPC
MoveProductItemToShoppingCart.isTransactional=true
# MoveProductItemToShoppingCartPC Pipeline component definition
MoveProductItemToShoppingCartPC.classname=com.beasys.commerce.
ebusiness.shoppingcart.pipeline.MoveProductItemToShoppingCartPC
MoveProductItemToShoppingCartPC.jndiName=com.beasys.commerce.
ebusiness.shoppingcart.pipeline.MoveProductItemToShoppingCartPC
MoveProductItemToShoppingCartPC.isEJBSessionBean=true
Dynamically Modifying Your Site's Pipelines
To dynamically modify your site's Pipelines, consider the following:
To modify your site's Pipelines, use the Webflow and Pipeline Editor Administration Tool. For more information about this tool, see Using the Webflow and Pipeline Editor.
Note: You can also modify Pipelines by editing the pipeline.properties file directly. However, this is not recommended. Once you edit the pipeline.properties file by hand, you may not be able to use the Webflow and Pipeline Editor. If you are certain you want to edit the file directly, follow these steps:
Eliminating Pipeline Components
The pipeline.properties file provides an easy way to eliminate Pipeline components without the need for advanced programming skills. For example, you might want to eliminate a Pipeline component that performs your tax calculations in the CommitOrder Pipeline. The definition in the default pipeline.properties file for the CommitOrder Pipeline is shown in Listing 2-12.
Listing 2-12 Default CommitOrder Pipeline
# CommitOrder
CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC,
TaxCalculateAndCommitLineLevelPC
To eliminate a Pipeline component using a text editor like Notepad, follow these steps:
Notes: Hand-editing the pipeline.properties file is not recommended. Instead, you should utilize the Webflow and Pipeline Editor tool, described in Using the Webflow and Pipeline Editor. These instructions are simply intended as an example for understanding how the content of the Pipeline configuration file is structured.
These instructions assume that the WebLogic Commerce Server software is installed and has been started.
You do not need to restart the server to view your changes if you have set the pipeline.hotdeploy.enable property to true in the weblogiccommerce.properties file.
Listing 2-13 CommitOrder Pipeline Without Tax Calculation Component
# CommitOrder
CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC
Note: There is no JSP that collects tax information. In the CommitOrder Pipeline example, you would not need to make changes to the user interface.
Reordering Pipeline Components
The pipeline.properties file also provides an easy way for you to modify the sequence of Pipeline components, without the need for advanced programming skills.
To reorder a Pipeline component using a text editor like Notepad, all you need to do is open the pipeline.properties file and change the order that the Pipeline components are listed in the Pipeline definition. Be sure to save your changes.
Notes: Hand-editing the pipeline.properties file is not recommended. Instead, you should utilize the Webflow and Pipeline Editor tool, described in Using the Webflow and Pipeline Editor. These instructions are simply intended as an example for understanding how the content of the Pipeline configuration file is structured.
Using the same CommitOrder Pipeline example, say you wanted to authorize the payment after calculating the tax instead of before it (as in the default OrderCommit Pipeline). Listing 2-14 shows how to do this.
Listing 2-14 CommitOrder Pipeline with Tax Component Reordered
# CommitOrder
CommitOrder.componentList=CommitOrderPC, TaxCalculateAndCommitLineLevelPC, AuthorizePaymentPC
Note: You do not need to restart the server to view your changes if you have set the pipeline.hotdeploy.enable property to true in the weblogiccommerce.properties file.
Using Pipelines in the Webflow
Pipelines are used in the webflow.properties file to initiate execution of the business logic required for a particular page. Each Pipeline must first be invoked by the Webflow, and then followed by a success and exception path. For example, if a customer were to submit their order for processing, the orderPipeline might be represented in the webflow.properties file as shown in Listing 2-15.
Listing 2-15 Using a Pipeline in the Webflow
shoppingcart.jsp.button(submit)=orderPipeline.pipeline
orderPipeline.pipeline.success=commitorder.jsp
orderPipeline.pipeline.exception(PipelineFatalException)=shoppingcart.jsp
The first transition indicates that when a customer clicks on the Submit button, the Webflow will turn control over to the Pipeline called orderPipeline. If the Pipeline executes successfully (that is, if each component in the Pipeline executes without error), the second transition sends the customer to a page that allows the customer to commit the order. If the Pipeline does not execute successfully, the third transition specifies the exception and directs the customer back to the shopping cart page.
Further Customization of Pipelines
If you would like to customize your site even further, you might choose to create and implement your own Pipelines or define your own exceptions for use with Pipelines. However, there are some important rules you need to follow to accomplish these tasks. For a more information, see Extending Webflow and Pipelines.
Note: Only Java/EJB programmers (or someone with similar technical knowledge and abilities) should attempt to customize Pipelines.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|