README

这是一个为 Symfony2 框架设计的包，它提供了创建表单、表格列表和树形（顺序）表单的功能。在创建网站的后端时非常有用。

此包正在开发中，请在项目中使用时小心。

表单功能

字段被组合成组
根据字段条件控制组的可见性
JavaScript 验证
高级模板，可用字段模板替换
Ajax 文件上传

表格列表功能

使用 Doctrine
支持选项卡
按所有字段排序
文本搜索功能
Ajax 操作
将排序设置、搜索设置、当前页等保存在会话中

树形（顺序）表单功能

使用 Doctrine
通过 JavaScript 轻松设置树形或顺序
支持鼠标和触摸屏

1. 安装

要安装 SergsxmUIBundle，请运行 composer require sergsxm/ui-bundle。

在 app/AppKernel.php 文件中注册此包

...
public function registerBundles()
{
    $bundles = array(
        ...
        new Sergsxm\UIBundle\SergsxmUIBundle(),
        ...
    );
...

在 app/config/routing.yml 文件中注册此包

...
sergsxm_ui:
    resource: "@SergsxmUIBundle/Resources/config/routing.yml"
    prefix:   /
...

通过命令 php app/console assets:install 安装包资源

现在您可以使用此包了。

如果您将更改布局模板，请记得添加此包的 CSS 和 JS 文件以及初始化部分（当然，还有 Bootstrap、jQuery、TinyMCE 文件）

<html>
    <head>
        ...
        ...
        <link rel="stylesheet" href="{{asset('bundles/sergsxmui/css/ui.css')}}" />
        <script src="{{asset('bundles/sergsxmui/js/ui.js')}}"></script>
        <script>
            sergsxmUIFunctions.initContext('{{app.request.locale}}', '{{path('sergsxm_ui_file_upload')}}');
        </script>    
    </head>
    ...
    ...
</html>

1.1. 第三方模块

为了包的正常运行，需要以下模块

Bootstrap

jQuery

TinyMCE（可选，用于表单中的 HTML 输入类型）

Yandex.maps（可选，用于表单中的地址输入类型）

2. 表单使用

2.1. 创建表单

要创建表单，请使用服务

$form = $this->get('sergsxm.ui')->createForm($object);

$object 是用于属性映射的对象。如果不需要此功能，则保留此参数或将其设置为 null。

现在您拥有 Form（Sergsxm\UIBundle\Form\Form）对象。此对象包含以下方法

public function addField($type, $name, $configuration = array(), $mappingObject = self::MO_PARENT);
public function openGroup($name, $description = '', $condition = '');
public function closeGroup();
public function enableCaptcha($type, $configuration = array());
public function disableCaptcha();
public function getFormId();
public function setFormId($formId);
public function setReadOnly($readOnly);
public function bindRequest(Request $request = null);
public function clear();
public function getResult();
public function getView();
public function renderView($template = 'SergsxmUIBundle:Form:Form.html.twig', $parameters = array());
public function render($template = 'SergsxmUIBundle:Form:Form.html.twig', $parameters = array(), Response $response = null);
public function findInputByName($name);
public function getValue();
public function setValue($value);
public function fromAnnotations($tag = null, $mappingObject = self::MO_PARENT);

具体功能请参阅类文件中的详细描述。

以下是使用表单的代码示例

$object = new \StdClass();
$object->text1 = 'foo';
$object->textarea1 = '';
$object->select1 = '';
$object->checkbox1 = '';
$object->password1 = '';
$object->timestamp1 = '';
$object->html1 = '';
$object->file1 = null;

$form = $this->get('sergsxm.ui')->createForm($object);
        
$form
    ->addField('text', 'text1')
    ->openGroup('test', 'Test group', '')
    ->addField('textarea', 'textarea1')
    ->addField('select', 'select1', array(
        'choices' => ['One', 'Two', 'Three'],
    ))
    ->openGroup('test1', 'Subgroup', 'select1 == 1')
    ->addField('checkbox', 'checkbox1')
    ->addField('password', 'password1')
    ->closeGroup()
    ->addField('timestamp', 'timestamp1')
    ->openGroup('test2', 'Subgroup 2')
    ->addField('html', 'html1')
    ->enableCaptcha('standart')
    ->addField('file', 'file1', array(
        'storeType' => \Sergsxm\UIBundle\FormInputTypes\File::ST_FILE,
        'storeFolder' => 'uploadfiles',
    ));
if ($form->bindRequest()) {
    echo 'Data saved!';
    var_dump($form->getValue());
    var_dump($object);
    $form->clear();
    die;
}
        
return $form->render('SergsxmUIBundle:Form:Form.html.twig', array('title' => 'New form', 'backUrl' => '/123'));

2.2. 对象属性映射

如果您为创建表单指定了用于属性映射的特定对象，则表单值将自动转移到具有相同名称的对象属性中。请确保在上述示例中可以实现这一点。此外，对于每个字段，您还可以指定另一个对象（请参阅添加字段方法的 4 个参数）。

如果不需要此功能，您可以在字段配置中指定 'mapping' => false。

2.3. 输入类型

支持输入类型：复选框、文本、文本区域、时间戳、HTML、密码、选择、文件、数字、图像、地址、标签、类别。

类型 checkbox 具有以下设置

类型 text 具有以下设置

类型 email 与 text 类型相同，具有预定义的正则表达式。

类型 textarea 具有以下设置

类型 timestamp 具有以下设置

类型 html 具有以下设置

类型 password 具有以下设置

类型 select 具有以下设置

类型 file 具有以下设置

类型 number 具有以下设置

类型 image 具有以下设置

类型 address 具有以下设置

类型 tag 具有以下设置

类型 category 具有以下设置

ValidateCallback 函数必须可调用。函数应返回 null（如果字段值有效）或错误文本。传递给函数的第一个参数是字段的值。第二个参数通过 validateCallbackParameters 参数指定。

StoreType 指定保存文件的类型。由类 \Sergsxm\UIBundle\FormInputTypes\File（用于图像类型的 \Sergsxm\UIBundle\FormInputTypes\Image）中的常量定义。有两种类型：ST_FILE 和 ST_DOCTRINE。当您输入 ST_FILE 时，文件将保存在 storeFolder 文件夹中。包含文件信息的扩展名信息将创建在同一个文件夹中。文件名将用作映射属性的值。当您输入 ST_DOCTRINE 时，文件也保存在 storeFolder 文件夹中。文件信息存储在实体 storeDoctrineClass 的数据库中。该实体将用作映射属性的值。注意：storeFolder 必须受到外部访问的保护，以确保安全。

您还可以通过 placeholder 配置参数为字段和验证码指定占位符。

2.4. 验证码类型

支持的验证码类型：标准。

类型标准具有以下设置

2.5. 高级模板

默认简单表单的模板位于 SergsxmUIBundle:Form:Form.html.twig。字段和组的参数传递到组默认模板 SergsxmUIBundle:Form:FormGroup.html.twig。在这个模板中，字段参数传递到字段默认模板，这些模板位于 SergsxmUIBundle:FormInputTypes:。您可以更改默认模板，但可以在组模板中描述单个字段的输出。

{% if root|default(false) == false %}
    <div id="{{groupId}}">
        {% if description != '' %}
            <h2>{{description}}</h2>
        {% endif %}
{% endif %}
        {% for field in fields %}
            {% if field['type'] == 'text' %}
                ...
                ...
            {% else %}
                {% include field['defaultTemplate'] with field only %}
            {% endif %}
        {% endfor %}
        {% for group in groups %}
            {% include group['defaultTemplate'] with group only %}
        {% endfor %}
{% if root|default(false) == false %}
    </div>
{% endif %}

因此，您可以创建自己的模板，并在调用表单对象的渲染方法时放置它们。

您还可以通过 template 配置参数为字段和验证码指定模板。

2.6. 注解

您可以从映射对象的注解创建表单。为此，使用方法 fromAnnotations($formName = null, $mappingObject = self::MO_PARENT)。

注解 Sergsxm\UIBundle\Annotations\FormField 用于创建输入字段。类型和配置参数直接传递到 addField 方法。

示例

    /**
     * @var string
     *
     * @\Sergsxm\UIBundle\Annotations\FormField(type="text", configuration={"description"="File name", "required"=true, "requiredError"="The field can not be empty"})
     */
    private $fileName;

为了本地化注解中的短语，有翻译选项：translate。选项 translate 是一个数组，包含需要本地化的配置数组的键。您还可以通过 'Sergsxm\UIBundle\Annotations\TranslationDomain' 类注解指定翻译域。

示例

/**
 * @\Sergsxm\UIBundle\Annotations\TranslationDomain("sergsxmui")
 */
class FileEntity
{
    /**
     * @var string
     *
     * @\Sergsxm\UIBundle\Annotations\Description("File name field")
     * @\Sergsxm\UIBundle\Annotations\FormField(
     *      type="text", 
     *      configuration={"description"="File name", "required"=true, "requiredError"="The field can not be empty"}, 
     *      translate={"description", "requiredError"})
     */
    private $fileName;

注解 Sergsxm\UIBundle\Annotations\Description 用于设置字段描述。此值将被翻译。

类注解 Sergsxm\UIBundle\Annotations\Form 用于设置对象的表单。有三个参数：name、groups 和 fields。参数 name 包含表单名称。当您调用 fromAnnotations($formName) 方法时，将加载具有此名称的表单。参数 groups 包含有关所有组的信息。参数 fields 包含表单结构。

示例

/**
 * @\Sergsxm\UIBundle\Annotations\Form(
 *      name="user",
 *      groups={
 *          {"name"="first", "description"="First group"},
 *          {"name"="second", "description"="Second group"}
 *      },
 *      fields={"fileName", "first"={"contentFile"}, "second"={"mimeType"}}
 * )
 * @\Sergsxm\UIBundle\Annotations\TranslationDomain("sergsxmui")
 */
class FileEntity
{
    /**
     * @var string
     *
     * @\Sergsxm\UIBundle\Annotations\Description("File name")
     * @\Sergsxm\UIBundle\Annotations\FormField(
     *      type="text",
     *      configuration={"required"=true, "requiredError"="Field required"}, 
     *      translate={"requiredError"})
     */
    private $fileName;

    /**
     * @var string
     *
     * @\Sergsxm\UIBundle\Annotations\FormField(type="text", configuration={"description"="MIME", "required"=true, "requiredError"="Field required"})
     */
    private $mimeType;

    /**
     * @var string
     *
     * @\Sergsxm\UIBundle\Annotations\FormField(type="text", configuration={"description"="Content file"})
     */
    private $contentFile;

3. 表格列表使用方法

3.1. 表格列表创建

要创建表格列表，使用服务

$list = $this->get('sergsxm.ui')->createTableList();

现在您有 TableList（Sergsxm\UIBundle\TableList\TableList）对象。此对象包含以下方法

public function addTab($repository, $name, $configuration = null);
public function getTab($name);
public function bindRequest(Request $request = null);
public function getView();
public function renderView($template = 'SergsxmUIBundle:TableList:TableList.html.twig', $ajaxTemplate = 'SergsxmUIBundle:TableList:TableListAjax.html.twig', $parameters = array());
public function render($template = 'SergsxmUIBundle:TableList:TableList.html.twig', $ajaxTemplate = 'SergsxmUIBundle:TableList:TableListAjax.html.twig', $parameters = array(), Response $response = null);

方法 addTab 和 getTab 返回 TableListTab（Sergsxm\UIBundle\TableList\TableListTab）对象。此对象包含以下外部方法

public function addWhereCondition($dql, $condition, $parameter);
public function openWhereGroup($whereType);
public function closeWhereGroup();
public function groupBy($dql);
public function addColumn($type, $name, $configuration = array());
public function addUrlAction($name, $url, $configuration = array());
public function addAjaxAction($name, $sql, $configuration = array());
public function getDescription();

简要来说，当您创建标签时，您指定了 Doctrine 存储库。当您添加任何列时，指定名称与存储库中的字段名称相同。这样就可以构建一个简单的表格。对于高级任务，请参阅 高级查询 部分。

具体功能请参阅类文件中的详细描述。

以下是一个使用表格列表的代码示例

$list = $this->get('sergsxm.ui')->createTableList();

$list
    ->addTab('TestBundle:FileEntity', 'files', array('description' => 'Files', 'countEnabled' => true))
    ->addColumn('text', 'fileName', array('description' => 'File name', 'searchEnabled' => true))
    ->addColumn('text', 'mimeType', array('description' => 'MIME type'))
    ->addColumn('timestamp', 'uploadDate', array('description' => 'Upload date'))
    ->addAjaxAction('delete', 'DELETE FROM TestBundle:FileEntity f WHERE f.id IN (:ids)', array('confirmed' => true))
    ->addAjaxAction('set_jpeg', 'UPDATE TestBundle:FileEntity f SET f.mimeType = \'image/jpeg\' WHERE f.id IN (:ids)')
    ->addAjaxAction('set_png', 'UPDATE TestBundle:FileEntity f SET f.mimeType = \'image/png\' WHERE f.id IN (:ids)')
    ->addUrlAction('new', '/admin/edit');
$list
    ->addTab('TestBundle:FileEntity', 'files2', 'Files 2')
    ->addColumn('text', 'fileName', array('description' => 'File name', 'searchEnabled' => true))
    ->addColumn('text', 'mimeType', array('description' => 'MIME type'))
    ->addColumn('timestamp', 'uploadDate', array('description' => 'Upload date'))
    ->addAjaxAction('delete', 'DELETE FROM TestBundle:FileEntity f WHERE f.id IN (:ids)', array('confirmed' => true))
    ->addAjaxAction('set_jpeg', 'UPDATE TestBundle:FileEntity f SET f.mimeType = \'image/jpeg\' WHERE f.id IN (:ids)')
    ->addAjaxAction('set_png', 'UPDATE TestBundle:FileEntity f SET f.mimeType = \'image/png\' WHERE f.id IN (:ids)')
    ->addUrlAction('new', '/admin/edit')
    ;
        
$list->bindRequest();
        
return $list->render('SergsxmUIBundle:TableList:TableList.html.twig', 'SergsxmUIBundle:TableList:TableListAjax.html.twig');

TableListTab 的默认配置

3.2. 列类型

支持的列类型：文本、复选框、选择、时间戳、文件、数字、图像、标签、类别。

所有列类型都有以下设置

类型文本具有以下个人设置

类型 复选框 具有以下个人设置

类型选择具有以下个人设置

类型 时间戳 具有以下个人设置

类型文件具有以下个人设置

类型 number 拥有以下个人设置

类型 image 拥有以下个人设置

类型 tag 拥有以下个人设置

类型 category 拥有以下个人设置

参数 url 可以有两种格式。其中一种是自定义 URL 的字符串（通过 "/" 符号检测）。在这个字符串语句中，"{{id}}" 将会被行项 ID 替换。第二种格式是包含 Symfony 路由的字符串。这个字符串将经过 Symfony 路由服务（带有路由参数 "id"）的处理。

3.3. URL 操作

操作以按钮列表的形式显示。有两种类型的操作：URL 和 Ajax。URL 操作是您网站上的其他页面（例如，创建新页面）的简单链接。Ajax 操作是在表格列表中选择的项上的操作。它们通过 Ajax 请求处理。

URL 操作通过方法 addUrlAction($name, $url, $configuration = array()); 添加。参数 $name 包含操作的技术名称。参数 $url 是操作 URL 或路由名称。

URL 操作有以下附加配置设置

3.4. Ajax 操作

Ajax 操作通过方法 addAjaxAction($name, $sql, $configuration = array()); 添加。参数 $name 包含操作的技术名称。参数 $sql 包含 DQL 查询。它可以是一组用分号分隔的查询。查询可以包含参数 :id 或 :ids。

Ajax 操作有以下附加配置设置

当 DQL 查询不足以满足需求时（例如，验证每行的用户权限），请使用回调函数。这个函数会传入所选行标识符的数组。函数应返回一个错误数组（键 - 行标识符，值 - 错误文本）。

3.5. 高级查询

当您创建选项卡时，您指定了 Doctrine 仓库。当您添加任何列时，将其命名为仓库中的字段名称。因此，查询看起来像这样 SELECT item.id, item.{{columnName1}} as col0, item.{{columnName2}} as col1 .... FROM {{repository}} item。

它能够执行子查询。为此，将变量 $name 写为一个子查询

    ->addColumn('number', 'SELECT COUNT(m.id) FROM TestBundle:TestEntity m WHERE m.fooFile = item.id', array('description' => 'Use count'))

它也能够执行连接语句。为此，将变量 $name 写为一个选择部分，并添加 'join' 参数

    ->addColumn('image', 'file.contentFile JOIN item.fooFile file', array('description' => 'Image'))

使用 TableListTab 的 addWhereCondition、openWhereGroup、closeWhereGroup 方法以及 TableList 的 addTab 方法的 $configuration 参数中的 whereType，可以管理 DQL 的 WHERE 语句。

使用 TableListTab 的 groupBy 方法可以管理 DQL 的 GROUP BY 语句。

4. 树形和顺序表单的使用

4.1. 树形和顺序表单的创建

要创建树形表单，使用服务

$list = $this->get('sergsxm.ui')->createTreeForm($configuration, $treeItems);

要创建顺序表单，使用服务

$list = $this->get('sergsxm.ui')->createOrderForm($configuration, $orderListItems);

第一个参数是配置数组。第二个参数是列表项数组（您也可以通过指定的 loadDoctrineRepository 配置参数加载所有 Doctrine 仓库）。

现在您有了 TreeForm（Sergsxm\UIBundle\TreeForm\TreeForm）或 OrderForm（Sergsxm\UIBundle\OrderForm\OrderForm）对象。

TreeForm 对象包含以下方法

public function getView();
public function renderView($template = 'SergsxmUIBundle:TreeForm:TreeForm.html.twig', $parameters = array());
public function render($template = 'SergsxmUIBundle:TreeForm:TreeForm.html.twig', $parameters = array(), Response $response = null);
public function setReadOnly($readOnly);
public function getResult();
public function bindRequest(Request $request = null);
public function clear();
public function getFormId();
public function setFormId($formId);

OrderForm 对象包含以下方法

public function getView();
public function renderView($template = 'SergsxmUIBundle:OrderForm:OrderForm.html.twig', $parameters = array());
public function render($template = 'SergsxmUIBundle:OrderForm:OrderForm.html.twig', $parameters = array(), Response $response = null);
public function setReadOnly($readOnly);
public function getResult();
public function bindRequest(Request $request = null);
public function clear();
public function getFormId();
public function setFormId($formId);

以下是一个使用树形表单的简单示例

$treeForm = $this->get('sergsxm.ui')->createTreeForm(array(
    'createEnabled' => true,
    'createCallback' => array($this, 'createTree'),
    'removeEnabled' => true,
), $this->getDoctrine()->getRepository('\TestBundle\Entity\TreeEntity')->findAll());
        
if ($treeForm->bindRequest()) {
    $treeForm->clear();
    echo 'Data saved!';
}        
        
return $treeForm->render();

4.2. 树形和顺序项实体

为 TreeForm 定义的项实体必须实现 \Sergsxm\UIBundle\Classes\TreeInterface。

每个树形实体都有一个父字段和一个顺序字段。父字段的值可以是父实体或整数 ID（由配置设置）。顺序字段的值是一个整数。

还有一个嵌套集合接口 \Sergsxm\UIBundle\Classes\TreeNSInterface，它扩展了 TreeInterface。该接口有额外的设置级别、左键和右键的方法，用于嵌套集合算法。

为 OrderForm 定义的项实体必须实现 \Sergsxm\UIBundle\Classes\OrderInterface。

每个顺序列表实体都有一个顺序字段。

4.3. 配置参数

TreeForm 有以下配置参数

参数 createCallback 必须包含带有三个参数的回调函数：$title、$parent、$order。$title 是新树项的标题。$parent 是父实体或 null。$order 是树中树项的顺序（整数）。

参数 changeCallback 必须包含带有三个参数的回调函数：$item、$parent、$order。$item 是树项实体。$parent 是父实体或 null。$order 是树中树项的顺序（整数）。此函数在更改实体的父级和顺序字段后调用。

参数 removeCallback 必须包含带有单个参数的回调函数：$item。$item 是要删除的树项实体。此函数在调用实体管理器的 remove 方法后调用。

OrderForm 具有以下配置参数

参数 createCallback 必须包含带有两个参数的回调函数：$title、$order。$title 是新项的标题。$order 是顺序列表中项的顺序（整数）。

参数 changeCallback 必须包含带有两个参数的回调函数：$item、$order。$item 是顺序列表项实体。$order 是顺序列表中项的顺序（整数）。此函数在更改实体的父级和顺序字段后调用。

参数 removeCallback 必须包含带有单个参数的回调函数：$item。$item 是要删除的顺序列表项实体。此函数在调用实体管理器的 remove 方法后调用。

5. 注意事项

此包只是我个人对如何在表单和列表中组织结构的看法。代码测试较少，可能包含一些错误。

6. 许可证

此包采用 MIT 许可证。

sergsxm /ui-bundle

维护者

详细信息