Implementing a Custom Checkout Step

This tutorial shows you how to add a custom checkout step by implementing the CommerceCheckoutStep interface.

A checkout step represents one screen of the checkout process for a customer. Liferay Commerce provides several checkout steps out-of-the-box, including essential steps like the payment method step and the order confirmation step.

Out-of-the-box checkout steps

Deploy an Example

In this section, get an example checkout step up and running on your instance of Liferay Commerce.

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip the Acme Commerce Checkout Step.

curl https://resources.learn.liferay.com/commerce/latest/en/developer-guide/sales/liferay-n8n6.zip -O

unzip liferay-n8n6.zip

Build and deploy the example.
```
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
```
Note

This command is the same as copying the deployed jars to /opt/liferay/osgi/modules on the Docker container.
Confirm the deployment in the Docker container console.
```
STARTED com.acme.n8n6.web_1.0.0
```
Verify that the example checkout step was added. Open your browser to https://localhost:8080 and navigate to a catalog on any Liferay Commerce site. Add an item to the cart, view the cart, and then click “Checkout”. The new “N8N6 Commerce Checkout Step” appears in the list of checkout steps.

New checkout step

Congratulations, you’ve successfully built and deployed a new checkout step that implements CommerceCheckoutStep.

Next, let’s dive deeper to learn more.

Walk Through the Example

In this section, review the example we deployed. First, annotate the class for OSGi registration. Second, review the CommerceCheckoutStep interface. And third, complete our implementation of CommerceCheckoutStep.

Note

To simplify implementing CommerceCheckoutStep, we extend BaseCommerceCheckoutStep for its base functionality.

Annotate the Class for OSGi Registration

@Component(
   property = {
   "commerce.checkout.step.name=n8n6",
   "commerce.checkout.step.order:Integer=21"
   },
   service = CommerceCheckoutStep.class
)
public class N8N6CommerceCheckoutStep extends BaseCommerceCheckoutStep {

The checkout step name must be a unique value so that Liferay Commerce can distinguish our checkout step from existing checkout steps.

The commerce.checkout.step.order value indicates how far into the checkout process the checkout step appears. For example, the shipping method checkout step has a value of 20. Giving our checkout step a value of 21 ensures that it appears immediately after the shipping method step.

Review the `CommerceCheckoutStep` Interface

Implement the following methods in addition to extending the base class:

public String getName();

This method returns the name of our checkout step. This name may be a language key that corresponds to the name that appears in the UI.

public void processAction(
      ActionRequest actionRequest, ActionResponse actionResponse)
   throws Exception;

The processAction method may be used to implement business logic with the information passed through the ActionRequest if backend processing is required.

public void render(
      HttpServletRequest httpServletRequest,
      HttpServletResponse httpServletResponse)
   throws Exception;

This is where we add the code to render a customized screen for our checkout step.

Complete the Checkout Step

The checkout step is comprised of a custom screen and backend logic to process any input. Do the following:

Configure the ServletContext for the module.
Implement the render method.
Add business logic to processAction.
Add a JSP to render the custom screen.
Add the language key to Language.properties.

Configure the `ServletContext` for the Module

Define the ServletContext using the symbolic name of our bundle so that it can find the JSP in our module:

@Reference(target = "(osgi.web.symbolicname=com.acme.n8n6.web)")
private ServletContext _servletContext;

The value we set for osgi.web.symbolicname matches the value for Bundle-SymbolicName in our bnd.bnd in liferay-n8n6.zip/n8n6-web. These values must match for the ServletContext to locate the JSP.

We must also declare a unique value for Web-ContextPath in our bnd.bnd file so the ServletContext is correctly generated. In our example, Web-ContextPath is set to /n8n6-web. See the bnd.bnd file for a reference on these values.

Implement the `render` Method

@Override
public void render(
      HttpServletRequest httpServletRequest,
      HttpServletResponse httpServletResponse)
   throws Exception {

   _jspRenderer.renderJSP(
      _servletContext, httpServletRequest, httpServletResponse,
      "/terms_and_conditions.jsp");
}

@Reference
private JSPRenderer _jspRenderer;

@Reference(target = "(osgi.web.symbolicname=com.acme.n8n6.web)")
private ServletContext _servletContext;

Use a JSPRenderer to render the JSP for our checkout step (in this case, terms_and_conditions.jsp in liferay-n8n6.zip/n8n6-web/src/main/resources/META-INF/resources). Provide the ServletContext as a parameter to find the JSP we created.

n8n6-commerce-checkout-step=N8N6 Commerce Checkout Step

See Localizing Your Application for more information.

Conclusion

Congratulations! You now know the basics for implementing the CommerceCheckoutStep interface, and have added a new checkout step to Liferay Commerce.

Capability: