README

此扩展包为Contao CMS的前端提供状态消息队列。

特性

在前端显示各种类型的状态消息（错误、成功、警告等）
同步和Ajax方式均支持
内部使用symfony的session flash bags（请参阅symfony文档获取更多详细信息）
包含预定义样式的模板，适用于bootstrap 4/5

印象

前端的状态消息队列

安装

使用composer安装：composer require heimrichhannot/contao-status-message-bundle。
通过迁移命令或安装工具更新您的数据库。

概念

消息作用域

要添加新的状态消息，您需要了解以下内容

您想要输出的消息的文本是什么？
消息的类型是什么（成功、错误等）？
消息的作用域是什么（一般作用域、特定模块或内容元素等）？

特别是，第三个参数可能不是很明显。在这个扩展包的上下文中，您不仅可以创建一个“状态消息队列”，还可以创建任意多个。为了在前端区分它们，您需要告诉StatusMessageManager您要添加的消息的作用域。

目前，作用域可以是

通用 -> 无特定上下文
模块 -> 特定前端模块（必须传递id）
内容元素 -> 特定前端内容元素（必须传递id）

内部此扩展包使用symfony的session flash bag API。如果您不熟悉这些，请参阅文档。

因此，上述的作用域由flash bag key描述。为了方便起见，在这个扩展包的上下文中，我们称之为作用域键。

例如，如果您想将消息绑定到特定模块，作用域键可能类似于huh_status_message.module.1234，其中module是作用域，而1234是模块id。

使用方法

添加状态消息

use HeimrichHannot\StatusMessageBundle\Manager\StatusMessageManager;

// ...
protected StatusMessageManager $statusMessageManager;
// ...

// use this scope key to output the messages after you've added them (see below)
$scopeKey = $this->statusMessageManager->getScopeKey(
    StatusMessageManager::SCOPE_TYPE_MODULE,
    $module->id
);

$this->statusMessageManager->addSuccessMessage(
    'Everything worked well :-)',
    $scopeKey
);

通过前端模块“状态消息队列”输出消息

为了输出您的状态消息，您可以创建一个“状态消息队列”前端模块，并将其包含在您的文章或布局中，例如。

重要：请确保此模块的包含顺序。如果您在队列模块渲染之前添加消息，则消息只能在网站重新加载后显示（消息存储在会话中）。

在twig模板中以编程方式输出消息

只需将作用域键（即内部的flash bag key）传递到您的twig模板，并使用symfony的flash message API输出消息（作用域键可能类似于huh_status_message.module.1234，其中module是作用域，而1234是模块id）

{% if app.session.flashBag.peek(scopeKey) is not empty %}
    {% for message in app.flashes(scopeKey) %}
        <div class="{{ message.type }}">
            {{ message.text }}
        </div>
    {% endfor %}
{% else %}
    {# do something else #}
{% endif %}

在传统html5模板中以编程方式输出消息

首先，在您的模块（或内容元素）控制器中实现必要的逻辑

use HeimrichHannot\StatusMessageBundle\Manager\StatusMessageManager;

// ...
protected StatusMessageManager $statusMessageManager;
// ...

protected function getResponse(Template $template, ModuleModel $module, Request $request): ?Response {
    $scopeKey = $this->statusMessageManager->getScopeKey(
        $module->statusMessageScopeType,
        $module->statusMessageScopeContext
    );
    
    $template->hasMessages = $this->statusMessageManager->hasMessages($scopeKey);
    
    if ($template->hasMessages) {
        $template->messages = $this->statusMessageManager->getMessages($scopeKey);
    }
    
    return $template->getResponse();
}

然后在您的模板中，使用以下数据

<?php if ($this->hasMessages): ?>
    <?php foreach ($this->messages as $message): ?>
        <div class="<?= $message['type'] ?>">
            <?= $message['text'] ?>
        </div>
    <?php endforeach; ?>
<?php else: ?>
    <!-- do something else -->
<?php endif; ?>

开发者注意事项

为什么不使用Contao.Message类呢？

当然，如果核心类符合我们的需求，我们会使用它们。一个缺点是，消息的作用域始终由作用域字符串和消息类型共同决定（见static::getFlashBagKey($strType, $strScope)）。

public static function add($strMessage, $strType, $strScope=TL_MODE) {
    // ...

    System::getContainer()->get('session')->getFlashBag()->add(static::getFlashBagKey($strType, $strScope), $strMessage);
}

因此，我们无法拥有包含不同类型消息的消息队列。

heimrichhannot / contao-status-message-bundle

维护者

详细信息