Advanced Email Notification¶

What does it do?¶

The Advanced Email Notification extension enables users to receive email notification of certain types of events. Users (both FE and BE users) can indicate if and what type of notifications they want to receive. Administrators can create custom notification types, both for FE and BE users. The notifications are sent out at regular intervals (typically once per hour) through a cron-job, thus this extension works only on Unix/Linux hosts, not on Windows.

Disclaimer¶

It is an advanced email notification extension, meaning that you can customize it in many ways and you can create almost any type of notification. However, flexibility may come at the cost of complexity. You will also need some advanced typo3 knowledge to get it working (you will need to make some changes in the .php files for example). The extension is at the moment still beta, although it is used on a few production sites. I am looking for feedback, so please let me know if you can think of improvements, or if you have certain notifications that you think should be part of the predefined set.

Screenshots¶

FE User set notifications:

BE User set notifications:

Manage predefined notifications (administrator only)

Manage custom notifications (administrator only)

Check which users have notification settings on:

Check history of sent notifications:

FE Users¶

Go to the page where you can set email notifications. Select the notification events that you want to be notified of.

BE Users¶

Go to User > BE Notifications. Select the notification events that you want to be notified of.

Install predefined email notifications¶

The file 'predefined.sql' in the 'doc' folder contains the SQL commands to upload the first 3 predefined notification event types. These are:

• Content Change: When someone changed content on one of your pages.
• New BE User: When a new BE user is added.
• New Page: When a new page is added.

Please let me know if you see the need for additional predefined notifications. I will be happy to add them.

Create custom notifications¶

The most useful feature of this extension is that you can create your own custom notifications. Below follows a little example of such a custom notification. Suppose we installed the kc_sermonmgr plugin to manage all the sermons and other content of our own church. It would be great if our Front-End users could decide to be notified each time a new sermon was added to the website. In order to achieve this, we need to follow these steps:

Create new custom notification. Go to the Back-End and click on Tools > Notifications > Manage Custom Notifications

Click on 'Create New Notification'.

Create an Event LL Label (LL stands for Local Language, you can use the multilanguage capabilities of Typo3 with this extension). Press save.

Now you will need to modify the locallang.xml file that you can find in typo3conf/ext/kc_emailnotification/pi1/ folder. Add these two lines:

<label index="newsermon_label">New Sermon</label>

<label index="newsermon_description">When a new sermon is added.</label>

Go back to Tools>Notifications>Manage Custom Notifications. You should now see the label and description appear that you just entered in the locallang.xml file.

Keep the status of Off for the time being. Keep the FE/BE selector on FE (since we want to make this a FE users notification).

Enter the page ID of the page that contains the kc_sermonmgr plugin in the link PID field. This will be used in the URLs that will be embedded in the notification email to bring the users straight to the right section where the changes have been made. This works fine also with realURL. This page ID can also be dynamic. If you enter ###pid### instead of a page number, the extension will search for the 'pid' that is defined in the event query (see point 9 below). Also, if you want to link to a section in the Back-End, then enter '0' for the page ID.

Enter the page ID of the sys-folder where you want this event type to be stored in the Page PID field.

Create the query for this event. This is probably the most complicated thing of creating custom notifications. The extension uses plain SQL to find those events in the Database that should trigger the notifications. All fields that you want to use need to be selected. In our example, the query is quite straightforward:

SELECT uid, title, crdate

FROM tx_kcsermonmgr_sermons

Note, if you do not know SQL, you can:

• Use the phpMyAdmin extension, under the Query tab you can create your query from the tables present in the database.
• Use the Tools > DB Check > Search Whole Database > Advanced Query > Make Query to make your own SQL query
• Learn basic SQL (http://www.w3schools.com/sql/default.asp)

Enter the database field that determines the timing (whether the event should be selected or not) in the Time field box. In our case, we want only new sermons. That means that we will use the tx_kcsermonmgr_sermons.crdate field here. Only sermons that have a crdate (a unix date/time field, based on seconds) that is smaller then the start-time of our time-interval will be selected.

You can now do a first little test to see if what you entered so far works. The time interval for testing can be adjusted by entering for example 100 in the “For testing only! Select the number of days ago from which events should be shown. “ field. So this would be the setup screen for our first test:

and this would be the test result:

You can see that we added 13 sermons in the last 100 days. (some of them are really good! ;-))

There is however no text yet for the links that are going to be created, and there are no users yet who have signed on for this notification (not possible since it is still switched off).

So the next step is

Add the text for the links. You can use the results of the event query by using their fieldnames with ### markers. So, we would like to show the sermon name and the create date for example. Thus we would enter the following in the Link Text field (crdate and tstamp fields will automatically be transformed into a readable format).

###title### - ###crdate###

Now, the links can also be provided with a set of parameters at the end. In our case, we have to give the ID of the sermon. We can use also the ### markers here. Thus is our case, these would be the:

tx_kcsermonmgr_pi1[showUid]=###uid###

If you want to link to a section in the Back-End, you can use the following as parameter. This will point to the page with ID=0 (the root of the site).

/typo3/db_list.php?id=0

If the plugin is not a USER_INT, you will probably want to use the chash parameter as well. Make sure you set the “use chash” to yes. (note, this is not implemented yet!!)

We have to make sure we get the id's of those users who need to be modified. In our case, this is very straightforward, since this is an extra field (the “User Condition” field), we can use it to create even more advanced notifications. The field with the userid needs to be names “notifyuser”, using an alias AS. Thus, in our case we use:

SELECT uid AS notifyuser

FROM fe_users

WHERE deleted=0 AND disable=0

ORDER BY notifyuser

The notifyuser needs some more explanation. The “AS notifyuser” can be used both in the “User Condition” field (as in the example above) or in the “Event Query” field.

Suppose we would have a system in which there is a discussion forum. We could then offer the option that you get notified if somebody else makes a reply to one of your postings. This means, the 'notifyuser' would actually be part of the event query, since you only want those users to be notified who have received a reply to their posting. Such an SQL query could then look like the following:

SELECT tx_discussion_1.feuser AS notifyuser , tx_discussion_thread.name, tx_discussion.thread, tx_discussion_thread.category, tx_idea.uid, tx_idea.name AS ideaname

FROM tx_discussion, tx_discussion AS tx_discussion_1, tx_discussion_thread, tx_idea

WHERE tx_discussion_1.thread = tx_discussion_thread.uid AND tx_discussion.parent = tx_discussion_1.uid AND tx_idea.uid = tx_discussion.idea

Notice that we now used the “AS notifyuser” in the event query. (In this example, we needed to add a second copy of the discussion table because of the chilc-parent relation that determines if one of the postings was a reply to another posting or not).

The last step is to switch the notification on, and make sure at least one user has selected it. We can now test all the elements of our custom notification. In our case, the we have the following screen:

Which would result in the following if press the “Test this notification” button:

It works. You can even click on the created links to see if they take you to the right page.