AppSuite:Writing a notification area plugin (7.6.x)

How to: Write a plugin for the notification area.

1. Preparations

To start a new plugin for the notification area you have to add a new folder at apps.plugins/notifications/ . For this tutorial we will create plugins/notifications/tutorial/ .

Now add a new file to your folder and name it register.js . Now add the basic markup such as copyright define, use strict and so on. Our tutorial result should look similar to this.

CODE /**

* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',

   ['io.ox/core/extensions'], function (ext) {

   'use strict';
   
   //just to give something back
   return true;

}); CODE

Note: We need to use extensions so require the needed resources with ...['io.ox/core/extensions'], function (ext)... as seen above.

Your file is not loaded yet. TO do this we need to create a manifest file. Create a new file in your folder with the name manifest.json with the following code in it:

CODE { namespace: "io.ox/core/notifications" } CODE

For developing add the following code to src manifests.js CODE {

   namespace: ['io.ox/core/notifications'],
   path: 'plugins/notifications/tutorial/register'

} CODE

2. Registering our plugin

Now we need to register our plugin by extending the right extension point, which is io.ox/core/notifications/register. Give your plugin a unique id and indexnumber and a register function. Inside this register function we register our notification plugin at the controller and also giving it an id and our view, we create later on We do so by adding:

CODE //register our notification plugin ext.point('io.ox/core/notifications/register').extend({

   id: 'tutorial',//unique id
   index: 500, //unused index
   register: function (controller) {
       //give our plugin a name and send it to the controller together with our view
       var notifications = controller.get('io.ox/tutorial', NotificationsView);
   }

}); CODE

io.ox/tutorial is the id the controlelr should use to refer to our plugin and NotificationsView is the view we will create now to display it.

3. Creating the View

Since we use will use backbone to create our plugin it obviously needs a view. Call the variable like the one you gave to the controller to make it work. In our exsample the code to create the view looks like this.

CODE //the view of our plugin var NotificationsView = Backbone.View.extend({

   className: 'notifications',
   id: 'io-ox-notifications-tutorial',
       
   //events from our items
   events: {
   },

   //draws the plugin
   render: function () {
       return this;
   }

}); CODE

Note: Events and render function are empty at the moment, but we will fix this soon.

4. Adding the headline

Now we need to draw something. We could just put it in the render method but since we have the extension point architecture we will make use of it, to keep our actual render method cleaned up.

We start by creating an extension point we will use to draw our headline and create a container for our notifications, to put in later. Add this code to your views render method to create the point and invoke the draw method of its extensions.

CODE //build baton to wrap things up var baton = ext.Baton({ view: this }); //draw header and container by creating an extension point and invoke drawing on its extensions ext.point('io.ox/core/notifications/tutorial/header').invoke('draw', this.$el.empty(), baton); CODE

Note: Here we use our special baton objects to pass the data to the extension points. By using this.$el.empty() as a dom node to draw we ensure that we clean up properly before drawing.

Now extend the point with a simple draw method for our header and container. 'this' refers to our views dom node we draw in in the rendering method.

CODE //the header and container for the notification plugin ext.point('io.ox/core/notifications/tutorial/header').extend({

   draw: function (baton) {
       this.append(
           $('<legend class="section-title">').text('Hello World'),//header

$('

')//the container for our notifications

       );
   }

}); CODE

Congratulations the first steps are done. Time for some testing to see if we did it right.

5. First testing Now we want to see how it looks in the program. To do this add this line of code to your register method: CODE notifications.collection.reset(new Backbone.Model()); CODE This creates an empty notification model and adds it to our plugins collection. We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

When finished start your appsuite and login, add &customManifests=true to the url to load your plugin and reload the page.

Note: The notification area is loaded with a delay, so you have to wait a bit.

After its loaded you should see something like this:

PICTURE

Well done now we need to add some real notifications.

6. Listening for events

Normally a notification area listens for events of the app it is related to. For exsample the mail notifications, listen for events on from the mail api.

For this Tutorial we will just create a small dummy to create some Notifications for us and then trigger the proper event.

Our dummy looks like this:

CODE //simple helper to trigger some events //normally this is done by mailapi, taskapi, etc. var myEventTriggerer = {

       lookForItems: function () {
           //build some items and put them in an array
           var items = [{title: 'I am a notification', description: 'Hello world!'},
                        {title: 'I am a notification too', description: 'Hooray!'}];
           //trigger the event to add them
           $(myEventTriggerer).trigger('set-tutorial-notification', [items]);
       }
   };

CODE

This dummy creates an array with two objects containing our notifications data. Then it triggers an event on itself and passes the array as an argument.

Notifications are stored as backbone models in a collection of our view. This collection is available in the register method under notifications.collection. The controller looks for changes in this collection and triggers a redraw.

To do this we create three simple functions for adding, removing and resetting notification models in our collection. Remove our testing line (notifications.collection.reset(new Backbone.Model());)from the register method and add our new functions:

CODE

CODE