xoops forums

goffy

Quite a regular
Posted on: 1/23 19:19
goffy
goffy (Show more)
Quite a regular
Posts: 377
Since: 2010/12/27
#1

Xoops notification system

Hi

is there somewhere a detailed description how xoops notication system is working and how to use it in a new module?

Mamba

Moderator
Posted on: 1/24 2:47
Mamba
Mamba (Show more)
Moderator
Posts: 10799
Since: 2004/4/23
#2

Re: Xoops notification system

From some old document:

Introduction
The notification feature provides a centralized way for users to subscribe to particular events, then receive notification by email or private message when that event occurs.

The User's Perspective - How to Subscribe to events
On each page of a notification-enabled module, you will be presented with a list of available events to which you can subscribe. This list will be embedded in the module, or in a 'block', or both, depending on how the administrator has configured this feature.

Examples of events include: "Notify me of new posts in the current thread", "Notify me when a new forum is created", "Notify me when a comment is posted to the current weblink", and "Bookmark this thread". The Bookmark event is special in that it doesn't generate any notification messages... it is simply a way to let you keep track of various items in various modules. (You can see your bookmarks on the Notifications page of the User Menu.)

To subscribe to an event, check the box, and click the "Update" button. To unsubscribe, uncheck the box, and click the "Update" button. You may make multiple changes at one time.

You can also find a page in the User Menu, called Notifications. This will give you a list of all events to which you are currently subscribed. There you can do bulk deletion of any notifications you no longer wish to receive.

Note, your user profile also contains a couple of relevant options which you can control.

The first option, Notification Method, determines how you will receive notification messages... by email (using the address in your profile), or by private message (using the built-in private message system in the website). Alternatively, you can disable all notifications. Please only use this for temporary disabling; to disable permanently, unsubscribe from the event(s). For example when you are on vacation, you can set the method to disable to suspend messages while away and then reactivate when you return, without having to resubscribe to all events.

The second profile option is a default Notification Mode. Available options are Send always (the default) which sends a message for all events. Another mode is Send once then disable until next login which is useful for e.g. high-traffic threads. You will receive one notification message for a new post in the thread, then notification will be suspended. So you will know there is at least one new post, but you don't know how many. Notification will be reactivated automatically when you log-in again. The theory is that when you are away, you are notified that at LEAST one post was made, you log in to catch up on the thread, and then you wish to be notified of further posts to that thread. The final mode is Send once then deactivate which sends only one message, then unsubscribes you.

To change the mode of an event you are currently subscribed to, you will have to change the mode in your profile, then unsubscribe and resubscribe to that event.


The Administrator's Perspective - Configuring Notification
When notification is supported by a module, two options are automatically added to the preferences menu for the module.
Enable Notification: This option lets you control how the user may subscribe to notifications (i.e. via the Notification Options block, or via a table embedded in the module page itself (inline)). It also lets you disable notifications entirely (i.e. sends out no messages).

Notification Events: This option lets you select which events (out of all possible events made available by the module) your users may subscribe to. Some events are added automatically in addition to what was provided by module writer. If comments are supported by the module, options for Comment and Comment Submit will appear automatically. The option Bookmark may also be available for some categories. Disabled events will be entirely invisible to users.

The Module Writer's Perspective - Adding Notification to your Module

Introduction : Modifying xoops_version.php
In the module configuration file xoops_version.php , you specify the notification options which are available for your module. These options are grouped into categories.

Each category essentially represents a type of object which is handled by the module. e.g. In the newbb module, we have the categories: 'thread' for events that happen to threads, 'forum' for events that happen to forums, and 'global' for events that do not happen to any particular "thing".

Each category (except 'global') must have associated with it a unique ID number which can be used to select a particular element from that category (e.g. a specific forum from the category of all forums).

Next, you specify the individual notification events. Each event belongs to a particular category. e.g. In the newbb module, one event in the 'thread' category is 'new_post'. Users may then subscribe to 'new_post' notifications for a PARTICULAR thread, and will receive a notification message whenever a new post is added to that thread. Another event is 'Notify me of new threads in this forum', which belongs to the 'forum' category. And finally, there is the event 'Notify me of new forums', which belongs to the 'global' category.

A few events are taken care of automatically... notification of posted comments (and submitted comments (for admins only)), and bookmark (which doesn't notify users, but lets users keep track of certain objects). For these automatic events, you don't need to specify anything in xoops_version.php, unless you wish to override the displayed text strings, or the mail templates (NOT RECOMMENDED).

First line to add:
$modversion['hasNotification'] = 1;


Specify your categories :
$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;

        namethe name of the category
        
titlethe title of the category (use language strings)
        * 
descriptiona description of the category (use language strings)
        * 
subscribe_froman array of all scripts where user is permitted to subscribe(Use '*' for all scriptsOmit this line for no scripts.
           Noteyou would specify no scripts only if your module provides other ways for users to subscribee.gcustom checkboxes within forms.)
        * 
item_namethe HTTP //get// parameter to watch, which specifies the ID of the specific item in the category (e.g. forum ID or thread ID). If set in xoops_version.php, the //get// parameter must be submitted via HTTP call, otherwise, the notification           categories remain hidden.
        
allow_bookmarkset to 1 if you want the system to allow this item to be bookmarked by users


Specify your events
$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;

       * 
namethe name of the event
       
categorythe category of the event
       
titletitle of event (use language strings)
       * 
captiondescription in form "Notify me when..." (use language strings)
       * 
descriptiondescription of event (use language strings)
       * 
mail_templatemail template in ##language//mail_template## directory of module (omit the '.tpl' suffix)
       
mail_subjectsubject of email (use language strings)


Additional options are available:
        admin_onlyset to 1 if you wish the event to be visible only to module administrators
        
invisibleset to 1 if you wish the event to be invisible... i.ewon't show up in module

preferences or in notification  blocks. It is used for 'custom' notifications: e.g. in 'mylinks', you can sign up (on the submit form) for a one-time   notification when your link submission is approved. The 'approve' event is invisible.

For the automated events (comment, comment_submit, and bookmark), you can specify info here if you wish to override text strings or mail templates (NOT RECOMMENDED YET, NOT FULLY TESTED). Just specify them as you would the other events. Specify helper functions

Lookup - if comments or bookmarks
If your module supports comments or bookmarks, you will need to write a helper function.
$modversion['notification']['lookup_file'] = 'include/notification.inc.php'
   
$modversion['notification']['lookup_func'] = 'forum_item_info';


This specifies the file, and function within that file which is the helper function. It is called by the kernel as forum_item_info($category,$itemid). Your function should return an associative array with 'name' equal to some name for your item, 'url' equal to the URL for viewing that item. See /modules/newbb/include/notification.inc.php for an example.

Tags
Another helper function is used to generate substitutions for filling in mail template tags (see below for tag info). The standard tags are automatically defined. Tags can be passed during triggering of an event (which is usually more convenient), or when the tags function is automatically called during notification.
$modversion['notification']['tags_file'] = 'include/notification.inc.php'
   
$modversion['notification']['tags_func'] = 'forum_tags';


This is only really needed if you use customized emails for comment notification and you wish to use tags not in the standard list on this page. Normally it is not needed.
Copy this file to your module directory
From the newbb module directory, copy to your module root directory
notification_update.php



Email tags
You can put tags in your email to be expanded when a message is sent. Simply place curly brackets around it, like so: {TAG}.
There are several built-in tags:

General tags
X_SITEURL URL of site
       
X_SITENAME name of site
       
X_ADMINMAIL administrator email address



User related tags
X_UNAME username
       
X_UID user id
       
X_UACTLINK user account activation link (you will probably never have use this
         
since it is part of the user registration process)



Notification related tags
X_MODULE name of module
       
X_MODULE_URL link to index page of the module
       
X_NOTIFY_EVENT event that was triggered
       
X_NOTIFY_CATEGORY category of the event
       
X_UNSUBSCRIBE_URL link to user's notification page



Special tags
These are used by kernel-generated notification events like comments. You will probably not use them in your own mail templates, instead using more readable tag names.
X_ITEM_TYPE type of item (the category 'title')
           * 
X_ITEM_NAME e.gthe name of the forumtitle of the threadetc..
           * 
X_ITEM_URL URL of the item


Incidentally, the system generates //X_ITEM_NAME// and //X_ITEM_URL// from your lookup function, so they will only be available when the lookup function is defined.

Triggering events
Comment events are triggered automatically when comments are posted. Depending on the comment rules, the admin may subscribe for notification of comments submitted to a particular item. All users may subscribe for notification of (approved) comments posted to a particular item.
Other events must be explicitly triggered by calling
        $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);

at the appropriate place in your code.

$category the name of the category (string)
       * 
$item_id the ID of the category item / if you want to notify of a global eventtype '0' (int)
       * 
$event the name of the event (string)
       * 
$extra_tags associative array of tags you wish to expand in your mail template.


The tag is the key, and the expansion is the value. e.g. $extra_tags['MY_TAG'] = "My text". The kernel will also call your 'tags' function if defined (see above for description) so that you may put module-wide tags in there, instead of generating them separately for each trigger in your module.
$user_list - if left blankany user who subscribed to the event will receive notification. If you specify an array of users (an array of user id's), only those users will be notified (only if they are subscribed).
* $module_id - module ID (defaults to current module)
* $omit_user_id - ID of user to omit from notifications (defaults to current user), but you can specify '
0' if you wish the current user to be included.

In general, only the first 4 parameters are needed.

Allowing users to Subscribe to Notifications
Providing subscription options in a 'block' is carried out completely automatically according to the information specified in xoops_version.php.

To provide subscription options in the main module page, you need to add the following line to the relevant template(s):
<{include file='db:system_notification_select.html'}>


In addition, you may choose to add custom subscription options to forms (e.g. using a checkbox). If the user selects the checkbox when posting a message in a forum for example, you make a call directly to:
$notification_handler =& xoops_gethandler('notification');
$notification_handler->subscribe ($category, $item_id, $events, $mode=null, $module_id=null, $user_id=null).
* $mode - you can force a particular notification //mode// (see discussion above). If left blank, the default user mode (from their profile) will be used.
Generally, only the first 3 parameters are needed.
To set the initial state of the checkbox, you might like to see if the user is currently subscribed to the event. You can do so with the following function (returns true/false):
$notification_handler =& xoops_gethandler('notification'); 
$notification_handler->isSubscribed ($category$item_id$event$mode=null$module_id=null$user_id=null)


Generally, only the first 3 parameters are needed.

Deleting Notification for Deleted Items
One final thing you need to do: whenever you delete an item from your module (e.g. delete a thread or delete a post), you need to delete all notifications for this item.
You can do so with this function call:
xoops_notification_deletebyitem ($module_id$category$item_id);


All parameters are required
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

princeemilec

Just popping in
Posted on: 11/3 21:03
princeemilec
princeemilec (Show more)
Just popping in
Posts: 3
Since: 11/3 20:12
#3

Re: Xoops notification system

Hi

How can someone get a tutorial on how to use the updated version?

How do I relate to my friends that xoops is more suitable since it doesn't have space for the disabled to use?

princeemilec

Just popping in
Posted on: 11/4 15:42
princeemilec
princeemilec (Show more)
Just popping in
Posts: 3
Since: 11/3 20:12
#4

Re: Xoops notification system

Hi

Please is there any way to add voice notification?

Mamba

Moderator
Posted on: 11/5 20:55
Mamba
Mamba (Show more)
Moderator
Posts: 10799
Since: 2004/4/23
#5

Re: Xoops notification system

Can you give us an example of what would you like to see/hear?

If you're using iPhone or iPad, these devices should help you with reading to you, or you can use Siri for it.
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs

princeemilec

Just popping in
Posted on: 11/6 6:31
princeemilec
princeemilec (Show more)
Just popping in
Posts: 3
Since: 11/3 20:12
#6

Re: Xoops notification system

How can I add video chat, recorder, voice massage group event. This are some of the things that will make my work more accessible to those who has some level of disabilities. And also highly security is advice.

Thanks

Mamba

Moderator
Posted on: 11/6 6:54
Mamba
Mamba (Show more)
Moderator
Posts: 10799
Since: 2004/4/23
#7

Re: Xoops notification system

You can definitely record a video or MP3 voice message, save it as a file, and then provide a link to that file in your post. There should be relatively easy.

Right now we don't provide a mechanism where you can record live a message or video and store it automatically.
Support XOOPS => DONATE
Use 2.5.10 | Docs | Modules | Bugs