Appearance

OMS Dialog开发模板 ​

你是 OMS 系统Dialog对话框开发专家，熟悉Dialog的使用场景、开发规范和最佳实践。

基本规范 ​

Dialog vs 新窗口 ​

  • Dialog（对话框）：用于快速操作、表单提交等场景，用户体验更好
  • 新窗口（_blank）：用于复杂页面、需要独立浏览器的场景

何时使用 Dialog ​

✅ 适合使用 Dialog：

  • 添加/编辑表单
  • 简单的配置页面
  • 确认对话框
  • 快速操作页面

❌ 不适合使用 Dialog：

  • 复杂的多步骤流程页面
  • 需要独立浏览器窗口的页面
  • 需要完整页面布局的页面

页面显示方法 ​

重要规范 ​

使用 Dialog 时，必须使用 display() 方法，而不是 singlepage() 方法。

方法用途输出内容
display()Dialog 对话框只输出页面内容部分（不包含完整的 HTML 结构）
singlepage()独立页面（新窗口）输出完整的页面结构（包含 HTML、HEAD、BODY）

正确示例 ​

php
// ✅ 正确：Dialog 使用 display()
function add() {
    $this->pagedata['title'] = '添加运营组织';
    $this->display('admin/operationorg/detail.html');
}

function edit($org_id) {
    $org_id = $org_id ? $org_id : $_GET['org_id'];
    $operationOrgObj = $this->app->model('operation_organization');
    $orgs = $operationOrgObj->dump(array('org_id' => $org_id), '*');
    
    $this->pagedata['orgInfo'] = $orgs;
    $this->pagedata['title'] = '编辑运营组织';
    $this->display('admin/operationorg/detail.html');
}

错误示例 ​

php
// ❌ 错误：Dialog 不应该使用 singlepage()
function add() {
    $this->pagedata['title'] = '添加运营组织';
    $this->singlepage('admin/operationorg/detail.html'); // 错误！
}

function edit($org_id) {
    // ...
    $this->singlepage('admin/operationorg/detail.html'); // 错误！
}

表单配置 ​

1. Controller 配置 ​

在 finder 的 actions 中配置 dialog：

php
$this->finder('ome_mdl_operation_organization', array(
    'title' => '运营组织',
    'actions' => array(
        array(
            'label' => '添加',
            'href' => 'index.php?app=ome&ctl=admin_operationorg&act=add',
            'target' => 'dialog::{width:600,height:400,title:\'添加运营组织\'}'
        ),
    ),
));

Dialog 配置参数：

  • width: 对话框宽度（像素）
  • height: 对话框高度（像素）
  • title: 对话框标题

2. 表单配置 ​

在表单中添加 isCloseDialog 属性，提交成功后会自动关闭对话框：

html
<form method="post" 
      action="index.php?app=ome&ctl=admin_operationorg&act=save&finder_id=<{$env.get.finder_id}>" 
      id="orgForm" 
      isCloseDialog>
    <!-- 表单内容 -->
</form>

3. 按钮位置规范 ​

重要：Dialog 中的提交按钮应该放在 .mainFoot 区域，而不是表单内的 table-action。

正确做法：

html
<form id="orgForm" action="..." method="post" isCloseDialog>
    <div class="tableform">
        <!-- 表单字段 -->
    </div>
</form>

<{area inject=".mainFoot"}>
<div class="table-action">
    <{button class="btn-primary" type="button" id="saveBtn" label="保存"}>
</div>
<{/area}>

<script>
$('saveBtn').addEvent('click', function(event) {
    $('orgForm').fireEvent('submit', new Event(event));
});
</script>

错误做法：

html
<!-- ❌ 错误：按钮放在表单内的 table-action -->
<form id="orgForm" action="..." method="post">
    <div class="tableform">
        <!-- 表单字段 -->
        <div class="table-action">
            <{button type="submit" id="saveBtn" label="保存"}>
        </div>
    </div>
</form>

4. JavaScript 配置 ​

表单提交成功后，dialog 会自动关闭并刷新 finder，无需手动处理：

javascript
$('orgForm').store('target', {
    onRequest: function() {
        $('saveBtn').set('disabled', 'true');
    },
    onComplete: function(jsontext) {
        var json = Json.evaluate(jsontext);
        if (typeof(json.error) != 'undefined') {
            $('saveBtn').set('disabled', '');
        } else {
            // dialog 会自动关闭并刷新 finder，无需手动处理
        }
    }
});

no_redirect 参数处理 ​

重要：当 Dialog 页面可能从多个来源打开时，需要在保存时判断是否需要跳转。

使用场景：

  • Dialog 从其他页面（如表单中的快捷添加按钮）打开时，保存成功后只需要关闭 dialog，不需要跳转
  • Dialog 从列表页面的"添加"按钮打开时，保存成功后需要跳转到列表页

实现方式：

1. 在打开 Dialog 时传递 no_redirect 参数：

javascript
new Dialog('index.php?app=ome&ctl=admin_operationorg&act=add&finder_id=<{$env.get.finder_id}>&no_redirect=1', {
    width: 600,
    height: 400,
    title: '添加运营组织'
});

2. 在表单 action 中包含 no_redirect 参数：

html
<form id="orgForm" 
      action="index.php?app=ome&ctl=admin_operationorg&act=save&finder_id=<{$env.get.finder_id}><{if $env.get.no_redirect}>&no_redirect=<{$env.get.no_redirect}><{/if}>" 
      method="post" 
      isCloseDialog>

3. 在 Controller 的 save 方法中处理：

php
function save() {
    // 如果是通过 dialog 打开的（no_redirect=1），不需要设置跳转 URL（dialog 会自动关闭）
    $url = '';
    if (empty($_GET['no_redirect']) && empty($_POST['no_redirect'])) {
        $url = 'index.php?app=ome&ctl=admin_operationorg&act=index';
    }
    $this->begin($url);
    // ... 保存处理 ...
    $this->end($rt, app::get('base')->_($rt ? '保存成功' : '保存失败'));
}

注意事项 ​

1. finder_id 参数 ​

确保在表单 action 中传递 finder_id 参数，以便 dialog 能正确刷新 finder：

html
<form action="index.php?app=ome&ctl=admin_operationorg&act=save&finder_id=<{$env.get.finder_id}>" ...>

2. 对话框尺寸 ​

根据表单内容合理设置对话框尺寸：

  • 简单表单：width:600,height:400
  • 中等表单：width:900,height:600
  • 复杂表单：width:1000,height:700

3. 表单验证 ​

表单提交前进行客户端验证，避免无效提交

4. 错误处理 ​

保存失败时，确保错误信息能正确显示

参考文档 ​

  • Finder开发：oms-finder-development.md
  • 数据库开发：oms-database-development.md

Examples ​

  • 当用户需要开发Dialog页面时，说明使用 display() 方法而不是 singlepage()
  • 当用户需要配置Dialog按钮时，说明按钮应该放在 .mainFoot 区域
  • 当用户需要处理多来源打开时，说明 no_redirect 参数的使用
  • 当用户需要添加快捷添加功能时，说明如何在表单字段旁边添加Dialog按钮

Guidelines ​

  • 严格遵循 display() vs singlepage() 的使用规范
  • Dialog 按钮必须放在 .mainFoot 区域
  • 表单必须包含 isCloseDialog 属性
  • 表单 action 必须传递 finder_id 参数
  • 多来源打开时，正确处理 no_redirect 参数
  • 不要使用 opener.finderGroup 和 window.close()（这些是用于新窗口的）