SAP Hybris新手教程：如何在Backoffice中创建自定义Widget

Hey there! As someone who started out with SAP Hybris Backoffice not too long ago, I totally get how overwhelming it can be to wrap your head around extensions and custom widgets. Let me break this down for you with clear steps and a simple example to make it stick.

Backoffice extensions are the building blocks for customizing the SAP Hybris Backoffice interface and functionality. They let you add new UI components, business logic, integration points, or modify existing Backoffice behavior. These extensions follow Hybris's standard extension structure, typically ending with the -backoffice suffix (e.g., mycustombackoffice).

Let's create a simple interactive widget that takes user input and displays a response. Here's how to do it:

2.1 Create a New Backoffice Extension #

First, generate a dedicated Backoffice extension using Hybris's command-line tool:

1. Open your Hybris bin directory in a terminal.
2. Run the command:

   ant extgen
   

3. When prompted, select the backoffice template, enter your extension name (e.g., mycustombackoffice), and fill in your company prefix (e.g., mycompany).
4. Add your new extension to localextensions.xml to enable it:

   <extension name="mycustombackoffice"/>
   

2.2 Define the Widget Metadata #

Every widget needs a definition file to tell Backoffice about its details.

1. In your extension, create the directory resources/widgets/myCustomWidget.
2. Inside that folder, create widgetDefinition.xml with this content:

   <widget-definition id="com.mycompany.mycustombackoffice.widgets.myCustomWidget"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:noNamespaceSchemaLocation="http://www.hybris.com/schema/cockpitng/widget-definition.xsd">
       <name>My Custom Widget</name>
       <description>A simple interactive widget for beginners</description>
       <version>1.0</version>
       <author>Your Name</author>
       <view src="zul/myCustomWidget.zul"/>
       <controller class="com.mycompany.mycustombackoffice.widgets.MyCustomWidgetController"/>
       <requires-extension name="backoffice"/>
   </widget-definition>
   

2.3 Build the Widget UI with ZUL #

Hybris Backoffice uses ZK Framework's ZUL language for UI. Create the view file:

1. Create the directory resources/widgets/myCustomWidget/zul.
2. Add myCustomWidget.zul with this code:

   <window xmlns="http://www.zkoss.org/2005/zul"
           xmlns:widget="http://www.hybris.com/cockpitng/widget"
           title="My First Custom Widget" border="normal" width="450px">
       <vbox spacing="12px" padding="15px">
           <label value="Try entering some text below!"/>
           <textbox id="userInput" placeholder="Type here..."/>
           <button label="Show My Input" onClick="widget.onButtonClicked()"/>
           <label id="outputText" value="" style="color: #2c3e50; font-weight: bold;"/>
       </vbox>
   </window>
   

2.4 Implement the Widget Controller #

The controller handles the widget's logic. Create the Java class:

1. In your extension's src/main/java directory, create the package com.mycompany.mycustombackoffice.widgets.
2. Add MyCustomWidgetController.java with this code:

   package com.mycompany.mycustombackoffice.widgets;
   
   import com.hybris.cockpitng.widgets.controllers.AbstractWidgetController;
   import org.zkoss.zul.Label;
   import org.zkoss.zul.Textbox;
   
   public class MyCustomWidgetController extends AbstractWidgetController {
   
       private Textbox userInput;
       private Label outputText;
   
       // Triggered when the button is clicked
       public void onButtonClicked() {
           String input = userInput.getValue();
           if (input.isEmpty()) {
               outputText.setValue("Please enter some text first!");
           } else {
               outputText.setValue("You entered: " + input);
           }
       }
   
       // Getters and setters for ZUL components (required for framework injection)
       public Textbox getUserInput() {
           return userInput;
       }
   
       public void setUserInput(Textbox userInput) {
           this.userInput = userInput;
       }
   
       public Label getOutputText() {
           return outputText;
       }
   
       public void setOutputText(Label outputText) {
           this.outputText = outputText;
       }
   }
   

2.5 Register the Widget with Backoffice #

Tell Backoffice about your new widget:

1. Create resources/backoffice-widgets.xml in your extension:

   <widgets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="http://www.hybris.com/schema/cockpitng/widgets.xsd">
       <widget id="myCustomWidget" widgetDefinitionId="com.mycompany.mycustombackoffice.widgets.myCustomWidget"/>
   </widgets>
   

2.6 Build and Test the Widget #

1. Run a full build to compile your extension:

   ant clean all
   

2. Start your Hybris server and log into Backoffice.
3. Enable the Widget Editor by clicking the pencil icon in the top-right corner.
4. Click "Add Widget", search for "My Custom Widget", drag it to any dashboard area, and save the layout.
5. Test it: Enter text, click the button, and see the output update!

• Hot Reload: For faster development, enable ZK hot reload in local.properties with cockpitng.hot.reload=true (no need to rebuild every time you change ZUL files).
• ZK Documentation: Familiarize yourself with basic ZUL components (buttons, textboxes, labels) since Backoffice relies heavily on ZK.
• Component Injection: Make sure your controller has getters/setters for every ZUL component you reference—this is how the Backoffice framework connects the UI to your logic.

内容的提问来源于stack exchange，提问作者CHARAFI Saad