跳到主要内容
版本：5.1

内容事件

内容插件事件不仅由 com_content 触发，还由其他组件（例如联系人、分类和标签）以及一些模块触发。

它们在以下过程中触发

  • 为在视图中显示准备内容（适用于文本 HTML 和 HTML 表单）
  • 处理从表单提交的 POST 数据（涉及 MVC 模型级别的数据验证和 CRUD 操作）

以下部分对每个内容事件进行了简要说明，包括事件参数/自变量以及可在 Joomla 手册中找到的任何使用示例。

有关 Joomla 过渡到使用事件类的背景信息，请参阅Joomla 4 和 5 的变更，您还可以在该部分找到有关访问参数和返回值的说明。

onContentPrepare​

说明​

这是为输出准备内容的第一阶段，也是面向内容的插件开展工作最常见的时机。由于项目及其相关参数作为引用传递，因此事件处理程序可在显示前对它们进行修改。

事件参数​

事件类 \Joomla\CMS\Event\Content\ContentPrepareEvent 具有以下参数

  • context - 传递给插件的内容上下文。这是组件名称和视图 - 或模块的名称（例如：com_content.article、com_contact.contact、com_users.user）。使用此信息检查您是否处于针对插件的期望上下文。

  • item - 视图正在渲染的项目，例如：文章、联系方式或用户。您可以使用（例如）$item->title访问此对象属性；可用属性取决于传递的是 quel 类型的item。如果您设置了其中任何属性，它们将被带入到网页输出中，但不会保存在数据库中。

  • params - 对项目参数关联数组（通常是项目数据库记录中的params字段，但对于 com_content 来说是attribs数据库字段）的引用。您设置的任何值都可以影响网页输出，但是不会保存在数据库中。

  • page - 与显示项目的分页列表的偏移关联的整数。但是，通常将其设置为 0 或 null，因此您可能不应该依赖它。

返回值​

无。

示例​

基本内容插件提供了处理文章文本以用fieldname的值替换{fieldname}的功能。

onContentAfterTitle​

这是一个信息请求，内容应放置在标题和正文之间。

事件参数​

事件类 \Joomla\CMS\Event\Content\AfterTitleEvent 有以下参数

尽管通过引用传递 item 和 params，但这不是修改项目数据的事件。使用 onContentPrepare 来实现此目的。

  • context - 传递给插件的内容上下文。这是组件名称和视图 - 或模块的名称（例如：com_content.article、com_contact.contact、com_users.user）。使用此信息检查您是否处于针对插件的期望上下文。

  • item - 由视图呈现的项目，例如，文章、联系信息或用户。

  • params - 与项目参数关联数组的引用（通常是项目数据库记录中的 params 字段，但对于 com_content 来说是 attribs 数据库字段）。

  • page - 与显示项目的分页列表的偏移关联的整数。但是，通常将其设置为 0 或 null，因此您可能不应该依赖它。

返回值​

HTML 字符串。这将在项目标题后显示。

信息

Joomla 自定义字段 (com_fields) 功能有一个关联的插件，该插件由此事件触发。该插件会针对已将“自动显示”选项设置为“标题后”的那些自定义字段返回 HTML。因此，此事件是在显示项目（如文章 (com_content 文章视图)、联系信息 (com_contact 联系信息视图) 等）的视图中触发的。如果你实现支持自定义字段的组件，则需要分发此事件。

onContentBeforeDisplay​

这是一个有关应立即置于组件主要内容（例如，文章文本）之前的的信息的请求。

对于生成 HTML 的视图，此操作可能包括使用已作为内容或相关参数指定样式。

事件参数​

事件类 \Joomla\CMS\Event\Content\BeforeDisplayEvent 有以下参数

尽管通过引用传递 item 和 params，但这不是修改项目数据的事件。使用 onContentPrepare 来实现此目的。

  • context - 传递给插件的内容上下文。这是组件名称和视图 - 或模块的名称（例如：com_content.article、com_contact.contact、com_users.user）。使用此信息检查您是否处于针对插件的期望上下文。

  • item - 由视图呈现的项目，例如，文章、联系信息或用户。

  • params - 与项目参数关联数组的引用（通常是项目数据库记录中的 params 字段，但对于 com_content 来说是 attribs 数据库字段）。

  • page - 与显示项目的分页列表的偏移关联的整数。但是，通常将其设置为 0 或 null，因此您可能不应该依赖它。

返回值​

HTML 字符串。这将在项目的文本前显示。

示例​

无。

信息

Joomla 自定义字段 (com_fields) 功能有一个关联的插件，该插件由此事件触发。该插件会针对已将“自动显示”选项设置为“在内容前面显示”的那些自定义字段返回 HTML。因此，此事件是在显示项目（如文章 (com_content 文章视图)、联系信息 (com_contact 联系信息视图) 等）的视图中触发的。如果你实现支持自定义字段的组件，则需要分发此事件。

它还被 Joomla 投票插件用于允许网站访问者针对内容指定星级评级。

onContentAfterDisplay​

这是一个在组件主要内容（例如文章文本）之后立即放置的信息请求。

事件参数 ​

事件类 \Joomla\CMS\Event\Content\AfterDisplayEvent 有以下参数

尽管通过引用传递 item 和 params，但这不是修改项目数据的事件。使用 onContentPrepare 来实现此目的。

  • context - 传递给插件的内容上下文。这是组件名称和视图 - 或模块的名称（例如：com_content.article、com_contact.contact、com_users.user）。使用此信息检查您是否处于针对插件的期望上下文。

  • item - 由视图呈现的项目，例如，文章、联系信息或用户。

  • params - 与项目参数关联数组的引用（通常是项目数据库记录中的 params 字段，但对于 com_content 来说是 attribs 数据库字段）。

  • page - 与显示项目的分页列表的偏移关联的整数。但是，通常将其设置为 0 或 null，因此您可能不应该依赖它。

返回值 ​

HTML 字符串。这将在项目文本之后立即显示。

信息

Joomla 自定义字段（com_fields）功能具有由该事件触发的关联插件。此插件返回了启用自动显示选项为在显示内容之后中，用于那些自定义字段的 HTML。因此，此事件在显示项目（例如文章（com_content 文章视图）、联系人（com_contact 联系人视图）等）的视图中触发。如果您实施了支持自定义字段的组件，那么您将需要调度此事件。

onContentPrepareData​

说明​

在 Joomla 表单的初始数据被设置之后，调用此事件，并可用于修改该预填充数据。

在 Joomla 中，加载表单时，有一个用于指定表单的初始数据的回调 loadFormData。（例如，在编辑记录时，初始数据将是记录的现有字段）。在 loadFormData 结束时，Joomla 扩展调用 preprocessData，而该函数的默认版本将触发此事件。

在 Joomla 扩展中，它在 onContentPrepareForm 之前触发。

事件参数 ​

事件类 \Joomla\CMS\Event\Model\PrepareDataEvent 有以下参数

  • context - 传递给插件的内容的上下文。这是组件名称和项目名称（如 com_content.article、com_contact.contact、com_users.user）。使用它检查您是否处在插件所需上下文中。

  • data - 表单字段的初始（预填充）数据，以 PHP 对象形式通过。您可以使用（例如）$data->title访问此对象的属性；可用的属性将取决于传递中 data 的类型。如果您设置了这些属性中任何一个，那么它们将在呈现给用户的表单数据中进行修改。

返回值​

无。

onContentPrepareForm​

加载表单后触发此事件，并可以使用“动态更改表单”中描述的技术修改表单对象。

在 Joomla 组件中加载表单

  • 每当即将在页面上显示表单时
  • 在处理表单 POST 的过程中（因需要执行字段验证）

在这两种情况下都会分派 onContentPrepareForm 事件。

事件参数​

事件类 \Joomla\CMS\Event\Model\PrepareFormEvent 参数如下

  • 表单 - 表单对象。此对象（可通过 $form->getName() 获取）的名称对象格式为“com_content.article”、“com_contact.contact”，可用于检查自己是否处于插件所需的上下文中。然后，可以使用表单 API方法修改此表单对象。

  • 数据 - 提交表单中字段的预填充数据，以 PHP 对象形式传递。可以使用 $data->title 等方式访问此对象的属性；可用的属性取决于传递的数据类型。如果设置其中任何属性，则会在提供给用户的表单数据中修改它们。

如果是在处理表单 POST 的过程中触发事件，则数据将为空，修改它也不会产生任何影响。

返回值​

无。

onContentNormaliseRequestData​

描述​

此事件在使用控制器和模型从提交的表单数据处理到数据库的过程中引发。此事件由控制器在过滤和验证提交表单数据（通常是浏览器在jform HTTP POST 参数内发送的数组）之前触发。数据数组会转换为 PHP 对象，然后作为事件中的参数传递。由于 PHP 对象总是按引用传递，侦听此事件的插件可修改提交的表单数据。

事件参数​

事件类 \Joomla\CMS\Event\Model\NormaliseRequestDataEvent 有以下参数

  • context - 传递给插件的内容的上下文。这是组件名称和项目名称（如 com_content.article、com_contact.contact、com_users.user）。使用它检查您是否处在插件所需上下文中。

  • 数据 - 作为 PHP 对象传递的已提交表单字段中的数据。你可以使用例如 $data->title 等来访问此对象的属性；可用的属性取决于将传递什么类型的 数据。如果你设置了其中任何属性，那么它们将在表单数据中修改，并且（很可能）保存在数据库中。

  • 表单 - Joomla 表单实例，如 如何使用 Joomla 表单 中所述。

返回值​

无。

onContentBeforeValidateData​

在处理 Joomla 表单中从 POST 提交的数据时，该事件在模型应用验证规则之前触发。你可以使用此事件修改已提交的数据，或者（不太可能）修改表单对象。

事件参数​

事件类 \Joomla\CMS\Event\Model\BeforeValidateDataEvent 有以下参数

  • 表单 - 表单对象。此对象的 名称 对象（可通过 $form->getName() 获取）将是 'com_content.article'、'com_contact.contact' 等格式，你可以使用它来检查你是否在插件的所需上下文中。

  • 数据 - 已提交的表单数据，作为关联数组按引用传递。可用数组元素取决于表单。如果你设置了其中任何元素，那么它们将在应用数据验证前进行修改。

返回值​

无。

onContentBeforeSave​

说明​

在任何调用将在数据库中保存新数据或更新数据的操作之前，该事件在模型级别触发。你可以通过返回 false 中止保存。如果你确实返回了 false，那么默认情况下，通过调用 $this->setError($table->getError) 将向用户显示的错误设置。因为可能没有与表对象关联的错误，你可能希望排队显示你自己的消息，向用户解释为什么拒绝保存。

onContentBeforeSave 针对大多数类型的数据触发（例如内容、联系人）。但是，一些模型会分派其自己的事件类型

  • onExtensionBeforeSave 为扩展触发
  • onUserBeforeSave 针对用户触发

事件参数​

\Joomla\CMS\Event\Model\BeforeSaveEvent 事件类具有以下参数

  • 上下文 - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact）。使用此功能来检查你是否处于插件所需的上下文中。

  • 项目 - 包含要存储的数据的 Table 对象。

  • isNew - 如果内容将被创建（相对于更新），则设置为 true 的布尔值

  • data - 即将保存的数据，作为关联数组传递。

请注意，item 和 data 都显示要保存的数据，换言之，即经过修改的数据。两者均未显示当前位于数据库中的数据值。

返回值​

返回 false 以中止保存。

onContentAfterSave​

说明​

在对数据库中保存新数据或更新的数据发出调用后，将在模型级别触发此事件。你可以使用此事件来启动在数据库或文件中存储相关信息。

onContentAfterSave 针对大多数类型的数据（例如内容、联系人）触发。但是，某些模型分派它们自己的事件类型

  • onExtensionAfterSave 针对扩展名触发
  • onUserAfterSave 针对用户触发

事件参数​

\Joomla\CMS\Event\Model\AfterSaveEvent 事件类具有以下参数

  • 上下文 - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact）。使用此功能来检查你是否处于插件所需的上下文中。

  • 项目 - 包含已存储数据的 Table 对象。

  • isNew - 如果创建了内容（相对于更新），则设置为 true 的布尔值

  • data - 已经保存的数据，作为关联数组传递。

返回值​

无

onContentBeforeDelete​

说明​

该事件在数据库中删除记录的调用之前在模型级别触发。你可以通过返回 false 来中断删除。如果你确实返回了 false，那么默认情况下，显示给用户的错误将通过调用 $this->setError($table->getError) 设置。由于 Table 对象可能没有关联的错误，因此你可能希望加入你自己的消息来向用户解释为什么拒绝删除。

在 Joomla 组件中，当你“废弃”某一项（如文章）时，该项并未删除，而是其状态被更改为“废弃”。当你选择一项并选择“清空废纸篓”时，才会删除该项。若在此清空废纸篓的操作中选择多项，那么则会为每个选择要删除的记录触发此事件。

onContentBeforeDelete 触发于大多数类型的数据（例如，内容、联系信息）。然而，有些模型会分派它们自己的事件类型

  • onExtensionBeforeDelete 触发于扩展程序
  • onUserBeforeDelete 触发于用户

事件参数​

事件类 \Joomla\CMS\Event\Model\BeforeDeleteEvent 具有以下参数

  • 上下文 - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact）。使用此功能来检查你是否处于插件所需的上下文中。

  • item - 包含要删除的数据的 Table 对象。

返回值​

返回 false 来中断删除。

onContentAfterDelete​

说明​

在数据库中删除记录的调用之后，该事件在模型级别触发。你可以使用此事件来启动相关信息的删除，例如。

如果你一次删除多条记录，那么此事件将针对每条记录触发。

onContentAfterDelete 触发于大多数类型的数据（例如，内容、联系信息）。然而，有些模型会分派它们自己的事件类型

  • onExtensionAfterDelete 触发于扩展程序
  • onUserAfterDelete 触发于用户

事件参数​

事件类 \Joomla\CMS\Event\Model\AfterDeleteEvent 具有以下参数

  • 上下文 - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact）。使用此功能来检查你是否处于插件所需的上下文中。

  • item - 包含要删除的数据的 Table 对象。

返回值​

无

onContentBeforeChangeState​

说明​

此事件在多种项目状态被更改之前在模型级别触发。您可以通过返回 false 来取消状态更改。然而，在这种情况下，您应该入队一条消息来向用户解释为什么状态更改被拒绝。

警告

Joomla 不会恰当地处理该拒绝——请求的状态变更未应用，但输出给用户的消息可能表示该操作已成功。

此情况会在以下情况下发生，当用户

  • 显示文章表单（它显示多篇文章的页面）
  • 选中多篇文章（通过复选框）
  • 选中更改状态（发布/取消发布/存档/废弃）的操作

该事件还会针对类似组件引发（例如，联系人、标签），但不会针对启用/禁用用户或扩展引发。

警告

无论何时编辑项目、更改其发布状态，然后保存，此事件都不会引发。

事件自变量​

事件类 \Joomla\CMS\Event\Model\BeforeChangeStateEvent 具有以下自变量

  • context - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact、com_categories.category）。使用该内容来检查您是否处于插件所需的上下文中。

  • pks - 状态即将更改的记录的主键数组。

  • value - 要应用的已发布状态的值（0：未发布，1：已发布，2：已存档，-2：已废弃）。

返回值​

返回 false 来取消状态更改。

onContentChangeState​

请注意，此事件未被称作“onContentAfterChangeState”——Joomla 在这里有些混乱。

描述​

在多种项目的许多状态更改后，此事件在模型级别触发。

警告

无论何时编辑项目、更改其发布状态，然后保存，此事件都不会引发。

事件自变量​

事件类 \Joomla\CMS\Event\Model\AfterChangeStateEvent 具有以下自变量

  • 上下文 - 传递给插件的内容的上下文。这是组件名称和项目名称（例如 com_content.article、com_contact.contact）。使用此功能来检查你是否处于插件所需的上下文中。

  • pks - 其中其状态已更改的记录的主键数组。

  • 值 - 应用的已发布状态的值（0：未发布，1：已发布，2：存档，-2：已删除）。

返回值​

无。

onCategoryChangeState​

描述​

更改若干类别的状态后，会在模型级别触发此事件。当选择若干类别更改其状态时，按以下顺序触发事件：

  • onContentBeforeChangeState
  • onContentChangeState
  • onCategoryChangeState

注意，onCategoryChangeState 的 context 与其他不同。

事件参数​

事件类 \Joomla\CMS\Event\Model\AfterCategoryChangeStateEvent 具有下列参数：

  • context - 传递给插件的内容的上下文。这是与类别关联的组件（例如 com_content、com_contact）。使用此参数检查插件的理想上下文。

  • pks - 状态更改的类别记录的主键数组。

  • 值 - 应用的已发布状态的值（0：未发布，1：已发布，2：存档，-2：已删除）。

返回值​

无。