Adding a New Product Type
This tutorial shows you how to add a new product type by implementing three interfaces: CPType, ScreenNavigationCategory, and ScreenNavigationEntry.
Product types can be used to group products that share similar characteristics. Liferay Commerce provides three product types out-of-the-box: Simple, Grouped, and Virtual.
Overview
Deploy an Example
In this section, get an example product type 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 Type.
-
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 Liferay Docker container console.
-
Verify that the example product type was added. Open your browser to
https://localhost:8080
. Click the Applications Menu () and navigate to Commerce → Products. Then click on the (+) icon to add a new product. The new product type (“Example”) is present in the list of types to choose from.
In Liferay Commerce 2.1 and earlier, find the products page by navigating to Control Panel → Commerce → Products.
Congratulations, you’ve successfully built and deployed a new product type that implements CPType
.
Next, let’s dive deeper to learn more.
Walk Through the Example
In this section, we review the example we deployed and create two classes: a product type class and a screen navigation entry class for a custom screen. Walk through the following:
- Annotate the Product Type Class for OSGi Registration
- Review the
CPType
Interface - Annotate the Screen Navigation Entry Class for OSGi Registration
- Review the
ScreenNavigationCategory
Interface - Review the
ScreenNavigationEntry
Interface - Complete the Product Type
Annotate the Product Type Class for OSGi Registration
Our product type class implements the CPType
interface:
The product type name must be a unique value so that Liferay Commerce can distinguish our product type from existing product types.
The commerce.product.type.display.order
value indicates how far into the list of product types our product type appears in the UI. For example, the virtual product type has a value of 15. Giving our product type a value of 16 ensures that it appears immediately after the virtual type.
Review the CPType
Interface
Implement the following methods of CPType
in the product type class:
This method is where any custom deletion logic for the product type is added.
This returns a text label that describes the product type. See the C1N4CPType.java
class in liferay-c1n4.zip/c1n4-web/src/main/java/com/acme/c1n4/web/internal/commerce/product/type
for a reference in retrieving the label with a language key.
This returns the name of our product type. This name may be a language key that corresponds to the name that appears in the UI.
Annotate the Screen Navigation Entry Class for OSGi Registration
Our screen navigation entry class implements both the ScreenNavigationCategory
and ScreenNavigationEntry
interfaces:
It is important to provide a distinct key for the navigation screen class so that Liferay Commerce can distinguish it as a separate screen from the existing screens. Reusing a key that is already in use overrides the existing associated navigation screen.
The screen.navigation.category.order
and screen.navigation.entry.order
values determine what position in the product type screens this screen appears. For example, the Details screen class has these values set to 10; setting them to 11 ensures that our custom screen appears after it in the list.
Review the ScreenNavigationCategory
Interface
Implement the following methods in the screen navigation entry class:
Returns a unique identifier for the category associated with the screen navigation entry.
Returns a text label for the screen navigation entry displayed in the UI. For an example of using a language key to retrieve the label, refer to the C1N4ScreenNavigationEntry.java
class in liferay-c1n4.zip/c1n4-web/src/main/java/com/acme/c1n4/web/internal/frontend/taglib/servlet/taglib
.
Returns a key to indicate where the screen should appear in Liferay. Use the string "cp.definition.general"
to ensure the screen appears among other product screens.
Review the ScreenNavigationEntry
Interface
Continue to build on the screen navigation entry class with the following methods:
Returns a unique identifier for the screen navigation category associated with the screen.
Returns a unique identifier for the screen navigation entry. It returns the same value as getCategoryKey
.
This method is identical to getScreenNavigationKey
from the ScreenNavigationCategory
interface. We implemented this method by returning the string value "cp.definition.general"
.
This method is where you add the code to render a customized screen for the product type.
Complete the Product Type
The product type is comprised of backend logic for deleting the product, logic to render the screen in the navigation menu, and the custom screen itself. Do the following:
- Configure the
ServletContext
for the module. - Implement the
ScreenNavigationEntry
’srender
method. - Override the
ScreenNavigationEntry
’sisVisible
method. - Add the product type deletion logic to
deleteCPDefinition
. - Add a JSP to render the custom screen.
- Add the language key to
Language.properties
.
Configure the ServletContext
for the Module
Define the ServletContext
in our ScreenNavigationEntry
class 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-c1n4.zip/c1n4-web
. These values must match for the ServletContext
to locate the JSP.
We 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 /c1n4-web
. See the bnd.bnd
file for a reference on these values.
Implement the ScreenNavigationEntry
’s render
Method
Use a JSPRenderer
to render the JSP for our product type’s custom screen (in our example, c1n4.jsp
in liferay-c1n4.zip/c1n4-web/src/main/resources/META-INF/resources
). Provide the ServletContext
as a parameter to find the JSP we have created.
Override the ScreenNavigationEntry
’s isVisible
Method
Implement logic here to determine when to show the custom screen. In our example, we only check whether the product type from the CPDefinition
matches our example product type.
Add the Product Type Deletion Logic to deleteCPDefinition
Our example does not require any logic to be added to deleteCPDefinition
.
Add a JSP to Render the Custom Screen
In our example, we are adding a JSP that prints “Hello C1N4.”.
Implement any other inputs or actions desired on the custom screen here, such as a form or MVC action command. See MVC Action Command for more information on adding an MVC action command that can be accessed from the JSP.
Add the Language Key to Language.properties
Add the language key and its value to a Language.properties
file in liferay-c1n4.zip/c1n4-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 CPType
interface, and have implemented a new product type with its own custom screen to Liferay Commerce.