XOOPS全局通知系统

导航: 上一页 | 首页 | DedeCMS | 帝国CMS | Drupal | PHPCMS | PHP168 | Joomla | PowerEasy | SupeSite

引言

通知特性为用户提供了一种集中的订阅特殊事件的方法，当事件发生时通过邮件或私人消息来接收。

用户观点--如何订阅事件

在允许通知模块的每张页面上，你将看到可以订阅的事件的列表。这个列表可能内嵌在模块中，也可能在一个'block'里，或两者都有，这取决于管理员对这个特性的配置。

事件的例子包含：“通知我最新的线索中的新邮件” ，“通知我当一个新的论坛被创建时” ，“通知我当评论被发表到当前的链接时” ，以及“将此线索加入书签” 。书签事件是特殊的，因为它不产生任何的通知消息……仅仅让你跟踪不同的模块中的不同条目。（你可以在用户菜单的通知页面看到你的标签。）

要订阅一个事件，选择复选框，然后点击"立即更新"按钮。不订阅就不要选复选框，然后点击"立即更新"按钮。你可以在同一时间做多种改变。

你同样可以在用户菜单中找到一个叫做通知的页面。它会给出你当前订阅的所有事件的列表。你可以在这个页面做成批的删除，来删除任何你不想再接收的通知。

注意，你的用户个人信息同样包括了两个你可以控制的相关选项。

• 第一个选项是通知方法，决定你将如何接收通知信息……是通过电子邮件（使用你个人信息中设定的地址），或者是通过短消息（使用网站内部的私人消息系统）。你可以选择暂时拒收所有通知。要暂时拒收请只使用这种方式；要永久拒收则不要订阅事件。举个例子说明：当你在度假的时候，离开时你可以设置成禁止接受，将消息悬挂起来；当你回来了就可以激活而不需要重新订阅所有的事件。

• 第二个界面选项时默认的通知模式。可用选项为总是发送（默认），就是发送消息来订阅所有的时间。另一种模式是只发送一次后禁用直到下一次登陆，对大业务量的线程来说是非常有用的。你会收到线程中一条新的邮件的通告消息，然后通告将被悬挂起来。所以你会知道至少有一个新邮件，但不知道有多少个。当你再次登陆时通告会自动被激活。理论上，当你离开时，你被告知至少有一个邮件，你登陆以得到线程的消息并希望被通告那个线程的更多的邮件。最后一种模式是只发送一次后禁用，你只会收到一个消息然后不再订阅。

要改变你当前一个事件的订阅模式，你就不得不改变你个人信息的模式，然后再停止订阅或重新订阅那个事件。

管理员观点--配置通知

当模块支持通知时，两个选项会被自动加到模块的设置菜单中。

• 启用通知：这个选项允许你控制用户可以怎样订阅通知（例如：通过通知选项区块，或是通过一个表格嵌入模块页面自身（联机的））。它同样允许你完全的禁止通知（例如：不发送消息）。

• 通知事件：这个选项允许你选择你的用户可以订阅哪些事件（来自模块可用的全部合理的事件）。某些事件可以自动添加，除了模块编写者提供的以外。如果模块支持评论功能，评论添加完毕、评论提交完毕的选项会自动出现。书签的选项在某些范围内同样是可用的。用户完全看不到停用的事件。

模块编写者的观点--在你的模块中添加通告

修改xoops_version.php

• 前言

模块的配置文件xoops_version.php中，指定模块通知选项是可用的。每个分类从本质上代表了模块处理的一种类型的对象。例如：在 newbb模块里，我们有分类：'thread'代表发生在thread上的事件，'forum'代表发生在forum上的事件，以及'global'代表发生在任何非特定事情上的事件。每个分类（除了'global'）必须关联一个唯一的ID，这个ID可以用来从对应的分类中搜索一个特定的元素（例如；从所有的论坛分类中指定的部分）。

下一步，你指定单独的通知事件。每个事件属于一个特定的分类。例如：在newbb模块中，'new_post'是属于分类 'thread'的一个事件。那么用户可能会订阅属于一个特殊的线索的'new_post'通知，只要一个新邮件被加到那个线索他就会收到一个通知信息。另一个事件是‘通知我这个论坛中的新线索’，它属于分类'forum'。最后还有一个事件‘通知我新的论坛’，它属于分类'global'。

少数事件是自动维护的……发送的评论（以及提交的评论（只有管理员的是））的通知，及书签（不通知用户，但让用户跟踪固定的对象）。因为有了这些自动的事件，你无须指定xoops_version.php中的什么，除非你希望忽略显示的文本字符串或是邮件模块（一般不推荐）。

• 首行添加：

$modversion['hasNotification'] = 1;

• 指定你的分类：

$modversion['notification']['category'][1]['name'] = 'thread';
$modversion['notification']['category'][1]['title']= _MI_NEWBB_THREAD_NOTIFY;
$modversion['notification']['category'][1]['description']= _MI_NEWBB_THREAD_NOTIFYDSC;
$modversion['notification']['category'][1]['subscribe_from']= 'viewtopic.php';
$modversion['notification']['category'][1]['item_name'] = 'topic_id';
$modversion['notification']['category'][1]['allow_bookmark'] = 1;

• name:分类的名称
• title：分类的标题（用语言字符串）
• description：分类的描述（用语言字符串）
• subscribe_from：用户允许订阅的所有脚本的一个数组（所有的脚本用'*'。无脚本就省略这行。注意：只有你的模块为用户订阅提供另外的方法时，你可以不订阅脚本。例如：表单中的自定义复选框）
• item_name：HTTP用get方式监视参数，通过指定分类中特定的条目（例如：论坛ID或线索ID）
• allow_bookmark：如果你希望系统允许该条目可被用户加入书签就设为1。

• 指定你的事件：

$modversion['notification']['event'][1]['name'] = 'new_post';
$modversion['notification']['event'][1]['category'] = 'thread';
$modversion['notification']['event'][1]['title'] = _MI_NEWBB_THREAD_NEWPOST_NOTIFY;
$modversion['notification']['event'][1]['caption']= _MI_NEWBB_THREAD_NEWPOST_NOTIFYCAP;
$modversion['notification']['event'][1]['description']= _MI_NEWBB_THREAD_NEWPOST_NOTIFYDSC;
$modversion['notification']['event'][1]['mail_template'] = 'thread_newpost_notify';
$modversion['notification']['event'][1]['mail_subject']= _MI_NEWBB_THREAD_NEWPOST_NOTIFYSBJ;

• name:事件的名称
• category：事件的分类
• title：分类的标题（用语言字符串）
• caption：表单“通知我当……”中的描述（使用语言字符串）
• description：事件的描述（用语言字符串）
• mail_template：模块目录language/<language>/mail_template中的邮件模板（省略后缀'.tpl'）
• mail_subject：电子邮件的主题（使用语言字符串）

可用的附加选项：

• admin_only：如果你希望事件只有模块管理员可以看见就设为1
• Invisible：如果你希望事件是不可见的就设为1……例如：不要在模块的首选项或通知区块中显示。被用作'custom'通知：例如，在'mylinks'中，当你链接提交被批准时，你可以（在提交表单上）签定一个以前的通知。'approve'事件就会不可见了。

对自动事件（评论，评论提交和书签），如果你希望忽略文本字符串或邮件模板就可以在这指定信息（还没测试，不推荐这样做）。只指定你要的别的事件。

• 指定帮助函数

• 查找

如果你的模块支持评论或书签功能，你将需要编写一个帮助函数。

$modversion['notification']['lookup_file'] = 'include/notification.inc.php';
$modversion['notification']['lookup_func'] = 'forum_item_info';

指定文件和这个文件中的帮助函数。作为forum_item_info($category,$itemid)被核心程序访问。你的函数将返回一个相关数组，其名称与你的条目相同，路径与访问该条目的路径相同。以/modules/newbb/include /notification.inc.php做一个例子。

• 标签

另一个帮助函数用来在邮件模板标签（看下面的标签信息）中产生置换。标准的标签是自动定义的。标签可以在触发一个事件的期间传递（通常更便利），或在通知期间，标签函数被自动访问。

$modversion['notification']['tags_file']='include/notification.inc.php';
$modversion['notification']['tags_func'] = 'forum_tags';

如果你使用评论通知的用户化电子邮件并且你希望使用这张页面上的非标准化的标签，你才真正需要。而正常情况下是不需要的。

准备notification_update.php文件

从模块目录newbb复制到你的模块根目录下：

notification_update.php

电子邮件标签

当发送一条消息时，你可以把标签放进你的电子邮件中来扩展。像这样用花括号括起来就可以了：{TAG}。

• 常用内部标签

普通标签：

• X_SITEURL:站点的URL路径
• X_SITENAME:站点的名称
• X_ADMINMAIL:管理员的电子邮件地址

用户相关标签：

• X_UNAME:用户名
• X_UID:用户ID
• X_UACTLINK:用户帐号激活链接（自从它成为用户注册过程后，你也许永远也不用这个）

通知相关标签：

• X_MODULE:模块名
• X_MODULE_URL:到模块的主页的链接
• X_NOTIFY_EVENT:被触发的事件
• X_NOTIFY_CATEGORY:事件的分类
• X_UNSUBSCRIBE_URL:到用户通知页面的链接

特殊标签：

这些是由内核产生的通知事件使用的，像是评论。你在自己的邮件模块中可能不会用到它们，使用更多易读的标签名来代替。

• X_ITEM_TYPE:条目的类型（分类'title'）
• X_ITEM_NAME:例如：论坛的名称，线索的标题，等等……
• X_ITEM_URL:条目的URL地址

顺便提一下，系统从你的查找功能函数中产生X_ITEM_NAME and X_ITEM_URL，所以只有当查找功能函数被定义了它们才是可用的。

触发事件

当发送评论时将自动触发评论事件。依据评论规则，管理员可以订阅提交到一个特定条目的评论的通知。所有的用户可以订阅提交到一个特定条目的评论（已审核的）的通知。其他的事件必须通过访问被明确的触发：

$notification_handler =& xoops_gethandler('notification');
$notification_handler->triggerEvent ($category, $item_id, $event, $extra_tags = array(), $user_list = array(), $module_id = null, $omit_user_id = 
null);

在你的程序中的适当位置。

• $category: 分类的名字（字符串型）
• $item_id: 分类的ID/如果你想通知一个全局事件，类型设为'0'（整型）
• $event: 事件的名称（字符串型）
• $extra_tags:你希望在你的邮件模板中扩展的标签的相关数组。

标签是键，扩展是值。例如：$extra_tags['MY_TAG'] = "My text"。核心还是访问你的'tags'函数，如果该函数被定义了的话（看上面的描述）所以你可以把模块范围的标签放在那，而不是在模块中的触发器单独生成。

• $user_list: 如果空白，任何订阅事件的用户将收到通知。如果你指定一个用户数组（用户ID的数组），只有那些用户将被通知（只有当他们订阅时）。
• $module_id: 模块ID（默认当前模块）
• $omit_user_id: 通知中忽略用户ID（默认当前用户），但你可以设定'0'如果你希望当前包括用户。

总之，只有前四个参数是必需的。

允许用户订阅通知

一个区块中提供的订阅选项依照xoops_version.php中的规定信息完全自动的实现。在主模块页面中提供订阅选项，你需要在相关模板中添加下面这行：

<{include file='db:system_notification_select.html'}>

另外，你可以选择往表单中增加客户订阅选择（例如：使用复选框）。举个例子：若用户在论坛发送消息时选择了复选框，你可以直接访问：

$notification_handler =& xoops_gethandler('notification');
$notification_handler->subscribe ($category, $item_id, $events, $mode = null, $module_id = null, $user_id = null);

• $mode: 你可以强制设置特殊通知模式（看上面的讨论）。如果为空，则使用默认的用户模式（他们的个人设置）。

设置复选框的初始状态，你可能希望看见用户是否订阅当前事件。你可以对下述的函数做这样的处理（返回真/假）：

$notification_handler =& xoops_gethandler('notification');
$notification_handler->isSubscribed ($category, $item_id, $event, $mode = null, $module_id = null, $user_id = null)

总之，只有前三个参数是必需的。

删除通知

最后一件要做的事：只要你从模块中删除一个条目（例如：删除一个线索或一个邮件），你必须删除这个条目的所有通知。

你可以这样处理这个函数：

xoops_notification_deletebyitem ($module_id, $category, $item_id);