README

安装

通过Composer

$ composer require nepada/form-renderer

在config.neon中注册扩展

extensions:
    formRenderer: Nepada\Bridges\FormRendererDI\FormRendererExtension

用法

Nette提供了两种渲染表单的方式

1. 手动在Latte模板中使用表单宏渲染整个表单。这种方式可以完全控制渲染，但编写所有模板很快就会变得重复。
2. 使用表单渲染器渲染，例如来自nette/forms的DefaultFormRenderer。 DefaultFormRenderer非常可定制，但为表单的某些控件设置特殊的渲染规则或添加对新表单控件类型的支持比较困难。

nepada/form-renderer建立在Latte模板和它们强大的块的基础上，因此结合了手动渲染和表单渲染器的DRY原则的优势。

模板渲染器

您可以使用TemplateRendererFactory服务来创建具有预配置的默认模板的渲染器。它以类似于DefaultFormRenderer的方式渲染表单。

自定义渲染

您可以通过从模板文件导入块来自定义渲染，稍后导入的具有相同名称的块将覆盖先前导入的块。您还可以向模板传递自定义变量。

/** @var Nepada\FormRenderer\TemplateRendererFactory $factory */
$renderer = $factory->create();
$renderer->importTemplate(__DIR__ . '/custom-form-rendering-blocks.latte');
$renderer->getTemlate()->foo = 'bar'; 
$form->setRenderer($renderer);

提示

• 您可以在#control-name-*块中定义表单特定控件的特殊渲染（例如，#control-name-container-subcontainer-foocontrol）。
• 如果您需要为控件和其标签定义特殊的渲染，请在#pair-name-*块中定义它。
• 不同控件类型的渲染（基于$control->getOption('type')的值）由#control-type-*和#pair-type-*块控制。默认模板实际上使用了这一点来渲染按钮（在一行中连续渲染按钮）。
• 您还可以在您的config.neon中指定要导入的模板文件

  formRenderer:
      default:
          imports:
              - %appDir%/templates/@form-extras1.latte
              - %appDir%/templates/@form-extras2.latte

有关支持块和更好地理解渲染器的工作原理的完整概述，请阅读模板的代码。

从头开始创建自定义TemplateRenderer配置

您不需要使用默认模板，您可以创建一个从零开始，具有符合您需求的块。您可以定义如下自定义设置的工厂

services:
    customRenderer:
        implement: Nepada\FormRenderer\TemplateRendererFactory
        setup:
          - importTemplate('%appDir%/templates/@form.latte')
          - importTemplate('%appDir%/templates/@form-extras.latte')

只需确保您的模板文件之一定义了一个名为#form的块即可 - 这用于渲染的起点。

模板中的safeTranslate过滤器

对于翻译，模板可以使用自定义的safeTranslate过滤器。与标准translate过滤器的关键区别在于

1. 它避免翻译Nette\Utils\IHtmlString和Latte\Runtime\IHtmlString的实例。
2. 它使用正在渲染的表单实例的翻译器。
3. 如果表单未设置翻译器，则它将简单地返回未翻译的传递的字符串。

n:class宏的改进版本

在所有表单模板中，也提供了一个改进的 n:class 宏版本，它支持合并来自 Nette\Utils\Html 实例的类。您可以进行如下操作：<input n:name="$control" n:class="$control->controlPrototype->class, form-control">，无需担心类属性是否真正以字符串或数组的形式表示，一切都会正常工作。

Bootstrap5Renderer

与 Bootstrap 5 兼容的表单渲染器，它内部使用 TemplateRenderer 和 自定义模板。

模板支持三种渲染模式

/** @var Nepada\FormRenderer\Bootstrap5RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

使用 $renderer->setRenderValidState(true) 启用/禁用表单提交后填充输入的“有效”表单控件状态的渲染。

在行内模式下，错误消息始终以工具提示的形式渲染。在其他模式下，您可以通过调用 $renderer->setUseErrorTooltips(true) 在标准渲染和工具提示渲染之间切换。

您可以通过 $renderer->setUseFloatingLabels(true) 启用 浮动标签（在水平模式下忽略）。默认情况下，所有 text、datetime、textarea 和 select 类型的控件都使用浮动标签渲染，但您可以通过设置 $input->setOption('floatingLabel', false) 在特定控件上手动覆盖此设置。

要将复选框渲染为开关，您需要设置类型选项：$checkboxInput->setOption('type', 'switch')。

要将单选按钮或复选框渲染为 切换按钮，向标签原型添加 btn 类（以及任何所需的按钮样式类）：$radio->getItemLabelPrototype()->addClass('btn btn-outline-primary')。

Bootstrap5Renderer 在将表单传递给 TemplateRenderer 之前对其进行了一些调整

1. 它为表单中的第一个 SubmitButton 控件的控件原型添加了 btn btn-primary 类，除非表单中已经存在此类控件。
2. 它为每个 Button 控件的控件原型添加了 btn btn-secondary 类，除非它已经设置了 btn 类。
3. 更改所有 Checkbox、CheckboxList、RadioList 控件的 type 选项，使其从 checkbox/radio 渲染为 togglebutton/togglebuttonlist。
4. 更改所有 CheckboxList 控件的 type 选项，从 checkbox 更改为 checkboxlist。
5. 当启用浮动标签时，它将在所有控件上设置布尔值 floatingLabel 选项（除非已经设置），以指示是否应渲染浮动标签。

您可以从您的 config.neon 中更改默认渲染器配置

formRenderer:
  bootstrap5:
    mode: horizontal
    renderValidState: true
    useErrorTooltips: true
    imports:
      - %appDir%/templates/@form-extras.latte

Bootstrap4Renderer

与 Bootstrap 4 兼容的表单渲染器，它内部使用 TemplateRenderer 和 自定义模板。

模板支持三种渲染模式

/** @var Nepada\FormRenderer\Bootstrap4RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

使用 $renderer->setRenderValidState(true) 启用/禁用表单提交后填充输入的“有效”表单控件状态的渲染。

在行内模式下，错误消息始终以工具提示的形式渲染。在其他模式下，您可以通过调用 $renderer->setUseErrorTooltips(true) 在标准渲染和工具提示渲染之间切换。

您可以通过 $renderer->setUseCustomControls(true) 启用使用 自定义表单控件。

要将复选框渲染为开关，您需要设置类型选项：$checkboxInput->setOption('type', 'switch')。

Bootstrap4Renderer 在将表单传递给 TemplateRenderer 之前对其进行了一些调整

1. 它为表单中的第一个 SubmitButton 控件的控件原型添加了 btn btn-primary 类，除非表单中已经存在此类控件。
2. 它为每个 Button 控件的控件原型添加了 btn btn-secondary 类，除非它已经设置了 btn 类。
3. 更改所有 CheckboxList 控件的 type 选项，从 checkbox 更改为 checkboxlist。

您可以从您的 config.neon 中更改默认渲染器配置

formRenderer:
    bootstrap4:
        mode: horizontal
        renderValidState: true
        useErrorTooltips: true
        useCustomControls: true
        imports:
            - %appDir%/templates/@form-extras.latte

Bootstrap3Renderer

与 Bootstrap 3 兼容的表单渲染器，它内部使用 TemplateRenderer 和 自定义模板。

模板支持三种渲染模式

/** @var Nepada\FormRenderer\Bootstrap3RendererFactory $factory */
$renderer = $factory->create();
$renderer->setBasicMode(); // Basic form
$renderer->setInlineMode(); // Inline form
$renderer->setHorizontalMode(4, 8); // Horizontal form (you can optionally set the size of label and control columns)

使用 $renderer->setRenderValidState(true) 启用/禁用表单提交后填充输入的“有效”表单控件状态的渲染。

Bootstrap3Renderer 在将表单传递给 TemplateRenderer 之前对其进行了一些调整

1. 它为表单中的第一个 SubmitButton 控件的控件原型添加了 btn btn-primary 类，除非表单中已经存在此类控件。
2. 它为每个 Button 控件的控件原型添加了 btn btn-default 类，除非它已经设置了 btn 类。
3. 更改所有 CheckboxList 控件的 type 选项，从 checkbox 更改为 checkboxlist。

您可以从您的 config.neon 中更改默认渲染器配置

formRenderer:
    bootstrap3:
        mode: horizontal
        renderValidState: true
        imports:
            - %appDir%/templates/@form-extras.latte