b2c-business-manager-extensions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Business Manager Extensions Skill

Business Manager扩展技能

This skill guides you through creating Business Manager (BM) extension cartridges to customize the admin interface.

本技能将指导您创建Business Manager（BM）扩展cartridge，以自定义管理界面。

Overview

概述

BM extensions allow you to add custom functionality to Business Manager:

Extension Type	Purpose
Menu Items	Add top-level menu sections
Menu Actions	Add functional links under menus
Dialog Actions	Add buttons to existing BM pages
Form Extensions	Add fields to existing forms

BM扩展允许您为Business Manager添加自定义功能：

扩展类型	用途
菜单项	添加顶级菜单板块
菜单操作	在菜单下添加功能链接
对话框操作	在现有BM页面中添加按钮
表单扩展	在现有表单中添加字段

File Structure

文件结构

/bm_my_extension
    /cartridge
        bm_extensions.xml           # Extension definitions (required)
        /controllers
            MyExtension.js          # Controller for menu actions
        /templates
            /default
                /extensions
                    mypage.isml     # Custom BM pages
        /static
            /default
                /icons
                    my-icon.gif     # Menu icons

/bm_my_extension
    /cartridge
        bm_extensions.xml           # Extension definitions (required)
        /controllers
            MyExtension.js          # Controller for menu actions
        /templates
            /default
                /extensions
                    mypage.isml     # Custom BM pages
        /static
            /default
                /icons
                    my-icon.gif     # Menu icons

Basic bm_extensions.xml

基础bm_extensions.xml

xml

<?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://www.demandware.com/xml/extensibility/2013-04-24">
    <!-- Menu Item: Creates section in navigation -->
    <menuitem id="my-tools" name="label.menu.mytools"
              site="false" position="10">
        <icon path="icons/my-icon.gif"/>
    </menuitem>

    <!-- Menu Action: Creates link under menu item -->
    <menuaction id="my-dashboard" menupath="my-tools"
                name="label.action.dashboard">
        <exec pipeline="MyExtension" node="Dashboard"/>
        <sub-pipelines>
            <pipeline name="MyExtension"/>
        </sub-pipelines>
    </menuaction>
</extensions>

xml

<?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://www.demandware.com/xml/extensibility/2013-04-24">
    <!-- Menu Item: Creates section in navigation -->
    <menuitem id="my-tools" name="label.menu.mytools"
              site="false" position="10">
        <icon path="icons/my-icon.gif"/>
    </menuitem>

    <!-- Menu Action: Creates link under menu item -->
    <menuaction id="my-dashboard" menupath="my-tools"
                name="label.action.dashboard">
        <exec pipeline="MyExtension" node="Dashboard"/>
        <sub-pipelines>
            <pipeline name="MyExtension"/>
        </sub-pipelines>
    </menuaction>
</extensions>

Menu Items

菜单项

Create top-level navigation sections:

xml

<menuitem id="custom-tools"
          name="label.menu.customtools"
          site="false"
          position="10">
    <description>Custom administration tools</description>
    <icon path="icons/tools-icon.gif"/>
</menuitem>

Attribute	Required	Description
`id`	Yes	Unique identifier
`name`	Yes	Resource key for display name
`site`	No	`true` = Site menu, `false` = Admin menu (default: true)
`position`	No	Sort order (higher = higher in list)

创建顶级导航板块：

xml

<menuitem id="custom-tools"
          name="label.menu.customtools"
          site="false"
          position="10">
    <description>Custom administration tools</description>
    <icon path="icons/tools-icon.gif"/>
</menuitem>

属性	是否必填	说明
`id`	是	唯一标识符
`name`	是	显示名称对应的资源键
`site`	否	`true` = 站点菜单， `false` = 管理菜单（默认值：true）
`position`	否	排序顺序（值越大，在列表中的位置越靠前）

Menu Actions

菜单操作

Add functional pages under menu items:

xml

<menuaction id="product-export"
            menupath="custom-tools"
            name="label.action.productexport">
    <description>Export products to CSV</description>
    <exec pipeline="ProductExport" node="Start"/>
    <sub-pipelines>
        <pipeline name="ProductExport"/>
    </sub-pipelines>
    <icon path="icons/export-icon.gif"/>
</menuaction>

Attribute	Required	Description
`id`	Yes	Unique identifier
`menupath`	No	Parent menu item ID
`name`	Yes	Resource key for display name

Note: For controllers, use

pipeline="ControllerName"

and

node="ActionName"

在菜单项下添加功能页面：

xml

<menuaction id="product-export"
            menupath="custom-tools"
            name="label.action.productexport">
    <description>Export products to CSV</description>
    <exec pipeline="ProductExport" node="Start"/>
    <sub-pipelines>
        <pipeline name="ProductExport"/>
    </sub-pipelines>
    <icon path="icons/export-icon.gif"/>
</menuaction>

属性	是否必填	说明
`id`	是	唯一标识符
`menupath`	否	父菜单项ID
`name`	是	显示名称对应的资源键

注意： 对于控制器，请使用

pipeline="ControllerName"

和

node="ActionName"

。

Dialog Actions

对话框操作

Add buttons to existing BM pages:

xml

<dialogaction id="order-export-btn"
              menuaction-ref="order-search"
              xp-ref="OrderPage-OrderDetails">
    <exec pipeline="OrderExport" node="Export"/>
    <icon path="icons/export.gif"/>
    <parameters>
        <parameter name="OrderNo"/>
    </parameters>
</dialogaction>

Attribute	Required	Description
`id`	Yes	Unique identifier
`menuaction-ref`	Yes	Parent menu action ID
`xp-ref`	Yes	Extension point ID

Common extension points:

OrderPage-OrderDetails

ProductPage-Details

CustomerPage-Profile

在现有BM页面中添加按钮：

xml

<dialogaction id="order-export-btn"
              menuaction-ref="order-search"
              xp-ref="OrderPage-OrderDetails">
    <exec pipeline="OrderExport" node="Export"/>
    <icon path="icons/export.gif"/>
    <parameters>
        <parameter name="OrderNo"/>
    </parameters>
</dialogaction>

属性	是否必填	说明
`id`	是	唯一标识符
`menuaction-ref`	是	父菜单操作ID
`xp-ref`	是	扩展点ID

常见扩展点：

OrderPage-OrderDetails

、

ProductPage-Details

、

CustomerPage-Profile

Form Extensions

表单扩展

Add fields to existing BM forms:

xml

<formextension id="order-search-extension">
    <valueinput type="string" name="customOrderField">
        <label xml:lang="x-default">Custom Field</label>
        <label xml:lang="de">Benutzerdefiniertes Feld</label>
    </valueinput>
    <valueinput type="string" name="exportStatus">
        <label xml:lang="x-default">Export Status</label>
        <option>Pending</option>
        <option>Exported</option>
        <option>Failed</option>
    </valueinput>
</formextension>

在现有BM表单中添加字段：

xml

<formextension id="order-search-extension">
    <valueinput type="string" name="customOrderField">
        <label xml:lang="x-default">Custom Field</label>
        <label xml:lang="de">Benutzerdefiniertes Feld</label>
    </valueinput>
    <valueinput type="string" name="exportStatus">
        <label xml:lang="x-default">Export Status</label>
        <option>Pending</option>
        <option>Exported</option>
        <option>Failed</option>
    </valueinput>
</formextension>

Controller Example

控制器示例

javascript

'use strict';

var ISML = require('dw/template/ISML');
var URLUtils = require('dw/web/URLUtils');

exports.Dashboard = function () {
    ISML.renderTemplate('extensions/dashboard', {
        title: 'My Dashboard',
        data: getReportData()
    });
};
exports.Dashboard.public = true;

exports.ProcessAction = function () {
    var params = request.httpParameterMap;
    var itemId = params.itemId.stringValue;

    // Process the action
    var result = processItem(itemId);

    // Redirect back or show result
    response.redirect(URLUtils.url('MyExtension-Dashboard', 'result', result));
};
exports.ProcessAction.public = true;

javascript

'use strict';

var ISML = require('dw/template/ISML');
var URLUtils = require('dw/web/URLUtils');

exports.Dashboard = function () {
    ISML.renderTemplate('extensions/dashboard', {
        title: 'My Dashboard',
        data: getReportData()
    });
};
exports.Dashboard.public = true;

exports.ProcessAction = function () {
    var params = request.httpParameterMap;
    var itemId = params.itemId.stringValue;

    // Process the action
    var result = processItem(itemId);

    // Redirect back or show result
    response.redirect(URLUtils.url('MyExtension-Dashboard', 'result', result));
};
exports.ProcessAction.public = true;

Template Example

模板示例

html

<!DOCTYPE html>
<html>
<head>
    <title>${pdict.title}</title>
    <link rel="stylesheet" href="${URLUtils.staticURL('/css/bm-custom.css')}"/>
</head>
<body>
    <div class="bm-content">
        <h1>${pdict.title}</h1>

        <table class="bm-table">
            <thead>
                <tr>
                    <th>ID</th>
                    <th>Name</th>
                    <th>Actions</th>
                </tr>
            </thead>
            <tbody>
                <isloop items="${pdict.data}" var="item">
                    <tr>
                        <td>${item.id}</td>
                        <td>${item.name}</td>
                        <td>
                            <a href="${URLUtils.url('MyExtension-ProcessAction', 'itemId', item.id)}">
                                Process
                            </a>
                        </td>
                    </tr>
                </isloop>
            </tbody>
        </table>
    </div>
</body>
</html>

html

<!DOCTYPE html>
<html>
<head>
    <title>${pdict.title}</title>
    <link rel="stylesheet" href="${URLUtils.staticURL('/css/bm-custom.css')}"/>
</head>
<body>
    <div class="bm-content">
        <h1>${pdict.title}</h1>

        <table class="bm-table">
            <thead>
                <tr>
                    <th>ID</th>
                    <th>Name</th>
                    <th>Actions</th>
                </tr>
            </thead>
            <tbody>
                <isloop items="${pdict.data}" var="item">
                    <tr>
                        <td>${item.id}</td>
                        <td>${item.name}</td>
                        <td>
                            <a href="${URLUtils.url('MyExtension-ProcessAction', 'itemId', item.id)}">
                                Process
                            </a>
                        </td>
                    </tr>
                </isloop>
            </tbody>
        </table>
    </div>
</body>
</html>

Localization

本地化

Add resource bundles for labels:

templates/resources/bm_extensions.properties:

properties

label.menu.customtools=Custom Tools
label.action.dashboard=Dashboard
label.action.productexport=Product Export

templates/resources/bm_extensions_de.properties:

properties

label.menu.customtools=Benutzerdefinierte Werkzeuge
label.action.dashboard=Instrumententafel
label.action.productexport=Produktexport

为标签添加资源包：

templates/resources/bm_extensions.properties:

properties

label.menu.customtools=Custom Tools
label.action.dashboard=Dashboard
label.action.productexport=Product Export

templates/resources/bm_extensions_de.properties:

properties

label.menu.customtools=Benutzerdefinierte Werkzeuge
label.action.dashboard=Instrumententafel
label.action.productexport=Produktexport

Enabling the Extension

启用扩展

Add cartridge to Business Manager site's cartridge path:
- Administration > Sites > Manage Sites > Business Manager
- Add cartridge ID to cartridge path
Grant permissions to roles:
- Administration > Organization > Roles
- Select role > Business Manager Modules
- Enable your custom modules

将cartridge添加到Business Manager站点的cartridge路径中：
- 进入管理 > 站点 > 管理站点 > Business Manager
- 将cartridge ID添加到cartridge路径
为角色授予权限：
- 进入管理 > 组织 > 角色
- 选择角色 > Business Manager模块
- 启用您的自定义模块

Best Practices

最佳实践

Prefix IDs with your organization name to avoid conflicts
Use resource keys for all displayed text (localization)
Keep cartridge separate - don't mix with storefront cartridges
Test permissions with different user roles
Don't reference internal BM URLs - they may change

为ID添加前缀：使用您的组织名称作为ID前缀，避免冲突
使用资源键：所有显示文本都使用资源键（支持本地化）
独立存放cartridge：不要与前台cartridge混合存放
测试权限：使用不同用户角色测试权限
不要引用BM内部URL：这些URL可能会发生变化

Detailed Reference

详细参考

Extensions XML Reference - Complete XML schema and examples

扩展XML参考文档 - 完整的XML模式和示例