如何在SugarCRM主HBS文件中引入局部HBS实现弹窗向导

问题背景 #

需要在SugarCRM弹窗内实现向导式多页面效果，尝试过自定义Handlebars助手（仅支持字符串传递）、iframe/PHP include（导致系统卡顿），均无法满足需求，需寻求官方规范内的实现方式。

正确实现方案：基于Handlebars局部模板+前端步骤控制 #

SugarCRM官方推荐使用Handlebars的**局部模板（Partial）**结合前端视图逻辑来实现多页面向导，既符合框架规范，又能避免性能问题。

步骤1：创建局部HBS模板文件

在对应模块的自定义目录下创建各向导步骤的局部模板，例如：

• custom/modules/Accounts/tpls/wizard-step1.hbs（步骤1内容）
• custom/modules/Accounts/tpls/wizard-step2.hbs（步骤2内容）
• custom/modules/Accounts/tpls/wizard-step3.hbs（步骤3内容）

示例局部模板内容（wizard-step1.hbs）：

<div class="step-content">
    <h4>基本信息填写</h4>
    <div class="form-group">
        <label>账户名称</label>
        {{input type="text" name="name" value=model.name}}
    </div>
</div>

步骤2：注册局部模板

在自定义JS助手文件中注册这些局部模板，确保Sugar能识别并加载：

(function(app) {
    app.events.on("app:init", function() {
        // 注册向导步骤局部模板
        Handlebars.registerPartial('wizardStep1', app.template.get('custom/modules/Accounts/tpls/wizard-step1'));
        Handlebars.registerPartial('wizardStep2', app.template.get('custom/modules/Accounts/tpls/wizard-step2'));
        Handlebars.registerPartial('wizardStep3', app.template.get('custom/modules/Accounts/tpls/wizard-step3'));
    });
})(SUGAR.App);

步骤3：主弹窗HBS文件实现步骤切换逻辑

在弹窗的主HBS文件中，通过条件渲染控制不同步骤的显示，同时添加步骤切换按钮：

<div class="wizard-modal-container">
    <!-- 步骤内容区域 -->
    {{#if currentStep '===' 1}}
        {{> wizardStep1}}
    {{/if}}
    {{#if currentStep '===' 2}}
        {{> wizardStep2}}
    {{/if}}
    {{#if currentStep '===' 3}}
        {{> wizardStep3}}
    {{/if}}

    <!-- 步骤控制按钮 -->
    <div class="wizard-controls">
        {{#if currentStep '>' 1}}
            <button class="btn btn-default" data-action="prev-step">上一步</button>
        {{/if}}
        {{#if currentStep '<' totalSteps}}
            <button class="btn btn-primary" data-action="next-step">下一步</button>
        {{/if}}
        {{#if currentStep '===' totalSteps}}
            <button class="btn btn-success" data-action="complete-wizard">完成</button>
        {{/if}}
    </div>
</div>

步骤4：视图JS文件处理步骤切换逻辑

在弹窗对应的视图JS中，初始化步骤变量并绑定按钮事件：

({
    extendsFrom: 'BaseModalView',
    initialize: function(options) {
        this._super('initialize', [options]);
        // 初始化向导状态
        this.model.set({
            currentStep: 1,
            totalSteps: 3
        });
        // 绑定步骤切换事件
        this.$el.on('click', '[data-action="prev-step"]', this.prevStep.bind(this));
        this.$el.on('click', '[data-action="next-step"]', this.nextStep.bind(this));
        this.$el.on('click', '[data-action="complete-wizard"]', this.completeWizard.bind(this));
    },
    prevStep: function() {
        let current = this.model.get('currentStep');
        if (current > 1) {
            this.model.set('currentStep', current - 1);
        }
    },
    nextStep: function() {
        let current = this.model.get('currentStep');
        let total = this.model.get('totalSteps');
        if (current < total) {
            this.model.set('currentStep', current + 1);
        }
    },
    completeWizard: function() {
        // 提交向导数据
        this.model.save(null, {
            success: () => {
                app.alert.show('wizard-success', {
                    level: 'success',
                    messages: '向导配置完成',
                    autoClose: true
                });
                this.closeModal();
            },
            error: () => {
                app.alert.show('wizard-error', {
                    level: 'error',
                    messages: '提交失败，请重试',
                    autoClose: true
                });
            }
        });
    }
})

为什么之前的方案不可行？ #

1. 自定义Handlebars助手：仅能返回字符串，无法加载预编译的模板，无法绑定Sugar的模型上下文，不适合复杂页面渲染。
2. iframe：额外加载独立页面，占用资源导致卡顿，且与Sugar上下文隔离，数据交互繁琐。
3. PHP include：HBS是前端模板，运行在浏览器端，无法执行服务器端的PHP代码，完全无效。

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