README

此模块允许开发者为表单字段添加使用提示。提示只是任意的字符串值。

这些提示可以在项目的主题和模板中使用，以特定方式渲染字段，由您的网站使用的任何前端 UI 套件解释。

这避免了将特定于主题的 CSS 类污染模块 PHP 代码。

而不是这样做 $field->addExtraClass('btn btn-danger')，这样做 $field->setHint('danger')。

默认字段

默认情况下，以下字段已配置为支持 Hintable 扩展

FormAction - 用于操作优先级
CompositeField - 用于以特定方式渲染子字段
HTMLReadonlyField - 用于以特定方式显示值和标题

不对字段本身进行更改，该扩展仅暴露一些在模块代码中使用的方法。

使用方法

重要：在您的主题或项目中，您需要提供一个由使用 Hintable 扩展的类使用的模板。阅读：模板继承。

表单

在您的表单上设置字段提示

<?php
use SilverStripe\Forms\FormAction;

//...


/**
 * Add a hint that the action is a 'secondary' button/input
 */
FormAction::create(
    'doSecondary',
    _t('some.i18n_key', 'Complete secondary action')
)->setHint('secondary');

/**
 * Add a hint, and also add any class mapped to the secondary hint in config
 * (See Sample project configuration, below)
 */
FormAction::create(
    'doSecondary',
    _t('some.i18n_key', 'Complete secondary action')
)->setHint('secondary', true);

setHint 的值是一个字符串，它可以是一个模板可以解释的任何值。

第二个参数是是否根据提供的提示将类添加为字段的 extraClass。配置提供了提示和类之间的映射。

在您的 FormAction 模板中，您可能需要添加以下内容

<div class="form-action"<% if $FormFieldHint == 'secondary' %> custom-secondary<% end_if %>

模板

使用 $FormFieldHint 的值来修改您的主题/项目模板渲染字段的方式。

以下是一个使用 HTMLReadonlyField 的示例

<%-- path: themes/my-theme/templates/SilverStripe/Forms/HTMLReadonlyField_holder.ss --%>
<% if $FormFieldHint == 'callout' %>
    <%-- render as callout --%>
    <div class="my-callout">
        <% if $FormFieldHintIcon %>
            <span class="icon">{$FormFieldHintIcon}</span>
        <% end_if %>
        <div class="content">
            <% if $Title %>
            <h4>{$Title.XML}</h4>
            <% end_if %>
            {$Value}
        </div>
    </div>
<% else_if $FormFieldHint == 'alert' %>
    <%-- render an alert message --%>
<% else %>
    <%-- Important: allow for default rendering if no hint supplied --%>
    {$Field}
<% end_if %>

图标

在支持的字段上设置字段提示图标

FormAction::create(
    'doSecondary',
    _t('some.i18n_key', 'Complete secondary action')
)->setHint('secondary', true)->setFieldHintIcon('delete')

<%-- theme template: SilverStripe/Forms/FormAction.ss --%>
<% if $UseButtonTag %>
    <button $AttributesHTML>
        <% if $FormFieldHintIcon %>
        <span class="material-icons-outlined">{$FormFieldHintIcon}</span>
        <% end_if %>
        <% if $ButtonContent %>$ButtonContent<% else %><span>$Title.XML</span><% end_if %>
    </button>
<% else %>
	<input $AttributesHTML />
<% end_if %>

配置

如果没有，除非

您想将 Hintable 扩展添加到其他字段。
您需要添加提示到类映射

示例项目配置

---
Name: 'app-field-hint'
After:
  - '#nswdpc-field-hint'
---
# you require TextField to be hintable
SilverStripe\Forms\TextField:
  extensions:
    - 'NSWPDC\Forms\Hintable'
# add hint/class mapping
SilverStripe\Forms\FormField:
  hint_class_mapping:
    'secondary': 'nsw-button--secondary'

请注意，类被添加为额外类，默认情况下在 Silverstripe 中添加到字段容器和字段输入元素。您的模板应考虑这一点。

安装

安装此模块的唯一支持方式是通过 composer

composer require nswdpc/silverstripe-field-hint

根据 Packagist 状态，您可能需要在 composer.json 中添加一个存储库条目。

许可

BSD-3-Clause

配置

见 _config/config.yml

维护者

dpcdigital@NSWDPC:~$

错误跟踪器

我们欢迎在此项目的 Github Issue 跟踪器上提交错误报告、拉取请求和功能请求。

在打开新问题之前，请先查看行为准则。

安全性

如果您在此模块中发现安全漏洞，请首先通过电子邮件 digital[@]dpc.nsw.gov.au 与我们联系，详细说明您的发现。

开发和贡献

如果您想为此模块做出贡献，请确保提出拉取请求并与模块维护者进行讨论。

在完成拉取请求之前，请先查看行为准则。

nswdpc / silverstripe-field-hint

维护者

详情