编辑“Xoops表单结构模块开发”

__NOTOC__
<span style="text-align:center; border:1px solid #000; float:right; padding:6px;"><strong>导航:</strong> [[Xoops模块开发|上一页]] | {{Template:Xoops导航}}</span>
<div style="clear:both;"></div>

该部分将建立一个简单的[[XOOPS]]模块，包含一个表单及提交表单时的动作。

===准备===
你应该：
* 已经安装一个 Xoops 系统 ，而且能够正常运行
* 已经熟悉 Xoops 模块安装的方法
* 知道如何编写 [[PHP]] 语言 
* 了解 [[SQL]] (如果你的模块需要存取[[数据库]])
* 了解[[Smarty]]模板的基本知识
* 已阅读并理解《xoops-module-skeleton.doc》、《XOOPS_Coding_Standards_.html》 

===格式说明===
我们的模块的目标是显示一个简单的表单，然后返回提交的数据。
* 模块名: Form Test
* 模块目录: formtest 


===模块功能说明===
* 在主菜单上显示它本身
* 支持多种语言
* 显示一张表单，然后在提交时显示输入值。 

===目录结构===
假设你已经用骨架代码把目录结构建好。所创建好的结构看起来就像如下的样子：
<pre>
XOOPS_ROOT/modules/formtest

    language

        english 

    templates 
</pre>
注意：在以下的描述中，当我给出一个目录名或文件名时，除非有明确地表述，否则它们都对应于XOOPS_ROOT/modules/ formtest。 


===模块基本配置信息===
创建一个文件 /xoops_version.php 其程序代码内容如下：
<pre>
<?php
//版权信息，说明，等等……放在这里
$modversion['name'] = _MI_FORMTEST_NAME;
$modversion['version'] = 1.00;
$modversion['description'] = _MI_FORMTEST_DESC;
$modversion['credits'] = '';
$modversion['author'] = '<insert name>';
$modversion['license'] = 'GPL see LICENSE';
$modversion['official'] = 0;
$modversion['image'] = 'images/logo.png';
$modversion['dirname'] = 'formtest';

//管理
$modversion['hasAdmin'] = 0;
$modversion['adminmenu'] = '';

//菜单
$modversion['hasMain'] = 1;

//模板
$modversion['templates'][1]['file'] = "formtest_form.html";
$modversion['templates'][1]['description'] = "Test Form";
$modversion['templates'][2]['file'] = "formtest_read.html";
$modversion['templates'][2]['description'] = "Read back form data";
?>
</pre>

'''_MI_ ... ?'''

任何以 _MI_ 为前缀的词，都是在 /language/schinese/modinfo.php语言文件里面定义的。我们马上会创建这个文件，但是现在，我们只要知道，这是模块信息，它将被及时显示在用户眼前；在这种情况下，它只在管理员安装或管理时显示。因此需要在语言文件里事先定义。

'''模板'''

模板（Templates）会在模块安装时被编译，而且保存在数据库中。 因此，你必须让系统知道你将会使用到的每个模板。

'''模块信息语言文件'''

编辑 /language/schinese/modinfo.php 而且将下列内容放入其中。
<pre>
<?php
//模块名称
define("_MI_FORMTEST_NAME", "FORM TEST");
//模块的简短描述
define("_MI_FORMTEST_DESC", "A simple module to demonstrate creating forms in XOOPS.");
?>
</pre>
说明：稍后我们将会把较多的信息加入这个文件里，但是它仍然是一样的语法；非常容易的。现在如果我们想要增加一个法语的语言文件，我们要做的只是创建 /language/french/modinfo.php，然后放上相同的定义，不过这些定义要改为法语。现在如果某人在法语的语系中使用此系统，Formtest会以他们的语言来显示它的名字和描述。 

'''一个简单的小帮手'''

以如下的内容，创建 /header.php ：
<pre>
<?php
require '../../mainfile.php';
?>
</pre>

说明：初始化XOOPS和SMARTY引擎。

'''最主要的文件：index.php'''

这将控制页面布局。
<pre>
<?php
//表单未填写，一定是第一个访问这样显示的表单
if (empty($_POST['submit'])) {
// 初始化XOOPS和SMARTY
include "header.php";
//开始页面
include XOOPS_ROOT_PATH."/header.php";
// 设置模板文件
$xoopsOption['template_main'] = "formtest_form.html";
// 获取表单创建类
include_once XOOPS_ROOT_PATH."/class/xoopsformloader.php";
// 包含你的表单的逻辑文件
include "formtest.php";
// 传送表单到SMARTY
$test_form->assign($xoopsTpl);
// 结束页面
include XOOPS_ROOT_PATH."/footer.php";

} else { // 表单被提交，让我们来演示返回
require "header.php";
require XOOPS_ROOT_PATH."/header.php";
$xoopsOption['template_main'] = "formtest_read.html";
// 从表单发送变量到SMARTY来输出
$xoopsTpl->assign('itemName', $_POST['itemName']);
$xoopsTpl->assign('itemDesc', $_POST['itemDesc']);
require XOOPS_ROOT_PATH."/footer.php";
}
?>
</pre>
要点：这可以在[[论坛]]中找到！为了适当的实现[[XOOPS]]系统范围的缓存，在主模板被赋值前必须进入XOOPS_ROOT_PATH."/header.php"。

这个文件有两部分。在检查提交按钮是否点击后，两张页面之一被创建。如果它还没被点击，那么这页面是第一次被访问，而且表单文件被显示的SMARTY模板赋值。如果它已经被点击过了，那么变量$_POST被插入显示的SMARTY模板。 

'''$xoopsTpl'''

这是另一个变量，当程序引用了 /header.php 时就自动产生了。它也是Smarty类。 在Smarty文档中定义 $xoopsTpl 变量为 $smarty。 它只是你在 $xoopsOption['template_main'] = 'formtest_form.html '或$xoopsOption['template_main'] = 'formtest_read.html' 模板中所创建的 Smarty类。

'''XOOPS_PATH . '/header.php' 和 XOOPS_PATH . '/footer.php''''

主页面header与footer。在这里你要知道的重要一点是：
#你必须将它们包含进来
#在还没把XOOPS_PATH.'/header.php'包含之前，你不能使用$xoopsTpl
#所有$xoopsTpl操作必须在两个require（或include）语句之间完成 

'''formtest.php'''

这是程序逻辑文件。我们可以在里面定义表单部分。

说明：有三个步骤：
#使用XOOPS表单类来创建表单的元素。
#建立一个表单对象。
#将你的元素加入到这个表单。 

'''/language/schinese/main.php'''
<pre>
<?php
define("_FT_NAME", "Item Name");
define("_FT_DESC", "Item Description");
define("_FT_SUBMIT", "Submit");
define("_FT_TESTFORM", "Test Form");
?>
</pre>
说明：在这个文件中我们定义所有在主要文件中的标题、提示、头部、或其他系统文本输出的变量。像modinfo.php，这个文件使得为站点提供不同的语言变的容易。

'''/templates/formtest_form.html'''

这个文件是个真实的Smarty 模板文件。

重要说明：在 XOOPS中，所有的Smart [[程序]]代码的Smarty标签都是 <{...}> 而不是像Smartys速成课程中所说的 {...} 标签。 {...} 是无法在XOOPS里工作的。请牢记！

首先，一个普通的动态创建的检测表单的javascript是嵌入的。然后表单打开开始显示表格。表单元素插入到一个XOOPS或 SMARTY前部的循环中。这种方式在不需要接触到[[HTML]]模板文件的情况下方便的添加或移动表单元素。表格的外观套用站点的主要[[CSS]]文件，所以，模块看上去像静态的站点。

'''/templates/formtest_read.html'''

* 条目名称: <{$itemName}>
* 条目描述: <{$itemDesc}> 

说明：<{$itemName}>通过/index.php, $xoopsTpl->assign('itemName', ...);.中的命令来获取赋值，<{$itemDesc}>也同样如此。如果你想改变页面外观，更改HTML代码而不用改变 XOOPS/SMARTY标签。例如：
<pre>
<table class="outer" cellspacing="1">
    <tr>
    <th colspan="2">Form Output</th>
    </tr>
    <tr>
        <td class="head">Name</td>
        <td><{$itemName}></td>
    </tr>
    <tr>
        <td class="head">Description</td>
        <td><{$itemDesc}></td>
    </tr>        
</table>
</pre>
注意：如果你只看到一张空白页，你应该试着更新模块。只要你更改了代码你就必须更新模块。进入System Admin --> Modules，点击formtest module旁边的'update module'按钮。如果还是显示空白页，就返回检查，这是一项艰苦的工作。尤其要检查文件xoops_version.php。 


===从数据库读取数据并显示===
这是一个从数据库顺着向下读取表单选项方面的快速课程

我们有一个含有叫"categories"表格的数据库，我们想要顺序向下的向数据库中填写分类。下面是应该怎么做：
<pre>
<?php
// 必须包含Xoops and Smarty初始信息，包含数据库接口……
include "../../mainfile.php";

//……及表格的产生。
include_once XOOPS_ROOT_PATH."/class/xoopsformloader.php";

// 查询数据库和读取一组有结果的数组
$results = $xoopsDB->query("SELECT `category` from ". $xoopsDB->prefix("categories"));
while ($opt = $xoopsDB->fetchArray($results)) {
    // 创建选项数组
    $options[] = $opt['category'];
}

//用XoopsFormSelect类创建表单元素
$category_select = new XoopsFormSelect(_MY_SELCAT, "categories");

// 添加从数据库提取的选项数组
$category_select->addOptionArray($options);

// 创建一个提交按钮
$submit_button = new XoopsFormButton("", "submit", _MY_SUBMIT, "submit");

// 创建新的表单对象
$my_form = new XoopsSimpleForm(_MY_MYFORM, "myform", "myform.php"); // default method is POST

// 添加元素到表单
$my_form->addElement($category_select);
$my_form->addElement($submit_button);
?>
</pre>
注意：_MY_SELCAT和所有其他常数元素标题在文件language/english/main.php中被定义（或无论你使用什么语言）

在你的模板文件顺序向下显示：
<pre>
<form name="<{$myform.name}>" enctype="multipart/form-data" action="<{$myform.action}>" method="<{$myform.method}>" <{$myform.extra}>>

<table>
    <tr>
        <th><{$myform.elements.categories.caption}></th>
        <td><{$myform.elements.categories.body}></td>
    </tr>
    <tr>
        <td colspan="2"><{$myform.elements.submit.body}></td>
    </tr>
</table>

</form>
</pre>











[[category:Xoops模块开发指南]]