Implementing a Custom Product Content Renderer
This tutorial shows you how to add a custom product content renderer by implementing the CPContentRenderer interface.
A product content renderer provides a style of displaying product details for a specific product type, in a variety of widgets that can display products. Liferay Commerce provides product content renderers for each out-of-the-box product type, such as SimpleCPContentRenderer for Simple products.
Overview
Deploy an Example
In this section, get an example product content renderer up and running on your instance of Liferay Commerce.
Start a new Liferay instance by running
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 Product Content Renderer.
-
Build and deploy the example.
NoteThis 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.
-
Verify that the example product content renderer was added. Open your browser to
https://localhost:8080
and navigate to any catalog with products in Liferay Commerce. Click on the product to see the Product Details widget, then click Configuration for the widget.Under the Custom Renderer section, select Simple. Below the Simple Commerce Product Type Renderer Key drop-down, select the new renderer (“Q4F7 Commerce Product Content Renderer”).
-
When you select a product, the new renderer shows only the product’s SKU, price, availability, and stock quantity.
Congratulations, you’ve successfully built and deployed a new custom product content renderer that implements CPContentRenderer
.
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 CPContentRenderer
interface. And third, complete our implementation of CPContentRenderer
.
Annotate the Class for OSGi Registration
It is important to provide a distinct key for the product content renderer so that Liferay Commerce can distinguish the new renderer from others in the product content renderer registry. Reusing a key that is already in use overrides the existing associated renderer.
The commerce.product.content.renderer.order
property is an integer value that Commerce uses to list the renderer in the UI. Renderers appear in ascending order. For example, the SimpleCPContentRenderer has this property set to the minimum integer value, so other renderers for Simple type products appear after it in the list.
The commerce.product.content.renderer.type
property determines what type of product this renderer can be used for. In our example, we use a Simple type, so the renderer appears under the Simple category in the UI.
Review the CPContentRenderer
Interface
Implement the following methods:
This method provides a unique identifier for the product content renderer in the product content renderer registry. The key can be used to fetch the renderer from the registry. Reusing a key that is already in use overrides the existing associated renderer.
This returns a text label that describes the product content renderer. See the implementation in the Q4F7CPContentRenderer.java class in liferay-q4f7.zip/q4f7-web/src/main/java/com/acme/q4f7/web/internal/commerce/product/content/renderer
for a reference in retrieving the label with a language key.
This is where we add the code to render a customized view for our product content renderer.
There are several ways to define a view: JSP, Freemarker template, or Soy template. In our example, use a JSP.
Complete the Product Content Renderer
The product content renderer is comprised of a custom view that we define and render. Do the following:
- Configure the
ServletContext
for the module. - Implement the
render
method. - Add a JSP for the custom view.
- 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:
The value we set for osgi.web.symbolicname
matches the value for Bundle-SymbolicName
in our bnd.bnd
file in liferay-q4f7.zip/q4f7-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 /q4f7-web
. See the bnd.bnd
file for a reference on these values.
Implement the render
Method
Use a JSPRenderer
to render the JSP for our product content renderer (in this case, view.jsp
in liferay-q4f7.zip/q4f7-web/src/main/resources/META-INF/resources
). Provide the ServletContext
as a parameter to find the JSP we have created.
Add a JSP for the Custom View
CPContentHelper is a class that retrieves information about a particular product.
CPCatalogEntry represents the displayed product itself. We get more information about the product with its default SKU, contained in a CPSku object.
We use Liferay Commerce’s add_to_cart_button.jsp to insert the “Add to Cart” feature to our view.
Add the Language Key to Language.properties
Add the language key and its value to a Language.properties
file in liferay-q4f7.zip/q4f7-web/src/main/resources/content
within our module:
See Localizing Your Application for more information.
Conclusion
Congratulations! You now know the basics for implementing the CPContentRenderer
interface, and have added a new product content renderer to Liferay Commerce.