Open-Xchange - User contributions [en]

AppSuite:Writing a portal plugin

2016-07-20T09:18:43Z

D.haus: /* Where and how to start */

{{Stability-stable}}

<div class="title">Writing a portal plugin</div>

'''Abstract:''' This articles covers how to write a plugin that shows on the portal page. A portal plugin always gives a short overview on a piece of information (the so-called 'tile'). It can link a longer view that is opened when the tile is clicked, this we call the side pop-up. The side pop-up is optional.

== Where and how to start ==
Portal plugins are collected in the folder ui/apps/plugins/portal. Start your new plugin there: Create a folder and in this folder, create two files: <tt>register.js</tt> (where everything happens) and <tt>manifest.json</tt>

== The simplest portal plugin: An advertisement ==
The simplest portal plugin comes without a side pop-up and shows static content on its tile. Two uses for this would be presenting an advertisement (or your daily creed, an often used check list....) or showing a link list (for example to other parts of an company's intranet that are not integrated into the AppSuite (yet)). We will now build an advertisement, which is just a slogan.

The beauty of this is that we do not have any dependencies (for example needing another module like the file store), so the content of our manifest.json is rather simple:

<pre class="language-javascript">
{
"namespace": "portal"
}
</pre>

Nothing to see here. We say we belong in the portal namespace and that's it. We do not need to define any dependencies on other modules.

Our register.js is only slightly longer:

<pre class="language-javascript">
define('plugins/portal/myAd/register', ['io.ox/core/extensions'], function (ext) {

'use strict';

ext.point('io.ox/portal/widget').extend({
id: 'myAd'
});

ext.point('io.ox/portal/widget/myAd').extend({
preview: function () {
var content = $('<div class="content">')
.text('Buy stuff. It's like solid happiness.');
this.append(content);
}
});

ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd'
});
});
</pre>

Please keep in mind, that the first parameter of define()-method refers to your app's path. According to the code above <tt>plugins/portal/myAd/</tt> should contain the upper displayed <tt>register.js</tt>.

So what do we have here? We have two extension points:

The first one is for the ad itself, ''io.ox/portal/widget/myAd''. This one contains a single method that we implement, ''preview''. ''Preview'' is responsible for the tile you see whenever you look at your portal. Technically, ''this'' contains the container to which you can attach your content. If you are brave, you can do changes on the container, too. But that is not needed for now.

The second is less obvious: It creates an option in the settings area for the portal (the one you reach by "customize this page"). There you will have to enable your setting (yes, this is a very polite advertisement). The ''title'' is what is shown as the name of your plugin (so chose a readable one), the type references the one you used in the definition. '''Attention:''' the ''type'' attribute has to be identical to the module name in the extension point. In this case "io.ox/portal/widget/myAd/settings" has the module name ''myAd'' and the referenced ''type'' is identical: ''myAd''. Also make sure, the type doesn’t contain any "/" or "-" characters. You are save if you limit the characters used to numbers, alphabetical characters and "_".

== A more typical portal plugin ==
A typical portal plugin uses the tile to display a short summary or teaser of its contents and uses a side-popup to show the whole content.

The manifest.json can stay the same, but the register.js needs to do a little more now:
<pre class="language-javascript">
define("plugins/portal/myAd/register", ['io.ox/core/extensions'], function (ext) {

"use strict";

ext.point('io.ox/portal/widget').extend({
id: 'myAd'
});

ext.point('io.ox/portal/widget/myAd').extend({
title: "My Advertisement",

load: function (baton) {
var def = $.Deferred();
def.resolve("It's like solid happiness.").done(function (data) {
baton.data = {
teaser: 'Buy stuff',
fullText: 'Buy stuff. It is like solid happiness.'
};
});
return def;
},

preview: function (baton) {
var content = $('<div class="content pointer">')
.text(baton.data.teaser);
this.append(content);
},

draw: function (baton) {
var content = $('<div class="myAdd">')
.text(baton.data.fullText);
this.append(content);
}
});

ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd'
});
});
</pre>

What happened here? We have gained two new methods and all three methods seems to be passing something called ''baton'' around. The baton is actually just that - something to pass around. The baton carries data between different methods.

=== Order of execution ===
How do the three functions interact? When a plugin is supposed to be rendered, the first method to be called is "load". Load usually does some (asynchronous) loading of data, be it from the file store or some external source. Meanwhile, the empty tile (well, if you give it a title, that is already rendered, so it is not completely naked) is rendered on the portal page.

When the loading is done, it is consensus that the loaded data is stored as baton.data. Then ''preview'' is called and usually does something with the data in the baton. It then renders its content, which is appended to the tile.

When the tile is clicked on, a side popup is drawn (which, again, is nearly naked). Meanwhile, the function ''draw'' is called. As with ''preview'', ''draw'' usually uses the data from the baton.

The given example is a stereotypical use case: First, ''load'' gets the data. Then ''preview'' renders a short version of the data on the tile. When clicked, ''draw'' renders a longer, more detailed view of that data on a side popup.

=== Notes ===
If you look closely, you will find that the class of the container on the tile has changed to "content pointer". This is relevant, as this makes the whole tile clickable (there is a delegate for '.item .content.pointer' that does that). This is just a comfortable way to do so, you don't have to use it. If you want to have different sections of your tile to execute different actions, you will have to implement handlers yourself.

This covers the most common uses of portal widgets. But if you are looking for more, we got more:

== Advanced plugins ==

=== Initialize ===
Sometimes you want to do things even before loading. Maybe pre-populate the baton. For this we have the method ''initialize'':
<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
initialize: function (baton) {
baton.default = "Defaultiness";
}
});
</pre>

=== Things that require a setup ===
There are some external sources that need some kind of set up before they can be used. Services that need an OAuth authorization, for example. For this, you need to implement two more functions, named ''requiresSetup'' and ''performSetup''. The former determines whether it is necessary to run a setup, the latter starts the setup process if the former returns ''true''.

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
requiresSetup: function () {
return isMissingAnAccount();
},
performSetup: function () {
createANewAccount();
}
});
</pre>

=== Unique ===
Talking about things with OAuth... a lot of data sources are unique - people only have one twitter account. To make sure the widget can only be created once, set it to ''unique'':

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd',
unique: true
});
</pre>

=== Error handling ===
Occasionally, it might happen that there is an error when loading an external source. Should this occur and ''load'' (which, as you know, uses a $.Deferred) call ''fail'' instead of ''done'', the function ''error'' is called. This allows you to handle this case differently.

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
error: function (error) {
$(this).empty().append(
$('<div>').text('An error occurred.');
);
}
});
</pre>
This is not a catch-all solution, though: If you do not use ''load'' to load that data, but do it in either ''preview'' or ''draw'', this will not work. It will also not work if the service that is called wraps the error nicely in a valid response.

=== Configurable settings ===
Sometimes you want to fine-tune your widget. The place to do so is in the settings. If you mark your settings ''editable'', your settings gets a little 'edit' link and you get to define a function that is called. This function is given both the model and the view so you can build your own settings pane:

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd/settings').extend({
editable: true,
edit: function (model, view) {
...
}
});
</pre>

== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].

=== Checklist: Paths, names and Types ===
Remember:
* The path of the extension point must be <tt>io.ox/portal/widget/$name</tt>
* You have to have settings!
* The path of the settings extension point must be <tt>io.ox/portal/widget/$name/settings</tt>
* The <tt>type</tt> of the settings extension point must match the <tt>$name</tt> of the portal plugin!
* go all lowercase with your widget name, versions <7.6 sometimes had issues with that

=== My shiny new widget does not show up in the widget selection ===
Yes. That is surprising, isn't it? There is a small peculiarity about manifests: They may be in the frontend, but the backend needs to know about them. Luckily, that is done automatically on system startup. You probably did not restart your server, didn't you?

If you cannot simply restart your server, but you want to test (good!), you can hack your widget into the list of loaded widgets. Open the <tt>io.ox/portal/widgets.js</tt> and look for the variable DEV_PLUGINS. Add the name of your plugin in there and re-build the UI.

== Finishing touches ==
Now that you have learned all there is about portal plugins, it is time to clean up. Check whether your plugin only [[AppSuite:UI manifests explained | works when a certain module is active]]. Also, maybe we can interest you in [[AppSuite:i18n | preparing the text for readers from other countries]]? There is also an article on [[AppSuite:Configuring_portal_plugins|plugins only showing under certain circumstances]].

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Developer]]

AppSuite:Writing a portal plugin

2016-07-20T09:18:28Z

D.haus: /* Where and how to start */

{{Stability-stable}}

<div class="title">Writing a portal plugin</div>

'''Abstract:''' This articles covers how to write a plugin that shows on the portal page. A portal plugin always gives a short overview on a piece of information (the so-called 'tile'). It can link a longer view that is opened when the tile is clicked, this we call the side pop-up. The side pop-up is optional.

== Where and how to start ==
Poral plugins are collected in the folder ui/apps/plugins/portal. Start your new plugin there: Create a folder and in this folder, create two files: <tt>register.js</tt> (where everything happens) and <tt>manifest.json</tt>

== The simplest portal plugin: An advertisement ==
The simplest portal plugin comes without a side pop-up and shows static content on its tile. Two uses for this would be presenting an advertisement (or your daily creed, an often used check list....) or showing a link list (for example to other parts of an company's intranet that are not integrated into the AppSuite (yet)). We will now build an advertisement, which is just a slogan.

The beauty of this is that we do not have any dependencies (for example needing another module like the file store), so the content of our manifest.json is rather simple:

<pre class="language-javascript">
{
"namespace": "portal"
}
</pre>

Nothing to see here. We say we belong in the portal namespace and that's it. We do not need to define any dependencies on other modules.

Our register.js is only slightly longer:

<pre class="language-javascript">
define('plugins/portal/myAd/register', ['io.ox/core/extensions'], function (ext) {

'use strict';

ext.point('io.ox/portal/widget').extend({
id: 'myAd'
});

ext.point('io.ox/portal/widget/myAd').extend({
preview: function () {
var content = $('<div class="content">')
.text('Buy stuff. It's like solid happiness.');
this.append(content);
}
});

ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd'
});
});
</pre>

Please keep in mind, that the first parameter of define()-method refers to your app's path. According to the code above <tt>plugins/portal/myAd/</tt> should contain the upper displayed <tt>register.js</tt>.

So what do we have here? We have two extension points:

The first one is for the ad itself, ''io.ox/portal/widget/myAd''. This one contains a single method that we implement, ''preview''. ''Preview'' is responsible for the tile you see whenever you look at your portal. Technically, ''this'' contains the container to which you can attach your content. If you are brave, you can do changes on the container, too. But that is not needed for now.

The second is less obvious: It creates an option in the settings area for the portal (the one you reach by "customize this page"). There you will have to enable your setting (yes, this is a very polite advertisement). The ''title'' is what is shown as the name of your plugin (so chose a readable one), the type references the one you used in the definition. '''Attention:''' the ''type'' attribute has to be identical to the module name in the extension point. In this case "io.ox/portal/widget/myAd/settings" has the module name ''myAd'' and the referenced ''type'' is identical: ''myAd''. Also make sure, the type doesn’t contain any "/" or "-" characters. You are save if you limit the characters used to numbers, alphabetical characters and "_".

== A more typical portal plugin ==
A typical portal plugin uses the tile to display a short summary or teaser of its contents and uses a side-popup to show the whole content.

The manifest.json can stay the same, but the register.js needs to do a little more now:
<pre class="language-javascript">
define("plugins/portal/myAd/register", ['io.ox/core/extensions'], function (ext) {

"use strict";

ext.point('io.ox/portal/widget').extend({
id: 'myAd'
});

ext.point('io.ox/portal/widget/myAd').extend({
title: "My Advertisement",

load: function (baton) {
var def = $.Deferred();
def.resolve("It's like solid happiness.").done(function (data) {
baton.data = {
teaser: 'Buy stuff',
fullText: 'Buy stuff. It is like solid happiness.'
};
});
return def;
},

preview: function (baton) {
var content = $('<div class="content pointer">')
.text(baton.data.teaser);
this.append(content);
},

draw: function (baton) {
var content = $('<div class="myAdd">')
.text(baton.data.fullText);
this.append(content);
}
});

ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd'
});
});
</pre>

What happened here? We have gained two new methods and all three methods seems to be passing something called ''baton'' around. The baton is actually just that - something to pass around. The baton carries data between different methods.

=== Order of execution ===
How do the three functions interact? When a plugin is supposed to be rendered, the first method to be called is "load". Load usually does some (asynchronous) loading of data, be it from the file store or some external source. Meanwhile, the empty tile (well, if you give it a title, that is already rendered, so it is not completely naked) is rendered on the portal page.

When the loading is done, it is consensus that the loaded data is stored as baton.data. Then ''preview'' is called and usually does something with the data in the baton. It then renders its content, which is appended to the tile.

When the tile is clicked on, a side popup is drawn (which, again, is nearly naked). Meanwhile, the function ''draw'' is called. As with ''preview'', ''draw'' usually uses the data from the baton.

The given example is a stereotypical use case: First, ''load'' gets the data. Then ''preview'' renders a short version of the data on the tile. When clicked, ''draw'' renders a longer, more detailed view of that data on a side popup.

=== Notes ===
If you look closely, you will find that the class of the container on the tile has changed to "content pointer". This is relevant, as this makes the whole tile clickable (there is a delegate for '.item .content.pointer' that does that). This is just a comfortable way to do so, you don't have to use it. If you want to have different sections of your tile to execute different actions, you will have to implement handlers yourself.

This covers the most common uses of portal widgets. But if you are looking for more, we got more:

== Advanced plugins ==

=== Initialize ===
Sometimes you want to do things even before loading. Maybe pre-populate the baton. For this we have the method ''initialize'':
<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
initialize: function (baton) {
baton.default = "Defaultiness";
}
});
</pre>

=== Things that require a setup ===
There are some external sources that need some kind of set up before they can be used. Services that need an OAuth authorization, for example. For this, you need to implement two more functions, named ''requiresSetup'' and ''performSetup''. The former determines whether it is necessary to run a setup, the latter starts the setup process if the former returns ''true''.

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
requiresSetup: function () {
return isMissingAnAccount();
},
performSetup: function () {
createANewAccount();
}
});
</pre>

=== Unique ===
Talking about things with OAuth... a lot of data sources are unique - people only have one twitter account. To make sure the widget can only be created once, set it to ''unique'':

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd/settings').extend({
title: 'My advertisement',
type: 'myAd',
unique: true
});
</pre>

=== Error handling ===
Occasionally, it might happen that there is an error when loading an external source. Should this occur and ''load'' (which, as you know, uses a $.Deferred) call ''fail'' instead of ''done'', the function ''error'' is called. This allows you to handle this case differently.

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd').extend({
...
error: function (error) {
$(this).empty().append(
$('<div>').text('An error occurred.');
);
}
});
</pre>
This is not a catch-all solution, though: If you do not use ''load'' to load that data, but do it in either ''preview'' or ''draw'', this will not work. It will also not work if the service that is called wraps the error nicely in a valid response.

=== Configurable settings ===
Sometimes you want to fine-tune your widget. The place to do so is in the settings. If you mark your settings ''editable'', your settings gets a little 'edit' link and you get to define a function that is called. This function is given both the model and the view so you can build your own settings pane:

<pre class="language-javascript">
ext.point('io.ox/portal/widget/myAd/settings').extend({
editable: true,
edit: function (model, view) {
...
}
});
</pre>

== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].

=== Checklist: Paths, names and Types ===
Remember:
* The path of the extension point must be <tt>io.ox/portal/widget/$name</tt>
* You have to have settings!
* The path of the settings extension point must be <tt>io.ox/portal/widget/$name/settings</tt>
* The <tt>type</tt> of the settings extension point must match the <tt>$name</tt> of the portal plugin!
* go all lowercase with your widget name, versions <7.6 sometimes had issues with that

=== My shiny new widget does not show up in the widget selection ===
Yes. That is surprising, isn't it? There is a small peculiarity about manifests: They may be in the frontend, but the backend needs to know about them. Luckily, that is done automatically on system startup. You probably did not restart your server, didn't you?

If you cannot simply restart your server, but you want to test (good!), you can hack your widget into the list of loaded widgets. Open the <tt>io.ox/portal/widgets.js</tt> and look for the variable DEV_PLUGINS. Add the name of your plugin in there and re-build the UI.

== Finishing touches ==
Now that you have learned all there is about portal plugins, it is time to clean up. Check whether your plugin only [[AppSuite:UI manifests explained | works when a certain module is active]]. Also, maybe we can interest you in [[AppSuite:i18n | preparing the text for readers from other countries]]? There is also an article on [[AppSuite:Configuring_portal_plugins|plugins only showing under certain circumstances]].

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Developer]]

AppSuite:Writing a notification area plugin

2015-09-11T07:43:54Z

D.haus: /* Adding desktop notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The API object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the API triggers when notifications should be added. The provided data is used by the addNotifications function.
**remove: A string that contains the events the API triggers when notifications should be removed. The provided data is used by the removeNotifications function.
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function.
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a matching list function for this. Default is 'false'.

This is designed to fit our core APIs like mail or calendar, but custom APIs should work as well.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

Usally you would have the API in a separate file but in our example we keep it with the other code for simplicity. Also note that this API just works as a dummy, normally you would use server requests etc to get your data, but depending on the design of your API this may vary.

In our example the reset function is now handled by the API. It throws a reset event that we also added to the options of our subview, so that it listens to it properly. We also use the get function here to get additional data. If your API does not need additional data and should only use the initial data provided when the notification was created, just set the ''fullModel'' option to true.
Note that the API extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the API (''fullModel'' = false), or the data from the collection is used (''fullModel'' = true). To get the right data the DOM node of the notification needs a ''data-cid'' attribute that contains the id for either API or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns ''one'' jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are multiple new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. Default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:43:25Z

D.haus: /* Adding desktop notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The API object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the API triggers when notifications should be added. The provided data is used by the addNotifications function.
**remove: A string that contains the events the API triggers when notifications should be removed. The provided data is used by the removeNotifications function.
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function.
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a matching list function for this. Default is 'false'.

This is designed to fit our core APIs like mail or calendar, but custom APIs should work as well.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

Usally you would have the API in a separate file but in our example we keep it with the other code for simplicity. Also note that this API just works as a dummy, normally you would use server requests etc to get your data, but depending on the design of your API this may vary.

In our example the reset function is now handled by the API. It throws a reset event that we also added to the options of our subview, so that it listens to it properly. We also use the get function here to get additional data. If your API does not need additional data and should only use the initial data provided when the notification was created, just set the ''fullModel'' option to true.
Note that the API extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the API (''fullModel'' = false), or the data from the collection is used (''fullModel'' = true). To get the right data the DOM node of the notification needs a ''data-cid'' attribute that contains the id for either API or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns ''one'' jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are multiple new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:42:42Z

D.haus: /* Adding Detailviews */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The API object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the API triggers when notifications should be added. The provided data is used by the addNotifications function.
**remove: A string that contains the events the API triggers when notifications should be removed. The provided data is used by the removeNotifications function.
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function.
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a matching list function for this. Default is 'false'.

This is designed to fit our core APIs like mail or calendar, but custom APIs should work as well.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

Usally you would have the API in a separate file but in our example we keep it with the other code for simplicity. Also note that this API just works as a dummy, normally you would use server requests etc to get your data, but depending on the design of your API this may vary.

In our example the reset function is now handled by the API. It throws a reset event that we also added to the options of our subview, so that it listens to it properly. We also use the get function here to get additional data. If your API does not need additional data and should only use the initial data provided when the notification was created, just set the ''fullModel'' option to true.
Note that the API extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the API (''fullModel'' = false), or the data from the collection is used (''fullModel'' = true). To get the right data the DOM node of the notification needs a ''data-cid'' attribute that contains the id for either API or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns ''one'' jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:39:53Z

D.haus: /* Using APIs */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The API object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the API triggers when notifications should be added. The provided data is used by the addNotifications function.
**remove: A string that contains the events the API triggers when notifications should be removed. The provided data is used by the removeNotifications function.
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function.
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a matching list function for this. Default is 'false'.

This is designed to fit our core APIs like mail or calendar, but custom APIs should work as well.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

Usally you would have the API in a separate file but in our example we keep it with the other code for simplicity. Also note that this API just works as a dummy, normally you would use server requests etc to get your data, but depending on the design of your API this may vary.

In our example the reset function is now handled by the API. It throws a reset event that we also added to the options of our subview, so that it listens to it properly. We also use the get function here to get additional data. If your API does not need additional data and should only use the initial data provided when the notification was created, just set the ''fullModel'' option to true.
Note that the API extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:31:21Z

D.haus: /* Adding and removing notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:31:07Z

D.haus: /* Adding and removing notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. Here we have a new text attribute in our notification models that we display. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:27:43Z

D.haus: /* Adding and removing notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications.
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:19:48Z

D.haus: /* Adding a manifest */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

To load our code we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:19:11Z

D.haus: /* Basic Notification */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add a notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:18:56Z

D.haus: /* Basic Notification */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our subview and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:18:13Z

D.haus: /* Basic Notification */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register'' and uses ''io.ox/core/notifications/subview'' to create the subview needed for our plugin.

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

AppSuite:Writing a notification area plugin

2015-09-11T07:15:50Z

D.haus: /* Basic Notification */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code just adds a simple hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

File:Notification780 tutorial.zip

2015-09-10T15:09:06Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T15:07:36Z

D.haus: /* Adding Detailviews */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

==Adding desktop notifications==

Finally you can add desktop notifications. This notifications are shown by the browser, if the appsuite is minimized or the tab is not active at the moment. The subview can show individual notifications, if there is only one new item or a more generic notification, if there are more new items.

To use it you can use the following options:
*desktopNotificationSupport: If you want to use desktop notifications this has to be true. default is ''true''
*genericDesktopNotification: This is the desktop notification shown when there are multiple new notifications or if there is no specific one. Accepts all attributes ''io.ox/core/desktopNotifications.show'' accepts. Default is:

<pre class="language-javascript">
{
title: gt('New notifications'),
body: gt('You\'ve got new notifications'),
icon: ''
}
</pre>

*specificDesktopNotification: Function that is called when there is only one new notification. The notifications data is provided as a model. Default is null.

Adding a specific notification to our example would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
},
specificDesktopNotification: function (model) {
return {
title: 'New tutorial notification',
body: model.get('text'),
icon: ''
};
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

==Download==
You can download the examplecode here.

[[File: Notification780_tutorial.zip]].

File:Detailview.png

2015-09-10T14:50:46Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T14:50:32Z

D.haus: /* Adding and removing notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

==Adding Detailviews==

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

We use a simple object with a draw function. It's important that this function returns one jquery node.
Also note that we added a data-cid attribute, so the API can lookup the correct item.

In the browser it looks like this:

[[Image: detailview.png]]

AppSuite:Writing a notification area plugin

2015-09-10T14:47:56Z

D.haus: /* Adding Detailviews */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

===Adding Detailviews===

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

AppSuite:Writing a notification area plugin

2015-09-10T14:47:47Z

D.haus: /* Using APIs */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

===Adding Detailviews===

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

AppSuite:Writing a notification area plugin

2015-09-10T14:47:31Z

D.haus: /* Adding and removing notifications */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre class="language-javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

===Adding Detailviews===

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

AppSuite:Writing a notification area plugin

2015-09-10T14:47:20Z

D.haus: /* Expanding our Plugin */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre language="javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

===Adding Detailviews===

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

AppSuite:Writing a notification area plugin

2015-09-10T14:46:27Z

D.haus: /* Using APIs */

<div class="title">Writing a plugin for the notification area</div>

'''Abstract:''' This article is a step by step tutorial to build your own notification plugin.
These plugins can be used for various purposes, for example reminding the user of something or showing him new invitations.

__TOC__

==Basic Notification==

First let's start with showing the most basic notification plugin you can write.
Create a file named ''register.js'' at ''plugins/notifications/tutorial''.

This code doesn't have api suppport or other things but adds a hello world notification:

<pre class="language-javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append( $('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item'
}
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});

</pre>

This code extends two extension points: ''io.ox/core/notifications/tutorial/item'' and ''io.ox/core/notifications/register''

We use ''io.ox/core/notifications/tutorial/item'' to draw our notification items. Here it's a simple ''hello world'' text.

''io.ox/core/notifications/register'' is used by the notification area to load the different plugins. Those plugins are implemented as subviews of the main notification area. The index determines the order of the different subviews.
We define some options for our view here:

* id: the internalId for our subview
* title: the text in the header of our subview
* extensionPoints: here we tell the subview which extensionpoints to use when drawing our notifications. For now we only use ''io.ox/core/notifications/tutorial/item'' to draw our items.

More options will be explained later on.

Now we create our view and add notification to it:
<pre class="language-json">
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
</pre>

===Adding a manifest===

Now we need to add a ''manifest.json'' file at ''plugins/notifications/tutorial'' with the following contents:

<pre class="language-json">
{
"namespace": "io.ox/core/notifications",
"requires": ""
}
</pre>

This manifest makes sure our code is loaded. You can also define capabilities like ''webmail'' here, if your notifications require specific capabilities to be enabled. They only show up if a user has these capabilities.

===Testing our notification===

Now it's time to test our notification. Build the UI and add ''&customManifests=true'' to the url, because our manifest is only present locally.

After reloading you should see something like this:

[[Image: basicNotification.png]]

==Expanding our Plugin==

We can add more functionality to our plugin by using the options when creating the subview.
Here are some more:

*showHideAllButton: Is used to show a ''hide all'' button for your subview. This button hides all current notifications of your subview. Default is ''false''
*hideAllLabel: Is the aria-label for the ''hide all'' button that is used by screen readers. Default is ''empty string''
*showHideSingleButton: Is used to show a ''hide'' button for your notifications. This button hides a single notification of your subview. Default is ''true''
*max: The maximum number of displayed notifications in this subview. The actual collection may contain more. Setting this to ''null'' will show all notifications. Default is ''10''
*autoOpen: Used to open the notification area, if there is a new notification for your plugin. You may want to tie this to a user setting. Default is ''false''
*extensionPoints: This is an object where you can define extension points used when drawing your subview. Possible points are:
**main: The main extension point. If you overwrite this you can draw the subview completely by hand. If you keep the default value, this extension point invokes the header, item and footer extension points for you.
**header: The extension point for your subview header. The default extension point uses the supplied title attribute and draws the hideall button if enabled.
**item: The extension point for a single notifications. This extension point has no default value and must be provided by the plugin when creating the subview. In our example this was ''io.ox/core/notifications/tutorial/item''.
**footer: The extension point for the footer. If your subview should have a footer you can provide an extension point for this. There is no default extension point and it's entirely optional.

Let's add a footer to our plugin and make it autopen. The code looks like this:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview'
], function (ext, Subview) {

'use strict';

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function () {
this.append($('<button class="btn">').text('click me')
.on('click', function () {
alert('footer button was clicked');
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function () {
this.append($('<span>').text('hello world'));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true
},
subview = new Subview(options);

subview.resetNotifications({ id: 'myNotification1' });
}
});

return true;
});
</pre>

And it should look like this:

[[Image: notificationWithFooter.png]]

==Adding and removing notifications==

Now we need to talk about how notifications are added and removed. Our subview has a backbone collection which stores all it's notifications. The notifications need an id so the collection can avoid duplicates and handle hiding correctly. Our example notifications id was ''myNotification1''.
This collection can be changed by using 3 methods:

*addNotifications: Adds notifications to the collection. Only adds notifications which have a new id. Has 2 parameters:
**items: Is a single object or an array of objects to be added as new notifications
**silent: Is a boolean that can be set to true if the new notifications should be added silently. This prevents immediate redrawing.
*removeNotifications: Removes notifications from the collection. Has items and silent parameter, like addNotifications.
*resetNotifications: Resets the collection. This throws away all notifications in the collection and fills it with the provided new ones. Can also be used to clear the collection, when an empty array is provided. Again has items and silent parameter, like addNotifications.

Let's expand our example by adding buttons to the footer to add notifications and reset them. Let's also add a button to remove a notification and show some data in our notifications.

The code looks like this:

<pre language="javascript">

var counter = 0;

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
counter = 0;
baton.view.resetNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter, text: 'I am notification number ' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

</pre>

The extension points are provided a baton which has the data of the view and the model. We use a simple counter here to create unique ids.

You should see Something like this in your browser:

[[Image: notificationAddRemove.png]]

===Using APIs===

Instead of manually adding or reseting notifications. The subview is also capable of handling APIs that meet certain conditions.

To use APIs the subview provides the following options:

*api: The api object that should be used by this subview. default is ''null'',
*apiEvents: An object where you can define events that the subview should listen to:
**add: A string that contains the events the api triggers when notifications should be added. The provided data is used by the addNotifications function;
**remove: A string that contains the events the api triggers when notifications should be removed. The provided data is used by the removeNotifications function;
**reset: A string that contains the events the api triggers when notifications should be reseted. The provided data is used by the resetNotifications function;
*fullModel: Some notifications have limited data and the full data must be requested from the server (our notifications usually only have id and folder). To do this the API must provide a get function that returns the full model data as the result of a deferred object. The model attributes are provided to the API.get function. If fullModel is set to true, there is no API call to get the full data as the model already has it. Default is ''false'',
*useListRequest: If data should be requested by the server, it can be done as a list request instead of multiple get requests. The API must have a maching list function for this. Default is 'false'.

Let's change our example to use a small api:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

The reset function is now handled by the api. We also use the get function here to get additional data.
Note that the api extends ''io.ox/core/event''. This is needed so the event listeners function properly.

===Adding Detailviews===

Most notifications provide detailviews. Those views open when you click on a notification. For example a reminder shows the calendar appointment or task.

You can add a detailview by adding the detailview option. This can be a string for our require module, like ''io.ox/calendar/view-detail''. Or it can be a normal object. Important is that it provides either a view constructor or a draw function. The data is provided either by the api (fullModel = false), or the data from the collection is used (fullModel = true). To get the right data the domnode of the notification needs a ''data-cid'' attribute that contains the id for either api or collection.

In our code this would look like this:

<pre language="javascript">
define('plugins/notifications/tutorial/register', [
'io.ox/core/extensions',
'io.ox/core/notifications/subview',
'io.ox/core/event'
], function (ext, Subview, Events) {

'use strict';

var counter = 0;

var api = {
get: function (data) {
var result = {
id: data.id,
text: 'I am ' + data.id
};
return $.Deferred().resolve(result);
},
reset: function () {
counter = 0;
api.trigger('reset', { id: 'myNotification' + counter });
counter++;
}
};

Events.extend(api);

ext.point('io.ox/core/notifications/tutorial/footer').extend({
draw: function (baton) {
this.append($('<button class="btn">').text('reset notifications')
.on('click', function () {
api.reset();
}),
$('<button class="btn">').text('add notifications')
.on('click', function () {
baton.view.addNotifications({ id: 'myNotification' + counter });
counter++;
}));
}
});

ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
var cid = _.cid(baton.model.attributes);

this.attr('data-cid', cid).append($('<div>').text(baton.model.get('text')),
$('<button class="btn">').text('remove notification').on('click', function () {
baton.view.removeNotifications(baton.model);
}));
}
});

ext.point('io.ox/core/notifications/register').extend({
id: 'tutorialplugin',
index: 1000,
register: function () {
var options = {
id: 'io.ox/tutorialplugin',
title: 'Test Notifications',
extensionPoints: {
item: 'io.ox/core/notifications/tutorial/item',
footer: 'io.ox/core/notifications/tutorial/footer'
},
autoOpen: true,
api: api,
apiEvents: {
reset: 'reset'
},
detailview: {
draw: function (obj) {
var node = $('<div>').append($('<div>').text('i am the tutorial detailview'),
$('<div>').text(obj.data.text));
return node;
}
}
};
new Subview(options);

api.reset();
}
});

return true;
});
</pre>

AppSuite:Writing a notification area plugin

2015-09-10T14:21:48Z

D.haus: /* Using APIs */

AppSuite:Writing a notification area plugin

2015-09-10T13:06:56Z

D.haus: /* Using APIs */

AppSuite:Writing a notification area plugin

2015-09-10T12:50:56Z

D.haus: /* Expanding our Plugin */

AppSuite:Writing a notification area plugin

2015-09-10T12:50:03Z

D.haus: /* Adding and removing notifications */

File:NotificationAddRemove.png

2015-09-10T12:44:03Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T12:43:53Z

D.haus: /* Adding and removing notifications */

AppSuite:Writing a notification area plugin

2015-09-10T12:43:02Z

D.haus: /* Adding and removing notifications */

AppSuite:Writing a notification area plugin

2015-09-10T12:42:08Z

D.haus: /* Adding and removing notifications */

AppSuite:Writing a notification area plugin

2015-09-10T11:58:12Z

D.haus: /* Expanding our Plugin */

File:NotificationWithFooter.png

2015-09-10T11:39:21Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T11:39:10Z

D.haus: /* Expanding our Plugin */

AppSuite:Writing a notification area plugin

2015-09-10T11:38:41Z

D.haus: /* Expanding our Plugin */

AppSuite:Writing a notification area plugin

2015-09-10T11:23:10Z

D.haus: /* Expanding our Plugin */

AppSuite:Writing a notification area plugin

2015-09-10T10:28:25Z

D.haus: /* Expanding our Plugin */

AppSuite:Writing a notification area plugin

2015-09-10T10:27:37Z

D.haus: /* Testing our notification */

AppSuite:Writing a notification area plugin

2015-09-10T09:58:31Z

D.haus: /* Testing our notification */

AppSuite:Writing a notification area plugin

2015-09-10T09:57:55Z

D.haus: /* Basic Notification */

AppSuite:Writing a notification area plugin

2015-09-10T09:42:01Z

D.haus: /* Basic Notification */

File:BasicNotification.png

2015-09-10T09:41:18Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T09:13:33Z

D.haus: /* Basic Notification */

AppSuite:Writing a notification area plugin

2015-09-10T09:12:17Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T09:04:47Z

D.haus: /* Basic Notification */

AppSuite:Writing a notification area plugin

2015-09-10T09:03:47Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T09:01:04Z

D.haus:

AppSuite:Writing a notification area plugin

2015-09-10T08:58:51Z

D.haus:

AppSuite:Theming

2014-04-11T15:13:43Z

D.haus: /* Variables */

{{Stability-experimental}}

<div class="title">Theming</div>

'''Abstract.''' In this article, you can learn how to create customized themes and use them to change the look of you appsuite installation.
__TOC__
== LESS.JS ==
Appsuite used LESS as dynamic stylesheet language. LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions.

Please read [http://lesscss.org/#docs LESS.JS] documentation first.

=== Using less.js ===
If your theme depends on less.js, you will need one more step to make it work. Why? To accelerate the login, compilation of LessCSS files was moved from the login process in the browser to the installation process on the backend.

Backend packages for themes and any apps which ship .less files require the following changes:

1. Add "skipLess=1" to the build command in *.spec and in debian/rules:
sh /opt/open-xchange-appsuite-dev/bin/build-appsuite app skipLess=1
2. Add %post and %postun sections to *.spec:
%post
if [ "$1" = 1 ]; then
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE
fi
%postun
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE

For multiple binary packages, the %post and %postun sections should apply only to backend packages
which contain .less files.

3. Add debian/postinst and debian/postrm containing the same content:
#!/bin/sh
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE

For multiple binary packages, the postinst and postrm files should apply only to backend packages which contain .less files.

Note: Since 7.2.1, LessCSS files must have the file extension .less to be usable with the 'less' RequireJS plugin (module dependencies of the form 'less!filename.less'). Previously we were more lenient and dealt with .css, too.

== File structure ==
A theme basically consists of two files located in <code>apps/themes/<var>THEME_ID</var>/</code>. These files are described in this and the following sections.

<code><var>THEME_ID</var></code> is a unique identifier for your theme, which is not visible to users. By convention, it is best derived from a domain name you control, e.g. <code>com.example.prettytheme</code>.

=== definitions.less ===
This file can be used to override variables described in the "Variables" section of this article.

=== style.less ===
This file can be used to define any CSS you like. Before doing this, check, if there really is no variable that can be used to achieve the same thing.

=== Referencing paths ===
Since 7.2.1, all URLs are relative to the source .less file in which they are contained. This means that unless a theme changes an image it does not need to include that image anymore.

Old themes must be updated if they change an image from the default theme: All styles from the default theme which refer to a changed image must be overwritten in the custom theme. This way the URLs resolve to the new image.

== Variables ==

Naming of the variables should be straight forward. Variables containing the word ''Background'' will always refer to the background color. Variables containing ''Color'' will refer to the foreground color of an element, like color of a font. ''Hover'' in most cases means "hovered" elements. ''Selected'' relates to the currently selected item. Elements that are supposed to catch the users eye can use the ''Highlight'' class and the variable contains this word.

Variables are defined in variables.less from twitter-bootstrap and our default definitions.less. Variables that are defined in definitions.less always override variables from bootstrap's variables.less

=== Basic ===

==== Font ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @font-family-sans-serif || @sansFontFamily || "Helvetica Neue", Helvetica, Arial, sans-serif
|-
| @font-family-serif || @serifFontFamily || Georgia, "Times New Roman", Times, serif
|-
| @font-family-monospace || @monoFontFamily || Monaco, Menlo, Consolas, "Courier New", monospace
|-
| @font-size-base || @baseFontSize || 14px
|-
| || @baseFontFamily ||
|-
| @line-height-base || @baseLineHeight || 1.428571429; // 20/14
|-
| || @altFontFamily ||
|-
| @font-size-touch || @touchFontSize || 15px
|-
| @headings-font-family || @headingsFontFamily || inherit
|-
| @headings-font-weight || @headingsFontWeight || 500
|-
| @font-size-large || @fontSizeLarge || ceil((@font-size-base * 1.25)); // ~18px
|-
| @font-size-small || @fontSizeSmall || ceil((@font-size-base * 0.85)); // ~12px
|-
| || @fontSizeMini ||
|-
| @vgrid-font-size || @vgridFontSize || 13px
|}

==== Colors ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @background || @bodyBackground || #fff
|-
| @text-color || @textColor || @gray-dark
|-
| @link-color || @linkColor || @brand-primary
|-
| @link-hover-color || @linkColorHover || darken(@link-color, 15%)
|-
| @link-accent-color || @linkAccentColor || #ffad00
|-
| || @linkAccentColorHover ||
|-
| @badge-color || @badgeColor || @white
|-
| @badge-bg || @badgeBackground || #aaa
|-
| @headings-color || @headingsColor || inherit
|-
| @black || @black || #000
|-
| @gray-darker || @grayDarker || #222
|-
| @gray-dark || @grayDark || #333
|-
| @gray || @gray || #555
|-
| @gray-light || @grayLight || #999
|-
| @gray-lighter || @grayLighter || #eee
|-
| @white || @white || #fff
|-
| @blue || @blue || darken(#049cdb, 5%)
|-
| @blue-dark || @blueDark || #0064cd
|-
| @blue-light || @blueLight || lighten(#049cdb, 25%)
|-
| @green || @green || #1A8D1A
|-
| @green-light || @greenLight || #92D050
|-
| @red || @red || #cc0000
|-
| @yellow || @yellow || #F8E400
|-
| @orange || @orange || #f89406
|-
| @pink || @pink || #E01CD9
|-
| @purple || @purple || #7E16CF
|-
|}

==== Space ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| || @paddingLarge ||
|-
| || @paddingSmall ||
|-
| || @paddingMini ||
|-
| @border-radius-base || @baseBorderRadius || 4px
|-
| @border-radius-large || @borderRadiusLarge || 6px
|-
| @border-radius-small || @borderRadiusSmall || 3px
|}

=== Pagination ===

Used where pagination is done, for example in the Calendar weekview, each week is on one "page"; one can switch the week using a pagination widget styled with these variables.

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @pagination-bg || @paginationBackground || #fff
|-
| @pagination-border || @paginationBorder || #ddd
|-
| @pagination-active-bg || @paginationActiveBackground || @brand-primary
|}

=== Buttons ===

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| || @btnBackground ||
|-
| || @btnBackgroundHighlight ||
|-
| || @btnBorder ||
|-
| @btn-primary-background || @btnPrimaryBackground || @link-color
|-
| @btn-primary-background-highlinght || @btnPrimaryBackgroundHighlight || darken(@btn-primary-background, 10%);
|-
| @btn-info-background || @btnInfoBackground || #5bc0de
|-
| @btn-info-background-highlight || @btnInfoBackgroundHighlight || #2f96b4
|-
| @btn-success-background || @btnSuccessBackground || #62c462
|-
| @btn-success-background-highlight || @btnSuccessBackgroundHighlight || #51a351
|-
| @btn-warning-background || @btnWarningBackground || lighten(@orange, 15%)
|-
| @btn-warning-background-highlight || @btnWarningBackgroundHighlight || @orange
|-
| @btn-danger-background || @btnDangerBackground || #ee5f5b
|-
| @btn-danger-background-danger-highlight || @btnDangerBackgroundHighlight || #bd362f
|-
| @btn-inverse-background || @btnInverseBackground || #444
|-
| @btn-inverse-background-highlight || @btnInverseBackgroundHighlight || @gray-darker
|}

=== Dropdowns ===

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @dropdown-bg || @dropdownBackground || #fff
|-
| @dropdown-border || @dropdownBorder || rgba(0,0,0,.15)
|-
| @dropdown-divider-bg || @dropdownDividerTop || #e5e5e5
|-
| @dropdown-divider-bg || @dropdownDividerBottom || #e5e5e5
|-
| @dropdown-link-color || @dropdownLinkColor || @gray-dark
|-
| @dropdown-link-hover-color || @dropdownLinkColorHover || darken(@gray-dark, 5%)
|-
| @dropdown-link-active-color || @dropdownLinkColorActive || @component-active-color
|-
| @dropdown-link-active-bg || @dropdownLinkBackgroundActive || @component-active-bg
|-
| @dropdown-link-hover-bg || @dropdownLinkBackgroundHover || #f5f5f5
|}

=== Foldertree ===
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @foldertree-sidepane-background || @foldertreeSidepanelBackground || #f5f5f5 ||
|-
| @foldertee-section-title-color || @foldertreeSectionTitleColor || #888 || Color for sectiontitles in foldertree (like "Public" folders)
|-
| @foldertree-active-label-color || @foldertreeActiveLabelColor || #333 || ''Active'' means, user can perform an action on this item
|-
|@foldertree-passive-label-color || @foldertreePassiveLabelColor ||@hc-gray || ''Passive'' means, user can '''not''' perform any action with this item
|-
| @foldertree-hover-background || @foldertreeHoverBackground || rgba(0, 0, 0, 0.05) ||
|-
| @foldertree-selected-background || @foldertreeSelectedBackground || rgba(0, 0, 0, 0.10) ||
|-
| @foldertree-badge-background || @foldertreeBadgeBackground || @bagde-bg || see [[#Colors]] for definition of @badge-bg
|-
| @foldertree-badge-color || @foldertreeBadgeColor ||@badge-color || see [[#Colors]] for definition of @badge-color
|}

=== Calendar ===
==== Appointment ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @appointment-reserved || @appointmentReserved || #08c /* blue */ || Appointment status color
|-
| @appointment-temporary || @appointmentTemporary || #ffbb00 /* yellow */ || Appointment status color
|-
| @appointment-absent || @appointmentAbsent || #913f3f /* red */ || Appointment status color
|-
| @appointment-free || @appointmentFree || #8eb360 /* green */ || Appointment status color
|-
| @appointment-private || @appointmentPrivate || #555 /* gray */ || Appointment status color
|-
| @appointment-declined-font || @appointmentDeclinedFont || #888 /* dark gray */|| Font color for declined Appointments
|-
| @appointment-unconfirmed-alpha || @appointmentUnconfirmedAlpha || 0.4 || Transparency value for unconfirmed Appointments
|-
| @appointment-declined-alpha || @appointmentDeclinedAlpha || 0.3 || Transparency value for declined Appointments
|-
| @appointment-hover-pct || @appointmentHoverPct || 15% || Percentage increase of the dark pigment content on hover effect
|}

==== Week View ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @weekview-appointment-lasso || @weekviewAppointmentLasso || #aeaeff || Lasso frame color
|-
| @weekview-day-in || @weekviewDayIn || #fff /* white */ || Default background color in week view
|-
| @weekview-day-out || @weekviewDayOut || #e0e0e0 /* grey */ || Background color outside of the mean working time
|-
| @weekview-timeline || @weekviewTimeline || rgba(243, 15, 170, 0.4) || Color of the Line indicating the current time
|-
| @weekview-time-width || @weekviewTimeWith || 58px || With of the time labels on the left side
|-
| @calendar-toolbar-height || @calendarToolbarHeight || 47px || Height of the control toolbar
|}

==== Month View ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @monthview-appointment-out || @monthviewAppointmentOut || #aaa /* light gray */ || Color of appointments, which are not in focus
|-
| @monthview-today || @monthviewToday || #daefff /* light blue */|| Background color of the current day
|-
| || @monthview@calendarToolbarHeight || ||
|}

== Area names ==

The variables sometimes refer to common areas. To identify which area is located where, see the following annotated screenshots.

[[File:Colors_mail.png|800px||Mail application]]

[[File:Colors_launchpad.png|800px||Launchpad application]]

== Replacing the logo ==

One of the most common theme changes which requires editing <code>style.css</code> is changing the logo in the top right corner. The logo is displayed as the background image for an element with the ID <code>io-ox-top-logo-small</code>. A theme can therefore change the size and URL of the image:
#io-ox-top-logo-small {
width: 60px;
height: 22px;
margin: 8px 13px 0 13px;
background-image: url(mylogo.png);
}
The file <code>mylogo.png</code> is expected to be in the same directory as <code>style.css</code>. If you want to place the image somewhere else, then use a relative path in <code>url()</code>.

Remember that images in OX App Suite are served by the web server and not by the application server. This means that images need to be packaged separately (for dedicated web servers) and installed in <code>/var/www/appsuite/</code> (or similar, depending on the target platform) instead of <code>/opt/open-xchange/appsuite/</code>. Direct support for multiple packages is coming in version 7.4.1. Until then, use the build system from the <code>develop</code> branch to [[AppSuite:UI_build_system#init-packaging|initialize the packaging]] if your theme contains images.

== Mixins ==
In LESS, it is possible to include a bunch of properties from one ruleset into another ruleset. So say we have the following class:

=== Sample ===
<pre class="language-css">
.border-radius(@radius: 0px) {
-webkit-border-radius: @radius;
-moz-border-radius: @radius;
-ms-border-radius: @radius;
border-radius: @radius;
}

#menu a {
color: #111;
.border-radius(5px);
}
</pre>

Read [http://www.lesscss.org/#-mixins LESS Mixins]

=== global OX Mixins ===

they can be found at [[#definitions.less | definitions.less]]

{|
! Mixin || Sample || Description
|-
| .box-sizing(@boxmodel) || .box-sizing(border-box) ||
|-
| .user-select(@select) || .user-select(none) ||
|-
| .border-radius(@radius) || .border-radius(3px) ||
|-
| .box-shadow(@shadow) || .box-shadow(3px) ||
|-
| .vertical-gradient(@startColor, @endColor) || .vertical-gradient(#888, #555) ||
|-
| .radial-gradient(@color1, @color2, @color3) || .radial-gradient(#111, #222, #333) ||
|-
| .transition(@transition) || .transition(background-color 0.2s linear) ||
|-
| .animation(@animation) || .animation(slidein 300ms) ||
|-
| .animation-name(@name) || .animation-name(slideright) ||
|-
| .ellipsis || .ellipsis ||
|-
| .overflow(@type) || .overflow(hidden) ||
|-
| .overflow-x(@type) || .overflow-x(hidden) ||
|-
| .overflow-y(@type) || .overflow-y(hidden) ||
|-
| .backface-visibility(@type) || .backface-visibility(hidden) ||
|}

== How to activate a theme during development ==

When creating a new theme, you will want to test changes quickly without building packages reinstalling them. The trick is to use [[Appsuite:Appserver|appserver]].

# First, you need to add the theme to the list of available themes on the backend. Simply create a new file in <code>/opt/open-xchange/etc/settings/</code> with the extension <code>.properties</code> and add a line for your theme to it: <pre<noinclude></noinclude>>io.ox/core/settingOptions//themes/<var>ID</var>=<var>Theme Name</var></pre<noinclude></noinclude>> Replace <var>ID</var> by the identifier (directory name) of your theme, and <var>Theme Name</var> by the human-readable name which should appear in the UI.
# The server needs to be restarted to read the new settings.
# Now, you can use <code>appserver</code> ([[AppSuite:appserver#Use_with_Apache|with a local web server]] if your theme includes images) to get your theme in combination with the UI which is already installed on the backend.
# Finally, activate your theme the list in the <code>Settings -> Basic</code> view behind the option <code>Theme</code>.

In case you also want to access the same backend without <code>appserver</code> while your theme is selected, that theme (or at least some empty <code>.less</code> files) should be also installed on the backend to avoid errors. To just use an empty theme, run the following as root:
touch /opt/open-xchange/appsuite/apps/themes/<var>ID</var>/definitions.less
touch /opt/open-xchange/appsuite/apps/themes/<var>ID</var>/style.less
/opt/open-xchange/appsuite/share/update-themes.sh
The value of <var>ID</var> here must be the same as in your <code>.properties</code> file.

== Favicons and mobile homescreen icons ==
'''Note''': This chapter is not about changing AppSuite icons which are used in the application like the brand on the upper right.

'''This documentation applies for AppSuite v.7.4.2'''

AppSuite ships with a standard set of icons containing a
# favicon
# set of touch icons which are mainly used by mobile Safari on iOS

These icons are used as default for all devices and browsers as long as you don't deliver your own icons with your theme.

=== Favicon ===
All major browsers support the use of a favicon. The favicon is a pixel image with the size of 16x16 (32x32) and the "ico" file ending. (see [http://en.wikipedia.org/wiki/Favicon Wikipedia Favicon] for details).

You should provide your custom favicon within your custom theme. If you do not add a custom favicon to your theme the global OX default will be used. The default icon is located under <tt>apps/themes/icons/default</tt> on the web server.

'''Attention:''' Safari and Internet Explorer do not support dynamic changes to the favicon for a webpage. This means, the default icon will be shown even if a custom favicon is provided within a custom theme. To enable the right favicon for a theme on Safari and IE, the overall standard <tt>favicon.ico</tt> located under <tt>apps/themes/icons/default</tt> on the web server must be replaced with a custom version.

=== Apple touch icons ===
iOS devices (iPhone/iPad/iPod) support so called "Webclips". Webclips are bookmarks to websites or webapps which provide a App Icon that is shown on the iOS homescreen. AppSuite offers full support for Webclips by providing all needed App icons, splashscreens and full screen support. If a user uses the "Add to homescreen" button on his iOS device, a Webclip is created, taking the right icon for his current device. Most devices need custom resolutions of the Webclip icon in the '''png''' format.

* iPhone 3: 57 x 57 px
* iPhone 4 retina: 114x114 px
* iPhone iPhone 5 retina: 120 x 120 px
* iPad: 72 x 72 px
* iPad (iOS 7): 76 x 76px
* iPad retina: 144 x 144 px
* iPad retina (iOS 7): 152 x 152 px

Furthermore a fullscreen Webclip App will show a splashscreen, a jpg file that is displayed on startup during app load. There are currently three different resolutions as jpg files available. '''Note''': Splashscreens must be JPG files

* iPhone: 320 x 460 px
* iPhone 4: 640 x 920 px
* iPhone 5: 640 x 1096 px

'''Note''': We do not provide splashscreens for iPad

This list may change with Apple's iOS updates. We recommend providing all of this resolutions when customizing the Webclip icons and splashscreens, even if some iOS devices use the next best resolution for an icon if a certain file is missing.

=== Providing custom icons ===
To provide custom Webclip icons locate the following path in the AppSuite installation on your web server:
pathToAppSuite/apps/themes/icons/default

This folder contains all OX default icons for Webclips icons and splashscreens. Use these as samples for your own versions.

A clean installation will have all our default icons in the "default" directory. To customize the icons we recommend using our default icons as samples and save your customized version in your theme. '''Note''': The filename has to be the same as in the default folder. Otherwise the fallback will be applied and the default icons will be used. If more advanced rewriting is needed one should edit the contents of the <tt>.htaccess</tt> file located under <tt>apps/themes</tt>

== Theming the login page ==

The login page is a little bit special. If you don’t use the [[Open-Xchange_servlet_for_external_login_masks|form login]] and provide your own login page, you might want to theme the login page, too. [[AppSuite:Theming the login page|Learn how to do this here]].

=== Providing domain based login themes ===

If you have a multibrand installation and you want to deliver not only custom themes but also custom login-themes this can be done via Apache mod_rewrite. You can do so by a domain-based rewrite rule to deliver custom themes to a user based on the URI he's using. The needed config file <tt>.htaccess</tt> is located under <tt>apps/themes</tt>

<pre>
# Sample config for domain based login theme
RewriteCond %{HTTP_HOST} ^www\.domain\.com$
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^login/(.*)$ domain_com_logintheme/$1 [L]
</pre>

== Best practice ==

To be really safe, it’s best to only define your own values for the variables shown above. If this really breaks anything, we consider this a bug, please report it [https://bugs.open-xchange.com/] in our bugzilla.

Of course, using CSS in <code>style.less</code> file to define your own styles is also possible. Make sure to test your style in such cases more carefully. It is most likely safe to change minor things using this file, but if you plan to change any positions of larger elements, this might break the complete design. So please be careful when overwriting the default CSS rules.

== Links ==
[http://bradfrost.github.io/this-is-responsive/resources.html Responsive design]

[http://lesscss.org/ LESS]

== Caveats ==

It is '''not''' recommended to change the size of elements or their position. If you really want to do so, please check on all devices and in all browsers and make sure you didn’t break anything. You even have to be careful when changing the font, because this might have effects on positioning, too.

As mentioned before, changing colors should be safe.

[[Category:AppSuite]]
[[Category:UI]]

AppSuite:Theming

2014-04-11T14:54:47Z

D.haus: /* Month View */

{{Stability-experimental}}

<div class="title">Theming</div>

'''Abstract.''' In this article, you can learn how to create customized themes and use them to change the look of you appsuite installation.
__TOC__
== LESS.JS ==
Appsuite used LESS as dynamic stylesheet language. LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions.

Please read [http://lesscss.org/#docs LESS.JS] documentation first.

=== Using less.js ===
If your theme depends on less.js, you will need one more step to make it work. Why? To accelerate the login, compilation of LessCSS files was moved from the login process in the browser to the installation process on the backend.

Backend packages for themes and any apps which ship .less files require the following changes:

1. Add "skipLess=1" to the build command in *.spec and in debian/rules:
sh /opt/open-xchange-appsuite-dev/bin/build-appsuite app skipLess=1
2. Add %post and %postun sections to *.spec:
%post
if [ "$1" = 1 ]; then
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE
fi
%postun
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE

For multiple binary packages, the %post and %postun sections should apply only to backend packages
which contain .less files.

3. Add debian/postinst and debian/postrm containing the same content:
#!/bin/sh
UPDATE=/opt/open-xchange/appsuite/share/update-themes.sh
[ -x $UPDATE ] && $UPDATE

For multiple binary packages, the postinst and postrm files should apply only to backend packages which contain .less files.

Note: Since 7.2.1, LessCSS files must have the file extension .less to be usable with the 'less' RequireJS plugin (module dependencies of the form 'less!filename.less'). Previously we were more lenient and dealt with .css, too.

== File structure ==
A theme basically consists of two files located in <code>apps/themes/<var>THEME_ID</var>/</code>. These files are described in this and the following sections.

<code><var>THEME_ID</var></code> is a unique identifier for your theme, which is not visible to users. By convention, it is best derived from a domain name you control, e.g. <code>com.example.prettytheme</code>.

=== definitions.less ===
This file can be used to override variables described in the "Variables" section of this article.

=== style.less ===
This file can be used to define any CSS you like. Before doing this, check, if there really is no variable that can be used to achieve the same thing.

=== Referencing paths ===
Since 7.2.1, all URLs are relative to the source .less file in which they are contained. This means that unless a theme changes an image it does not need to include that image anymore.

Old themes must be updated if they change an image from the default theme: All styles from the default theme which refer to a changed image must be overwritten in the custom theme. This way the URLs resolve to the new image.

== Variables ==

Naming of the variables should be straight forward. Variables containing the word ''Background'' will always refer to the background color. Variables containing ''Color'' will refer to the foreground color of an element, like color of a font. ''Hover'' in most cases means "hovered" elements. ''Selected'' relates to the currently selected item. Elements that are supposed to catch the users eye can use the ''Highlight'' class and the variable contains this word.

=== Basic ===

==== Font ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @font-family-sans-serif || @sansFontFamily || "Helvetica Neue", Helvetica, Arial, sans-serif
|-
| @font-family-serif || @serifFontFamily || Georgia, "Times New Roman", Times, serif
|-
| @font-family-monospace || @monoFontFamily || Monaco, Menlo, Consolas, "Courier New", monospace
|-
| @font-size-base || @baseFontSize || 14px
|-
| || @baseFontFamily ||
|-
| @line-height-base || @baseLineHeight || 1.428571429; // 20/14
|-
| || @altFontFamily ||
|-
| @font-size-touch || @touchFontSize || 15px
|-
| @headings-font-family || @headingsFontFamily || inherit
|-
| @headings-font-weight || @headingsFontWeight || 500
|-
| @font-size-large || @fontSizeLarge || ceil((@font-size-base * 1.25)); // ~18px
|-
| @font-size-small || @fontSizeSmall || ceil((@font-size-base * 0.85)); // ~12px
|-
| || @fontSizeMini ||
|-
| @vgrid-font-size || @vgridFontSize || 13px
|}

==== Colors ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @background || @bodyBackground || #fff
|-
| @text-color || @textColor || @gray-dark
|-
| @link-color || @linkColor || @brand-primary
|-
| @link-hover-color || @linkColorHover || darken(@link-color, 15%)
|-
| @link-accent-color || @linkAccentColor || #ffad00
|-
| || @linkAccentColorHover ||
|-
| @badge-color || @badgeColor || @white
|-
| @badge-bg || @badgeBackground || #aaa
|-
| @headings-color || @headingsColor || inherit
|-
| @black || @black || #000
|-
| @gray-darker || @grayDarker || #222
|-
| @gray-dark || @grayDark || #333
|-
| @gray || @gray || #555
|-
| @gray-light || @grayLight || #999
|-
| @gray-lighter || @grayLighter || #eee
|-
| @white || @white || #fff
|-
| @blue || @blue || darken(#049cdb, 5%)
|-
| @blue-dark || @blueDark || #0064cd
|-
| @blue-light || @blueLight || lighten(#049cdb, 25%)
|-
| @green || @green || #1A8D1A
|-
| @green-light || @greenLight || #92D050
|-
| @red || @red || #cc0000
|-
| @yellow || @yellow || #F8E400
|-
| @orange || @orange || #f89406
|-
| @pink || @pink || #E01CD9
|-
| @purple || @purple || #7E16CF
|-
|}

==== Space ====

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| || @paddingLarge ||
|-
| || @paddingSmall ||
|-
| || @paddingMini ||
|-
| @border-radius-base || @baseBorderRadius || 4px
|-
| @border-radius-large || @borderRadiusLarge || 6px
|-
| @border-radius-small || @borderRadiusSmall || 3px
|}

=== Pagination ===

Used where pagination is done, for example in the Calendar weekview, each week is on one "page"; one can switch the week using a pagination widget styled with these variables.

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @pagination-bg || @paginationBackground || #fff
|-
| @pagination-border || @paginationBorder || #ddd
|-
| @pagination-active-bg || @paginationActiveBackground || @brand-primary
|}

=== Buttons ===

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| || @btnBackground ||
|-
| || @btnBackgroundHighlight ||
|-
| || @btnBorder ||
|-
| @btn-primary-background || @btnPrimaryBackground || @link-color
|-
| @btn-primary-background-highlinght || @btnPrimaryBackgroundHighlight || darken(@btn-primary-background, 10%);
|-
| @btn-info-background || @btnInfoBackground || #5bc0de
|-
| @btn-info-background-highlight || @btnInfoBackgroundHighlight || #2f96b4
|-
| @btn-success-background || @btnSuccessBackground || #62c462
|-
| @btn-success-background-highlight || @btnSuccessBackgroundHighlight || #51a351
|-
| @btn-warning-background || @btnWarningBackground || lighten(@orange, 15%)
|-
| @btn-warning-background-highlight || @btnWarningBackgroundHighlight || @orange
|-
| @btn-danger-background || @btnDangerBackground || #ee5f5b
|-
| @btn-danger-background-danger-highlight || @btnDangerBackgroundHighlight || #bd362f
|-
| @btn-inverse-background || @btnInverseBackground || #444
|-
| @btn-inverse-background-highlight || @btnInverseBackgroundHighlight || @gray-darker
|}

=== Dropdowns ===

{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x)
|-
| @dropdown-bg || @dropdownBackground || #fff
|-
| @dropdown-border || @dropdownBorder || rgba(0,0,0,.15)
|-
| @dropdown-divider-bg || @dropdownDividerTop || #e5e5e5
|-
| @dropdown-divider-bg || @dropdownDividerBottom || #e5e5e5
|-
| @dropdown-link-color || @dropdownLinkColor || @gray-dark
|-
| @dropdown-link-hover-color || @dropdownLinkColorHover || darken(@gray-dark, 5%)
|-
| @dropdown-link-active-color || @dropdownLinkColorActive || @component-active-color
|-
| @dropdown-link-active-bg || @dropdownLinkBackgroundActive || @component-active-bg
|-
| @dropdown-link-hover-bg || @dropdownLinkBackgroundHover || #f5f5f5
|}

=== Foldertree ===
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @foldertree-sidepane-background || @foldertreeSidepanelBackground || #f5f5f5 ||
|-
| @foldertee-section-title-color || @foldertreeSectionTitleColor || #888 || Color for sectiontitles in foldertree (like "Public" folders)
|-
| @foldertree-active-label-color || @foldertreeActiveLabelColor || #333 || ''Active'' means, user can perform an action on this item
|-
|@foldertree-passive-label-color || @foldertreePassiveLabelColor ||@hc-gray || ''Passive'' means, user can '''not''' perform any action with this item
|-
| @foldertree-hover-background || @foldertreeHoverBackground || rgba(0, 0, 0, 0.05) ||
|-
| @foldertree-selected-background || @foldertreeSelectedBackground || rgba(0, 0, 0, 0.10) ||
|-
| @foldertree-badge-background || @foldertreeBadgeBackground || @bagde-bg || see [[#Colors]] for definition of @badge-bg
|-
| @foldertree-badge-color || @foldertreeBadgeColor ||@badge-color || see [[#Colors]] for definition of @badge-color
|}

=== Calendar ===
==== Appointment ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @appointment-reserved || @appointmentReserved || #08c /* blue */ || Appointment status color
|-
| @appointment-temporary || @appointmentTemporary || #ffbb00 /* yellow */ || Appointment status color
|-
| @appointment-absent || @appointmentAbsent || #913f3f /* red */ || Appointment status color
|-
| @appointment-free || @appointmentFree || #8eb360 /* green */ || Appointment status color
|-
| @appointment-private || @appointmentPrivate || #555 /* gray */ || Appointment status color
|-
| @appointment-declined-font || @appointmentDeclinedFont || #888 /* dark gray */|| Font color for declined Appointments
|-
| @appointment-unconfirmed-alpha || @appointmentUnconfirmedAlpha || 0.4 || Transparency value for unconfirmed Appointments
|-
| @appointment-declined-alpha || @appointmentDeclinedAlpha || 0.3 || Transparency value for declined Appointments
|-
| @appointment-hover-pct || @appointmentHoverPct || 15% || Percentage increase of the dark pigment content on hover effect
|}

==== Week View ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @weekview-appointment-lasso || @weekviewAppointmentLasso || #aeaeff || Lasso frame color
|-
| @weekview-day-in || @weekviewDayIn || #fff /* white */ || Default background color in week view
|-
| @weekview-day-out || @weekviewDayOut || #e0e0e0 /* grey */ || Background color outside of the mean working time
|-
| @weekview-timeline || @weekviewTimeline || rgba(243, 15, 170, 0.4) || Color of the Line indicating the current time
|-
| @weekview-time-width || @weekviewTimeWith || 58px || With of the time labels on the left side
|-
| @calendar-toolbar-height || @calendarToolbarHeight || 47px || Height of the control toolbar
|}

==== Month View ====
{|
! Variable (7.6.x) || Variable (7.4.x) || Default (7.6.x) || Description
|-
| @monthview-appointment-out || @monthviewAppointmentOut || #aaa /* light gray */ || Color of appointments, which are not in focus
|-
| @monthview-today || @monthviewToday || #daefff /* light blue */|| Background color of the current day
|-
| || @monthview@calendarToolbarHeight || ||
|}

== Area names ==

The variables sometimes refer to common areas. To identify which area is located where, see the following annotated screenshots.

[[File:Colors_mail.png|800px||Mail application]]

[[File:Colors_launchpad.png|800px||Launchpad application]]

== Replacing the logo ==

One of the most common theme changes which requires editing <code>style.css</code> is changing the logo in the top right corner. The logo is displayed as the background image for an element with the ID <code>io-ox-top-logo-small</code>. A theme can therefore change the size and URL of the image:
#io-ox-top-logo-small {
width: 60px;
height: 22px;
margin: 8px 13px 0 13px;
background-image: url(mylogo.png);
}
The file <code>mylogo.png</code> is expected to be in the same directory as <code>style.css</code>. If you want to place the image somewhere else, then use a relative path in <code>url()</code>.

Remember that images in OX App Suite are served by the web server and not by the application server. This means that images need to be packaged separately (for dedicated web servers) and installed in <code>/var/www/appsuite/</code> (or similar, depending on the target platform) instead of <code>/opt/open-xchange/appsuite/</code>. Direct support for multiple packages is coming in version 7.4.1. Until then, use the build system from the <code>develop</code> branch to [[AppSuite:UI_build_system#init-packaging|initialize the packaging]] if your theme contains images.

== Mixins ==
In LESS, it is possible to include a bunch of properties from one ruleset into another ruleset. So say we have the following class:

=== Sample ===
<pre class="language-css">
.border-radius(@radius: 0px) {
-webkit-border-radius: @radius;
-moz-border-radius: @radius;
-ms-border-radius: @radius;
border-radius: @radius;
}

#menu a {
color: #111;
.border-radius(5px);
}
</pre>

Read [http://www.lesscss.org/#-mixins LESS Mixins]

=== global OX Mixins ===

they can be found at [[#definitions.less | definitions.less]]

{|
! Mixin || Sample || Description
|-
| .box-sizing(@boxmodel) || .box-sizing(border-box) ||
|-
| .user-select(@select) || .user-select(none) ||
|-
| .border-radius(@radius) || .border-radius(3px) ||
|-
| .box-shadow(@shadow) || .box-shadow(3px) ||
|-
| .vertical-gradient(@startColor, @endColor) || .vertical-gradient(#888, #555) ||
|-
| .radial-gradient(@color1, @color2, @color3) || .radial-gradient(#111, #222, #333) ||
|-
| .transition(@transition) || .transition(background-color 0.2s linear) ||
|-
| .animation(@animation) || .animation(slidein 300ms) ||
|-
| .animation-name(@name) || .animation-name(slideright) ||
|-
| .ellipsis || .ellipsis ||
|-
| .overflow(@type) || .overflow(hidden) ||
|-
| .overflow-x(@type) || .overflow-x(hidden) ||
|-
| .overflow-y(@type) || .overflow-y(hidden) ||
|-
| .backface-visibility(@type) || .backface-visibility(hidden) ||
|}

== How to activate a theme during development ==

When creating a new theme, you will want to test changes quickly without building packages reinstalling them. The trick is to use [[Appsuite:Appserver|appserver]].

# First, you need to add the theme to the list of available themes on the backend. Simply create a new file in <code>/opt/open-xchange/etc/settings/</code> with the extension <code>.properties</code> and add a line for your theme to it: <pre<noinclude></noinclude>>io.ox/core/settingOptions//themes/<var>ID</var>=<var>Theme Name</var></pre<noinclude></noinclude>> Replace <var>ID</var> by the identifier (directory name) of your theme, and <var>Theme Name</var> by the human-readable name which should appear in the UI.
# The server needs to be restarted to read the new settings.
# Now, you can use <code>appserver</code> ([[AppSuite:appserver#Use_with_Apache|with a local web server]] if your theme includes images) to get your theme in combination with the UI which is already installed on the backend.
# Finally, activate your theme the list in the <code>Settings -> Basic</code> view behind the option <code>Theme</code>.

In case you also want to access the same backend without <code>appserver</code> while your theme is selected, that theme (or at least some empty <code>.less</code> files) should be also installed on the backend to avoid errors. To just use an empty theme, run the following as root:
touch /opt/open-xchange/appsuite/apps/themes/<var>ID</var>/definitions.less
touch /opt/open-xchange/appsuite/apps/themes/<var>ID</var>/style.less
/opt/open-xchange/appsuite/share/update-themes.sh
The value of <var>ID</var> here must be the same as in your <code>.properties</code> file.

== Favicons and mobile homescreen icons ==
'''Note''': This chapter is not about changing AppSuite icons which are used in the application like the brand on the upper right.

'''This documentation applies for AppSuite v.7.4.2'''

AppSuite ships with a standard set of icons containing a
# favicon
# set of touch icons which are mainly used by mobile Safari on iOS

These icons are used as default for all devices and browsers as long as you don't deliver your own icons with your theme.

=== Favicon ===
All major browsers support the use of a favicon. The favicon is a pixel image with the size of 16x16 (32x32) and the "ico" file ending. (see [http://en.wikipedia.org/wiki/Favicon Wikipedia Favicon] for details).

You should provide your custom favicon within your custom theme. If you do not add a custom favicon to your theme the global OX default will be used. The default icon is located under <tt>apps/themes/icons/default</tt> on the web server.

'''Attention:''' Safari and Internet Explorer do not support dynamic changes to the favicon for a webpage. This means, the default icon will be shown even if a custom favicon is provided within a custom theme. To enable the right favicon for a theme on Safari and IE, the overall standard <tt>favicon.ico</tt> located under <tt>apps/themes/icons/default</tt> on the web server must be replaced with a custom version.

=== Apple touch icons ===
iOS devices (iPhone/iPad/iPod) support so called "Webclips". Webclips are bookmarks to websites or webapps which provide a App Icon that is shown on the iOS homescreen. AppSuite offers full support for Webclips by providing all needed App icons, splashscreens and full screen support. If a user uses the "Add to homescreen" button on his iOS device, a Webclip is created, taking the right icon for his current device. Most devices need custom resolutions of the Webclip icon in the '''png''' format.

* iPhone 3: 57 x 57 px
* iPhone 4 retina: 114x114 px
* iPhone iPhone 5 retina: 120 x 120 px
* iPad: 72 x 72 px
* iPad (iOS 7): 76 x 76px
* iPad retina: 144 x 144 px
* iPad retina (iOS 7): 152 x 152 px

Furthermore a fullscreen Webclip App will show a splashscreen, a jpg file that is displayed on startup during app load. There are currently three different resolutions as jpg files available. '''Note''': Splashscreens must be JPG files

* iPhone: 320 x 460 px
* iPhone 4: 640 x 920 px
* iPhone 5: 640 x 1096 px

'''Note''': We do not provide splashscreens for iPad

This list may change with Apple's iOS updates. We recommend providing all of this resolutions when customizing the Webclip icons and splashscreens, even if some iOS devices use the next best resolution for an icon if a certain file is missing.

=== Providing custom icons ===
To provide custom Webclip icons locate the following path in the AppSuite installation on your web server:
pathToAppSuite/apps/themes/icons/default

This folder contains all OX default icons for Webclips icons and splashscreens. Use these as samples for your own versions.

A clean installation will have all our default icons in the "default" directory. To customize the icons we recommend using our default icons as samples and save your customized version in your theme. '''Note''': The filename has to be the same as in the default folder. Otherwise the fallback will be applied and the default icons will be used. If more advanced rewriting is needed one should edit the contents of the <tt>.htaccess</tt> file located under <tt>apps/themes</tt>

== Theming the login page ==

The login page is a little bit special. If you don’t use the [[Open-Xchange_servlet_for_external_login_masks|form login]] and provide your own login page, you might want to theme the login page, too. [[AppSuite:Theming the login page|Learn how to do this here]].

=== Providing domain based login themes ===

If you have a multibrand installation and you want to deliver not only custom themes but also custom login-themes this can be done via Apache mod_rewrite. You can do so by a domain-based rewrite rule to deliver custom themes to a user based on the URI he's using. The needed config file <tt>.htaccess</tt> is located under <tt>apps/themes</tt>

<pre>
# Sample config for domain based login theme
RewriteCond %{HTTP_HOST} ^www\.domain\.com$
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^login/(.*)$ domain_com_logintheme/$1 [L]
</pre>

== Best practice ==

To be really safe, it’s best to only define your own values for the variables shown above. If this really breaks anything, we consider this a bug, please report it [https://bugs.open-xchange.com/] in our bugzilla.

Of course, using CSS in <code>style.less</code> file to define your own styles is also possible. Make sure to test your style in such cases more carefully. It is most likely safe to change minor things using this file, but if you plan to change any positions of larger elements, this might break the complete design. So please be careful when overwriting the default CSS rules.

== Links ==
[http://bradfrost.github.io/this-is-responsive/resources.html Responsive design]

[http://lesscss.org/ LESS]

== Caveats ==

It is '''not''' recommended to change the size of elements or their position. If you really want to do so, please check on all devices and in all browsers and make sure you didn’t break anything. You even have to be careful when changing the font, because this might have effects on positioning, too.

As mentioned before, changing colors should be safe.

[[Category:AppSuite]]
[[Category:UI]]