Open-Xchange - User contributions [en]

AppSuite:Theming

2014-04-11T08:09:30Z

David.bauer: /* Font */

{{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) || Default (7.4.x)
|-
| @font-family-sans-serif || @sansFontFamily || "Helvetica Neue", Helvetica, Arial, sans-serif || "Helvetica Neue", Helvetica, Arial, sans-serif
|-
| @font-family-serif || @serifFontFamily || Georgia, "Times New Roman", Times, serif || Georgia, "Times New Roman", Times, serif
|-
| @font-family-monospace || @monoFontFamily || Monaco, Menlo, Consolas, "Courier New", monospace || Monaco, Menlo, Consolas, "Courier New", monospace
|-
| @font-size-base || @baseFontSize || 14px || 14px
|-
| || @baseFontFamily || || @sansFontFamily
|-
| @line-height-base || @baseLineHeight || 1.428571429; // 20/14 || 20px
|-
| || @altFontFamily || || @serifFontFamily
|-
| @font-size-touch || @touchFontSize || 15px || 15px
|-
| @headings-font-family || @headingsFontFamily || inherit || inherit
|-
| @headings-font-weight || @headingsFontWeight || 500 || bold
|-
| @font-size-large || @fontSizeLarge || ceil((@font-size-base * 1.25)); // ~18px || @baseFontSize * 1.25
|-
| @font-size-small || @fontSizeSmall || ceil((@font-size-base * 0.85)); // ~12px || @baseFontSize * 0.85
|-
| || @fontSizeMini || || @baseFontSize * 0.75
|-
| @vgrid-font-size || @vgridFontSize || 13px || 13px
|}

==== Colors ====

{|
! Variable || Default || Description
|-
| @bodyBackground || @white
|-
| @textColor || @grayDark
|-
| @linkColor || #08c
|-
| @linkColorHover || darken(@linkColor, 15%)
|-
| @linkAccentColor || #ffad00
|-
| @linkAccentColorHover || darken(@linkAccentColor, 15%)
|-
| @badgeColor || @white
|-
| @badgeBackground || #555
|-
| @headingsColor || inherit
|-
| @black || #000
|-
| @grayDarker || #222
|-
| @grayDark || #333
|-
| @gray || #555
|-
| @grayLight || #aaa
|-
| @grayLighter || #eee
|-
| @white || #fff
|-
| @blue || darken(#049cdb, 5%)
|-
| @blueDark || #0064cd
|-
| @blueLight || lighten(#049cdb, 25%)
|-
| @green || #1A8D1A
|-
| @greenLight || #92D050
|-
| @red || #cc0000
|-
| @yellow || #F8E400
|-
| @orange || #f89406
|-
| @pink || #E01CD9
|-
| @purple || #7E16CF
|-
|}

==== Space ====

{|
! Variable || Default || Description
|-
| @paddingLarge || 11px 19px
|-
| @paddingSmall || 2px 10px
|-
| @paddingMini || 0 6px
|-
| @baseBorderRadius || 4px
|-
| @borderRadiusLarge || 6px
|-
| @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 || Default || Description
|-
| @paginationBackground || #fff
|-
| @paginationBorder || #ddd
|-
| @paginationActiveBackground || #f5f5f5
|}

=== Buttons ===

{|
! Variable || Default || Description
|-
| @btnBackground || @white
|-
| @btnBackgroundHighlight || darken(@white, 10%)
|-
| @btnBorder || #bbb
|-
| @btnPrimaryBackground || @linkColor
|-
| @btnPrimaryBackgroundHighlight || spin(@btnPrimaryBackground, 20%)
|-
| @btnInfoBackground || #5bc0de
|-
| @btnInfoBackgroundHighlight || #2f96b4
|-
| @btnSuccessBackground || #62c462
|-
| @btnSuccessBackgroundHighlight || #51a351
|-
| @btnWarningBackground || lighten(@orange, 15%)
|-
| @btnWarningBackgroundHighlight || @orange
|-
| @btnDangerBackground || #ee5f5b
|-
| @btnDangerBackgroundHighlight || #bd362f
|-
| @btnInverseBackground || #444
|-
| @btnInverseBackgroundHighlight || @grayDarker
|}

=== Dropdowns ===

{|
! Variable || Default || Description
|-
| @dropdownBackground || @white
|-
| @dropdownBorder || rgba(0,0,0,.2)
|-
| @dropdownDividerTop || #e5e5e5
|-
| @dropdownDividerBottom || @white
|-
| @dropdownLinkColor || @grayDark
|-
| @dropdownLinkColorHover || @white
|-
| @dropdownLinkColorActive || @white
|-
| @dropdownLinkBackgroundActive || @linkColor
|-
| @dropdownLinkBackgroundHover || @dropdownLinkBackgroundActive
|}

=== Foldertree ===
{|
! Variable || Default || Description
|-
| @foldertreeSidepanelBackground || #333 ||
|-
| @foldertreeSectionTitleColor || #888 || Color for sectiontitles in foldertree (like "Public" folders)
|-
| @foldertreeActiveLabelColor || #ccc || ''Active'' means, user can perform an action on this item
|-
| @foldertreePassiveLabelColor || #ccc || ''Passive'' means, user can '''not''' perform any action with this item
|-
| @foldertreeHoverBackground || #888 ||
|-
| @foldertreeSelectedBackground || #222 ||
|-
| @foldertreeBadgeBackground || @bagdeBackground || see [[#Colors]] for definition of @badgeBackground
|-
| @foldertreeBadgeColor ||@badgeColor || see [[#Colors]] for definition of @badgeBackground
|}

=== Calendar ===
==== Appointment ====
{|
! Variable || Default || Description
|-
| @appointmentReserved || #08c /* blue */ || Appointment status color
|-
| @appointmentTemporary || #ffbb00 /* yellow */ || Appointment status color
|-
| @appointmentAbsent || #913f3f /* red */ || Appointment status color
|-
| @appointmentFree || #8eb360 /* green */ || Appointment status color
|-
| @appointmentPrivate || #555 /* gray */ || Appointment status color
|-
| @appointmentDeclinedFont || #888 /* dark gray */|| Font color for declined Appointments
|-
| @appointmentUnconfirmedAlpha || 0.4 || Transparency value for unconfirmed Appointments
|-
| @appointmentDeclinedAlpha || 0.3 || Transparency value for declined Appointments
|-
| @appointmentHoverPct || 15% || Percentage increase of the dark pigment content on hover effect
|}

==== Week View ====
{|
! Variable || Default || Description
|-
| @weekviewAppointmentLasso || #aeaeff || Lasso frame color
|-
| @weekviewDayIn || #fff /* white */ || Default background color in week view
|-
| @weekviewDayOut || #e0e0e0 /* grey */ || Background color outside of the mean working time
|-
| @weekviewTimeline || #f00 /* red */ || Color of the Line indicating the current time
|-
| @weekviewTimeWith || 58px || With of the time labels on the left side
|-
| @calendarToolbarHeight || 41px || Height of the control toolbar
|}

==== Month View ====
{|
! Variable || Default || Description
|-
| @monthviewAppointmentOut || #aaa /* light gray */ || Color of appointments, which are not in focus
|-
| @monthviewToday || #daefff /* light blue */|| Background color of the current day
|-
| @calendarToolbarHeight || 41px || Height of the control toolbar
|}

== 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-11T08:08:46Z

David.bauer: /* Font */

{{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) || Default (7.4.x)
|-
| @font-family-sans-serif || @sansFontFamily || "Helvetica Neue", Helvetica, Arial, sans-serif || "Helvetica Neue", Helvetica, Arial, sans-serif
|-
| @font-family-serif || @serifFontFamily || Georgia, "Times New Roman", Times, serif || Georgia, "Times New Roman", Times, serif
|-
| @font-family-monospace || @monoFontFamily || Monaco, Menlo, Consolas, "Courier New", monospace || Monaco, Menlo, Consolas, "Courier New", monospace
|-
| @font-size-base || @baseFontSize || 14px || 14px
|-
| N/A || @baseFontFamily || N/A || @sansFontFamily
|-
| @line-height-base || @baseLineHeight || 1.428571429; // 20/14 || 20px
|-
| N/A || @altFontFamily || N/A || @serifFontFamily
|-
| @font-size-touch || @touchFontSize || 15px || 15px
|-
| @headings-font-family || @headingsFontFamily || inherit || inherit
|-
| @headings-font-weight || @headingsFontWeight || 500 || bold
|-
| @font-size-large || @fontSizeLarge || ceil((@font-size-base * 1.25)); // ~18px || @baseFontSize * 1.25
|-
| @font-size-small || @fontSizeSmall || ceil((@font-size-base * 0.85)); // ~12px || @baseFontSize * 0.85
|-
| N/A || @fontSizeMini || N/A || @baseFontSize * 0.75
|-
| @vgrid-font-size || @vgridFontSize || 13px || 13px
|}

==== Colors ====

{|
! Variable || Default || Description
|-
| @bodyBackground || @white
|-
| @textColor || @grayDark
|-
| @linkColor || #08c
|-
| @linkColorHover || darken(@linkColor, 15%)
|-
| @linkAccentColor || #ffad00
|-
| @linkAccentColorHover || darken(@linkAccentColor, 15%)
|-
| @badgeColor || @white
|-
| @badgeBackground || #555
|-
| @headingsColor || inherit
|-
| @black || #000
|-
| @grayDarker || #222
|-
| @grayDark || #333
|-
| @gray || #555
|-
| @grayLight || #aaa
|-
| @grayLighter || #eee
|-
| @white || #fff
|-
| @blue || darken(#049cdb, 5%)
|-
| @blueDark || #0064cd
|-
| @blueLight || lighten(#049cdb, 25%)
|-
| @green || #1A8D1A
|-
| @greenLight || #92D050
|-
| @red || #cc0000
|-
| @yellow || #F8E400
|-
| @orange || #f89406
|-
| @pink || #E01CD9
|-
| @purple || #7E16CF
|-
|}

==== Space ====

{|
! Variable || Default || Description
|-
| @paddingLarge || 11px 19px
|-
| @paddingSmall || 2px 10px
|-
| @paddingMini || 0 6px
|-
| @baseBorderRadius || 4px
|-
| @borderRadiusLarge || 6px
|-
| @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 || Default || Description
|-
| @paginationBackground || #fff
|-
| @paginationBorder || #ddd
|-
| @paginationActiveBackground || #f5f5f5
|}

=== Buttons ===

{|
! Variable || Default || Description
|-
| @btnBackground || @white
|-
| @btnBackgroundHighlight || darken(@white, 10%)
|-
| @btnBorder || #bbb
|-
| @btnPrimaryBackground || @linkColor
|-
| @btnPrimaryBackgroundHighlight || spin(@btnPrimaryBackground, 20%)
|-
| @btnInfoBackground || #5bc0de
|-
| @btnInfoBackgroundHighlight || #2f96b4
|-
| @btnSuccessBackground || #62c462
|-
| @btnSuccessBackgroundHighlight || #51a351
|-
| @btnWarningBackground || lighten(@orange, 15%)
|-
| @btnWarningBackgroundHighlight || @orange
|-
| @btnDangerBackground || #ee5f5b
|-
| @btnDangerBackgroundHighlight || #bd362f
|-
| @btnInverseBackground || #444
|-
| @btnInverseBackgroundHighlight || @grayDarker
|}

=== Dropdowns ===

{|
! Variable || Default || Description
|-
| @dropdownBackground || @white
|-
| @dropdownBorder || rgba(0,0,0,.2)
|-
| @dropdownDividerTop || #e5e5e5
|-
| @dropdownDividerBottom || @white
|-
| @dropdownLinkColor || @grayDark
|-
| @dropdownLinkColorHover || @white
|-
| @dropdownLinkColorActive || @white
|-
| @dropdownLinkBackgroundActive || @linkColor
|-
| @dropdownLinkBackgroundHover || @dropdownLinkBackgroundActive
|}

=== Foldertree ===
{|
! Variable || Default || Description
|-
| @foldertreeSidepanelBackground || #333 ||
|-
| @foldertreeSectionTitleColor || #888 || Color for sectiontitles in foldertree (like "Public" folders)
|-
| @foldertreeActiveLabelColor || #ccc || ''Active'' means, user can perform an action on this item
|-
| @foldertreePassiveLabelColor || #ccc || ''Passive'' means, user can '''not''' perform any action with this item
|-
| @foldertreeHoverBackground || #888 ||
|-
| @foldertreeSelectedBackground || #222 ||
|-
| @foldertreeBadgeBackground || @bagdeBackground || see [[#Colors]] for definition of @badgeBackground
|-
| @foldertreeBadgeColor ||@badgeColor || see [[#Colors]] for definition of @badgeBackground
|}

=== Calendar ===
==== Appointment ====
{|
! Variable || Default || Description
|-
| @appointmentReserved || #08c /* blue */ || Appointment status color
|-
| @appointmentTemporary || #ffbb00 /* yellow */ || Appointment status color
|-
| @appointmentAbsent || #913f3f /* red */ || Appointment status color
|-
| @appointmentFree || #8eb360 /* green */ || Appointment status color
|-
| @appointmentPrivate || #555 /* gray */ || Appointment status color
|-
| @appointmentDeclinedFont || #888 /* dark gray */|| Font color for declined Appointments
|-
| @appointmentUnconfirmedAlpha || 0.4 || Transparency value for unconfirmed Appointments
|-
| @appointmentDeclinedAlpha || 0.3 || Transparency value for declined Appointments
|-
| @appointmentHoverPct || 15% || Percentage increase of the dark pigment content on hover effect
|}

==== Week View ====
{|
! Variable || Default || Description
|-
| @weekviewAppointmentLasso || #aeaeff || Lasso frame color
|-
| @weekviewDayIn || #fff /* white */ || Default background color in week view
|-
| @weekviewDayOut || #e0e0e0 /* grey */ || Background color outside of the mean working time
|-
| @weekviewTimeline || #f00 /* red */ || Color of the Line indicating the current time
|-
| @weekviewTimeWith || 58px || With of the time labels on the left side
|-
| @calendarToolbarHeight || 41px || Height of the control toolbar
|}

==== Month View ====
{|
! Variable || Default || Description
|-
| @monthviewAppointmentOut || #aaa /* light gray */ || Color of appointments, which are not in focus
|-
| @monthviewToday || #daefff /* light blue */|| Background color of the current day
|-
| @calendarToolbarHeight || 41px || Height of the control toolbar
|}

== 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:GettingStartedWithGrunt

2014-03-12T13:54:09Z

David.bauer: /* Grunt & Bower */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

If you are having problems or your package manager does not provide at least nodejs in version 0.10.x please have at https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.

''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

'''Mac OS X / Windows:'''
<pre>
npm install -g bower grunt-cli
</pre>

'''Linux ''only'':'''
You may need root privileges to install global npm modules.
<pre>
sudo npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

== Accessing the UI ==

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

You can now access the ui via <tt>http://localhost:8337/appsuite/</tt>.

AppSuite:GettingStartedWithGrunt

2014-03-10T13:36:14Z

David.bauer: /* appserver */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.

''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

== Accessing the UI ==

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

You can now access the ui via <tt>http://localhost:8337/appsuite/</tt>.

AppSuite:GettingStartedWithGrunt

2014-03-10T13:33:59Z

David.bauer:

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.

''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

== appserver ==

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

You can now access the frontend via <tt>http://localhost:8337/appsuite/</tt>.

AppSuite:GettingStartedWithGrunt

2014-03-10T13:24:41Z

David.bauer: /* Windows */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.

''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:24:33Z

David.bauer: /* Windows */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.
''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:23:00Z

David.bauer: /* Installing node dependencies for OX Appsuite Frontend development */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

<pre>
npm install
</pre>

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:19:46Z

David.bauer: /* Local configuration */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

<pre>
cp grunt/local.conf.default.json grunt/local.conf.json
vi grunt/local.conf.json
</pre>

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:18:47Z

David.bauer: /* Local configuration */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<pre>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</pre>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:17:08Z

David.bauer: /* Building the UI */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

<pre>
grunt
</pre>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:16:34Z

David.bauer: /* Grunt & Bower */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

<pre>
npm install -g bower grunt-cli
</pre>

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:09:09Z

David.bauer:

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task:

<pre>
grunt connect:server:keepalive
</pre>

or in combination with the watch task:

<pre>
grunt connect watch
</pre>

AppSuite:GettingStartedWithGrunt

2014-03-10T13:03:31Z

David.bauer: /* Mac OS X */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].

Make sure you have an up-to-date homebrew installation.

<pre>
brew update
brew upgrade
</pre>

Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

<pre>
brew doctor
</pre>

Install node via <tt>brew install node</tt> if is not yet installed.

<pre>
brew install node
</pre>

Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:GettingStartedWithGrunt

2014-03-10T12:58:10Z

David.bauer: /* Mac OS X */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:GettingStartedWithGrunt

2014-03-10T12:57:28Z

David.bauer: /* Mac OS X */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.

<pre>
ulimit -n 8192
</pre>

or you can set
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>

<pre>
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
</pre>

''Note that you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:GettingStartedWithGrunt

2014-03-10T12:50:12Z

David.bauer: /* Mac OS X */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
it permanently by adding

<tt>limit maxfiles 8192 20480</tt>

to <tt>/etc/launchd.conf</tt>

''Note that this file may need to be created if it does not exist and you will have to restart your system for the setting to be active.''

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:Changes

2014-03-10T12:46:58Z

David.bauer:

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

For further information please see our [[AppSuite:GettingStartedWithGrunt | Getting Started with grunt]] guide.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

'''Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.'''

''However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team.''

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io here].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

'''Hint:''' Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

'''Note:''' We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

'''Note:''' In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:GettingStartedWithGrunt

2014-03-10T11:58:51Z

David.bauer: /* appserver */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
it permanently by adding

<tt>limit maxfiles 8192 20480</tt>

to <tt>/etc/launchd.conf</tt>.

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
"appserver": {
"server": "http://url.to.your.ser/appsuite/",
"verbose": ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:GettingStartedWithGrunt

2014-03-10T11:57:44Z

David.bauer: /* appserver */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
it permanently by adding

<tt>limit maxfiles 8192 20480</tt>

to <tt>/etc/launchd.conf</tt>.

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
appserver: {
server: "http://url.to.your.ser/appsuite/",
verbose: ["local:error"]
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:GettingStartedWithGrunt

2014-03-10T11:45:08Z

David.bauer: /* appserver */

<div class="title">Getting started with grunt</div>
__TOC__
== Node ==

=== Linux ===

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

=== Windows ===

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

=== Mac OS X ===

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt> and resolved any issues remaining.

Install node via <tt>brew install node</tt> or run <tt>brew upgrade</tt> if you already have node installed.

Make sure you '''don't <tt>sudo</tt> anything related to node'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
it permanently by adding

<tt>limit maxfiles 8192 20480</tt>

to <tt>/etc/launchd.conf</tt>.

== Grunt & Bower ==

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

== Cleaning development environment ==

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.

== Installing node dependencies for OX Appsuite Frontend development ==

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

== Building the UI ==

Just run the default grunt task <tt>grunt</tt>

== Local configuration ==

You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.

Hint: copy the default file to <tt>grunt/local.conf.json</tt> to get started.

=== appserver ===

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

<code>
{
appserver: {
server: 'http://url.to.your.ser/appsuite/',
verbose: ['local:error']
}
}
</code>

You can run the appserver with the connect grunt task: <tt>grunt connect:server:keepalive</tt> or in combination with the watch task: <tt>grunt connect watch</tt>

AppSuite:Changes

2014-02-25T13:41:59Z

David.bauer:

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

'''Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.'''

''However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team.''

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io here].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

'''Hint:''' Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

'''Note:''' We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

'''Note:''' In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:Changes

2014-02-25T13:33:31Z

David.bauer: /* Bower */

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

'''Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.'''

''However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team.''

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io here].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

'''Hint:''' Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

**Note: We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.**

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

**Note: In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.**

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:Changes

2014-02-25T13:32:52Z

David.bauer:

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

'''Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.'''

''However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team.''

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

'''Hint:''' Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

**Note: We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.**

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

**Note: In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.**

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:Changes

2014-02-25T13:32:15Z

David.bauer: /* Underscore.js */

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

**Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.**

_However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team._

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

'''Hint:''' Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

**Note: We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.**

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

**Note: In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.**

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:Changes

2014-02-25T13:31:04Z

David.bauer: /* Bootstrap */

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

**Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.**

_However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team._

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

**Hint: Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.**

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

**Note: We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.**

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/migration/ Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

**Note: In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.**

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:Changes

2014-02-25T13:30:35Z

David.bauer:

<div class="title">Changes</div>

== 7.6.0 ==

=== grunt ===
grunt has superseded jake as a build system. In this section all changes will be described.

Instead of a shell wrapper around jake (the `build-appsuite` script), grunt should now be invoked
directly. The recommended workflow will be described in the next subsections, where all tasks relevant
for development will be explained in detail.

Grunt is a well documented task-runner (see http://gruntjs.com) and there is a large community writing plugins.
Unless stated otherwise, we implemented standard grunt behaviour and rely on best-practice introduced by the
grunt community.

==== local configuration ====
All local configuration is now done in `grunt/local.conf.json` using the JSON format. This replaces
the `local.conf` file, that was sourced into build-appsuite shell script. This new way is more platform
independent.

=== appserver ===
The functionality of the appserver is now provided by the grunt-contrib-connect plugin. The `connect` task
should be run in conjunction with the `watch` task like this:

<pre>
grunt connect watch
</pre>

This will start the appserver middleware and start watching for changed files. In case you don't want this
behaviour, you have to start the `connect` task with the keepalive option (as documented in grunt-contrib-connect documentation):

<pre>
grunt connect:server:keepalive
</pre>

=== Bower ===
Most of our third party front-end libraries are now managed via bower. The location for these libraries has changed from lib/ to bower_components/. These files will be handled when building by the new grunt build system and copied or concatinated accordingly.

**Warning: Manual editing/patching/hacking files in "bower_components/" is deprecated.**

_However if you are positive that there is a bug in one of these libraries a possible course of action would be to fork the package on github and commit your patch there and create an upstream pull request, in any case this should be handled by the frontend team._

An up-to-date list of packages maintained by bower can be reviewed in the bower.json file in the ui root.

* jquery
* underscore
* mediaelement
* bootstrap
* bootstrap-datepicker
* bootstrap-typeahead
* font-awesome
* open-sans-fontface
* backbone
* backbone-validation
* Chart.js
* bigscreen
* jquery-placeholder
* jquery-imageloader
* textarea-helper
* requirejs
* bootstrap-accessibility-plugin

Read more about bower [http://bower.io].

=== Require.js ===
Require.js updated from 2.1.8 to 2.1.11

We also changed the way style files are included in the require.js define() method.
less and css files are now defined in the same way as javascript files, WITHOUT its extension.

* less!io.ox/calendar/style.less => less!io.ox/calendar/style
* css!io.ox/calendar/style.css => css!io.ox/calendar/style

=== jQuery ===
jQuery was updated from 2.0.3 to 2.1.0

If you experience any issues please check [http://blog.jquery.com/2014/01/24/jquery-1-11-and-2-1-released/ this blogpost] for changes.

=== Underscore.js ===

Underscore was updated from Version 1.4.4 to Version 1.6

Please read the [http://underscorejs.org/#changelog changelog].

**Hint: Look for "Removed the ability to call _.bindAll with no method name arguments", this was pretty much the only issue we had whilst updating.**

=== Backbone.js ===

Backbone.js was updated from 0.9.x to Version 1.0.0

Please read the [http://backbonejs.org/#changelog changelog].

**Note: We currently cannot update to 1.1.2, which is the current version of backbone, but will do so in the near future, when we resolve our issues.**

=== Bootstrap ===

Bootstrap was updated from 2.2.2 to 3.1.1

Please read the [http://getbootstrap.com/getting-started/#migration Bootstrap 2 to Bootstrap 3 migration guide], as there are many significant changes, to markup and styles.

All bootstrap plugins and our core components have been updated accordingly.

**Note: In Bootstrap 3 the typeahead plugin was dropped in favor of Twitters typeahead.js. This change would break our current autocomplete functions, so we added the Bootstrap 3 Typeahead (https://github.com/bassjobsen/Bootstrap-3-Typeahead) for backwards-compatibility.**

See also changes for themes below.

=== Themes ===

We cleaned up definitions.less and removed duplicate and obsolete definitions. If you want to override specific bootstrap default values you can do so by overriding variables from "/bower_components/bootstrap/less/variables.less" in your themes definitions.less file.

Mixins were also removed from definitions and reside now in a seperate file "/apps/themes/mixins.less".

=== Font Awesome ===

Font Awesome was updated to it's latest version (4.0.3).
You can read about the changes [http://fortawesome.github.io/Font-Awesome/whats-new/ here].

These classes have been replaced in our core components:

* icon-align-justify => fa fa-align-justify
* icon-align-left => fa fa-align-left
* icon-angle-left => fa fa-angle-left
* icon-angle-right => fa fa-angle-right
* icon-archive => fa fa-archive
* icon-arrow-down => fa fa-arrow-down
* icon-arrow-up => fa fa-arrow-up
* icon-book => fa fa-book
* icon-bookmark => fa fa-bookmark
* icon-bookmark-empty => fa fa-bookmark-o
* icon-caret-down => fa fa-caret-down
* icon-caret-right => fa fa-caret-right
* icon-chevron-left => fa fa-chevron-left
* icon-chevron-right => fa fa-chevron-right
* icon-circle => fa fa-circle
* icon-circle-arrow-right => fa fa-circle-arrow-right
* icon-cloud-download => fa fa-cloud-download
* icon-cog => fa fa-cog
* icon-collapse-alt => fa fa-minus-square-o
* icon-comment-alt => fa fa-comment-o
* icon-download-alt => fa fa-download
* icon-edit => fa fa-edit
* icon-envelope => fa fa-envelope
* icon-envelope-alt => fa fa-envelope-o
* icon-exclamation => fa fa-exclamation
* icon-expand-alt => fa fa-plus-square-o
* icon-external-link => fa fa-external-link
* icon-external-link-sign => fa fa-external-link-square
* icon-eye-open => fa fa-eye
* icon-file => fa fa-file
* icon-film => fa fa-film
* icon-folder-close => fa fa-folder
* icon-folder-open => fa fa-folder-open
* icon-gear => fa fa-cog
* icon-group => fa fa-group
* icon-list-alt => fa fa-list-alt
* icon-lock => fa fa-lock
* icon-magic => fa fa-magic
* icon-mail-forward => fa fa-mail-forward
* icon-minus-sign => fa fa-minus-circle
* icon-music => fa fa-music
* icon-ok => fa fa-check
* icon-paper-clip => fa fa-paperclip
* icon-pencil => fa fa-pencil
* icon-picture => fa fa-picture-o
* icon-play => fa fa-play
* icon-plus-sign => fa fa-plus-circle
* icon-print => fa fa-print
* icon-qrcode => fa fa-qrcode
* icon-question-sign => fa fa-question-circle
* icon-refresh => fa fa-refresh
* icon-remove => fa fa-times
* icon-remove-circle => fa fa-times-circle
* icon-reorder => fa fa-bars
* icon-reply => fa fa-reply
* icon-resize-full => fa fa-expand
* icon-retweet => fa fa-retweet
* icon-rss => fa fa-rss
* icon-search => fa fa-search
* icon-shopping-cart => fa fa-shopping-cart
* icon-signin => fa fa-sign-in
* icon-spin => fa fa-spin
* icon-star => fa fa-star
* icon-table => fa fa-table
* icon-tag => fa fa-tag
* icon-th => fa fa-th
* icon-th-large => fa fa-th-large
* icon-th-list => fa fa-th-list
* icon-tint => fa fa-tint
* icon-trash => fa fa-trash-o
* icon-unlock => fa fa-unlock
* icon-user => fa fa-user

=== TinyMCE ===

TinyMCE was updated from 3.4.7 to 3.5.10.

AppSuite:GettingStartedWithGrunt

2014-02-24T15:02:52Z

David.bauer: Created page with "= Getting started with grunt = == Prerequisites == === Node === ==== Linux ==== Install the default nodejs of your distribution via your favourite package/ports manager an..."

= Getting started with grunt =

== Prerequisites ==

=== Node ===

==== Linux ====

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

==== Windows ====

Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
It is recommended to restart after the installation, as paths may not be up-to-date.

==== Mac OS X ====

We strongly encourage you to use [http://brew.sh/ homebrew].
Make sure you have checked your homebrew installation with <tt>brew doctor</tt>.

Install node via <tt>brew install node</tt>.

Make sure you don't <tt>sudo</tt> anything related to node. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
it permanently by adding

<tt>limit maxfiles 8192 20480</tt>

to <tt>/etc/launchd.conf</tt>.

=== Grunt & Bower ===

With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.

=== Installing node dependencies for OX Appsuite Frontend development ===

Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.

AppSuite:RunTests

2013-09-13T13:28:25Z

David.bauer:

{{Stability-experimental}}
<div class="title">Running the ui tests</div>

__TOC__

This article explains the test system of the frontend. It is aimed at developers that want to work with the frontend, be it creating new plugins or applications or modifying existing code using BDD. Bringing a BDD testing infrastructure to the frontend is still a work in progress and subject to (breaking) changes. Please contribute to the stability by reporting any issues or ideas to [[User:J.ohny.b|me]].

== Libraries ==

* [http://pivotal.github.io/jasmine/ Jasmine] - JS BDD framework
* [http://sinonjs.org/ Sinon.JS] - Standalone test spies, stubs and mocks for JavaScript.
* [http://karma-runner.github.io/ Karma Runner] - test runner

== Setting up your system ==

You need at least ''node'' version 0.8 to use the latest version of ''karma'', which we need. To install the (latest stable version of) karma runner, run

npm install -g karma

in a shell. You might need admin rights to do that, use ''sudo'' if needed.

If you have karma installed already you may have to run

npm -g update

at least once, if the karma dependencies fail at least 2 times.

After that you may have to add the path to your node modules to the ''local.conf'' file.

export NODE_PATH="/usr/local/lib/node_modules:/usr/local/share/npm/lib/node_modules:$NODE_PATH"

== Running the tests ==

Running the tests is pretty easy. For now, in the ''ui'' directory of your sources start the karma server with this jake task

./build.sh testserver

After that, open up a browser and point it to http://localhost:9876/.

If you don’t want to use the appserver proxy but your own backend, you need to adjust the proxies section in your ''ui/karma.conf.js''. The appserver or a running backend won’t be needed in the future.

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Development process]]

AppSuite:Supported file types

2013-07-08T11:25:23Z

David.bauer: /* Mediaplayer */

AppSuite allows you to preview, view and edit files. A common question is what files are supported. The following list is not definitive

== Mediaplayer ==
The AppSuite "media player" uses the native html 5 video playback of each browser. The actual file support depends on the user's browser, so a definitive list can not be given. Here is an attempt:

=== Video ===

* Chrome: m4v, ogv, webm
* Safari: m4v
* IE: m4v
* Firefox: ogv, webm

=== Audio ===

For audio files a flash/silverlight fallback is used if a browser is not capable of native mp3 playback like Firefox.

* Chrome: mp3, wav, m4a, m4b, ogg
* Safari: mp3, wav, m4a, m4b, aac
* IE: mp3, wav, m4a, m4b
* Firefox: mp3, wav, ogg

== Preview ==
* pdf
* docx
* odt
* xlsx

== Documents ==
* docx
* odt

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Server]]

AppSuite:Supported file types

2013-07-08T11:20:53Z

David.bauer: /* Mediaplayer */

AppSuite allows you to preview, view and edit files. A common question is what files are supported. The following list is not definitive

== Mediaplayer ==
The AppSuite "media player" technically consists of several technologies stacked onto each other that serve as fallbacks. Most of them depend on the user's system setup, so a definitive list can not be given. Here is an attempt:

=== Video ===

* Chrome: m4v, ogv, webm
* Safari: m4v
* IE: m4v
* Firefox: ogv, webm

=== Audio ===

* Chrome: mp3, wav, m4a, m4b, ogg
* Safari: mp3, wav, m4a, m4b, aac
* IE: mp3, wav, m4a, m4b
* Firefox: mp3, wav, ogg

== Preview ==
* pdf
* docx
* odt
* xlsx

== Documents ==
* docx
* odt

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Server]]

AppSuite:Supported file types

2013-07-08T11:19:21Z

David.bauer: /* Mediaplayer */

AppSuite allows you to preview, view and edit files. A common question is what files are supported. The following list is not definitive

== Mediaplayer ==
The AppSuite "media player" technically consists of several technologies stacked onto each other that serve as fallbacks. Most of them depend on the user's system setup, so a definitive list can not be given. Here is an attempt:

* Chrome: m4v, ogv, webm
* Safari: m4v
* IE: m4v
* Firefox: ogv, webm

== Preview ==
* pdf
* docx
* odt
* xlsx

== Documents ==
* docx
* odt

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Server]]

AppSuite:UI remote debugging android mac

2013-06-24T12:46:36Z

David.bauer: Created page with "{{Stability-experimental}} <div class="title">How to setup remote debugging for chrome on android devices with a mac</div> ==Prerequisites== You need the latest X-Code and ..."

{{Stability-experimental}}

<div class="title">How to setup remote debugging for chrome on android devices with a mac</div>

==Prerequisites==

You need the latest X-Code and a working setup of the latest Homebrew. Check with <tt>brew doctor</tt>.

==Setup==
<pre>
$ brew install android-sdk
</pre>
Add this to your shells rc (e.g. .bashrc or .zshrc)
<pre>
export ANDROID_HOME=/usr/local/opt/android-sdk
</pre>

Launch the "Android SDK Manager".
<pre>
$ android
</pre>
Check <tt>Android SDK Platform-tools</tt> and <tt>Android Support Library</tt> uncheck everything else, except if you plan on using other components of the SDK.

Add this to your shells rc (e.g. .bashrc or .zshrc) for convenience:

<pre>
alias chrome-android="adb forward tcp:9222 localabstract:chrome_devtools_remote"
</pre>

==Usage==

Connect an Android Device via USB.

Open a terminal and enter "chrome-android".

Open Chrome on your device.

Visit <tt>localhost:9222</tt> on your desktop machine for remote debugging.

AppSuite:Mobile

2013-06-24T12:40:29Z

David.bauer: /* Remote Debugging */

{{Stability-experimental}}

<div class="title">Developing for mobile devices</div>

==Introduction==

App Suite is designed to work on all device types and sizes. The UI uses responsive design principles to scale nicely on each device size. We do define three display sizes to macht the majority of devices. These are simply named "small", "medium" and "large". Theses classes are used to match smartphones, tablets and desktop PCs. If you are developing a app for App Suite make sure it runs nicely and looks great on all of these three device categories. (If you are not familiar with latest CSS techniques and the principles of responsive design you should have a look at this [[AppSuite:UI_developer_primer | article]]).

Often the simple use of media queries is not enough to customize your app for small and medium screens, you may need to customize your application code as well. We have integrated a function to detect everything you might want to know during runtime in your javascript code.

==Sizes==

The minimum device target size is 320 x 480 pixels. Your App should work on devices with this resolution.

{| border=1
|-
|small || up to 480px
|-
|medium || 481px up to 1024px
|-
|large || 1025px and higher
|}

==The _.device function==

We extended underscore with a new function called <tt>_.device</tt>

The <tt>_.device()</tt> function can be used to retrieve informations about the device. The function takes a string as argument which contains a boolean expression. This expression will be evaluated and the result is returned as a boolean.

The device function uses <tt>_.browser</tt> object for informations in combination with <tt>_.screenInfo</tt>

==Examples for _.device==
<pre class="language-javascript">
// handle different mobile operating systems
if (_.device('ios')) {
// true for all devices running iOS, no matter what version
console.log('you are running iOS');
}

// combined statements
if (_.device('ios && android')) {
// true for all android and iOS devices
}

// negation
if (_.device('!android')) {
// true for all devices except android
}

// screen information
if (_.device('small && iOS ')) {
// true for iPhone, not for iPad
}

// shorthands
_.device('smartphone')
// true for small devices running a mobile OS (iOS, Android, BB or Windowsphone)

_.device('tablet')
// true for medium sized devices running a mobile OS

_.device('desktop')
// true for all devices not running a mobile OS

// getting version informations
_.device('ios > 5 || android > 4')
// true for ios > 5, i.e. 5.1 and 6. Same for Android, 4.0 will fail 4.1 or 4.2 will be true.

// enhanced screen information
_.device('iOS && retina && small')
// true for iPhone 4, 4s and 5 (retina display)

_.device('landscape && android && medium')
// true for android tablet held in landscape mode

// other information, simple browser detection
_.device('safari || firefox')

</pre>

Please note that information about device orientation may change during usage.

==Mobile considerations==

As of today mobile usage has become much more important than some years ago. Always consider the the fact a user may want to use your App on a smartphone. So, optimizing for mobile should not be last step in your development process, it should be one of the first. This will safe you a lot of painful debugging and layout fixes.

You should ask you a simple question: Does function X in my App do have a mobile use case? Or more simple: Will anybody use this on a smartphone?
If not, disable or remove this function on a mobile device. Nobody will perform a complex 35-click action in your App on a smartphone.

Developing for mobile should follow some simple rules:
* Mobile phones do have small screens. Safe space in your layout, reduce margins and paddings.
* Touch is not click, keep buttons and links big enough to be touchable. 40px should be a minium.
* Mobile networks are slow and have a high latency. Safe network requests and handle failing requests properly
* Mobile devices are not as fast as desktop PCs. Not everybody has a high end smartphone so keep your code clean and fast
* Always test your App on a real device

==Remote Debugging==

[[AppSuite:UI_remote_debugging_android_mac | How to setup remote debugging for Chrome on android devices with a mac.]]

AppSuite:Mobile

2013-06-24T11:33:24Z

David.bauer:

AppSuite:Media player

2013-04-17T09:29:40Z

David.bauer: /* How to enable/disable the mediaplayer */

<div class="title">Mediaplayer</div>

__TOC__

==Browser and OS support==
We use mediaelement.js[http://mediaelementjs.com/] as HTML5 media player, which has a flash and silverlight fallback.

Every Browser supports a different set of supported codecs and container formats, follow this link to see which ones: http://mediaelementjs.com/#devices

==How to enable/disable the mediaplayer==

<tt>settings!io.ox/files</tt>

<tt>audioEnabled [true|false]</tt>

AppSuite:Media player

2013-04-17T09:28:52Z

David.bauer: Created page with "<div class="title">Mediaplayer</div> __TOC__ ==Browser and OS support== We use mediaelement.js[http://mediaelementjs.com/] as HTML5 media player, which has a flash and silve..."

AppSuite:UI

2013-04-17T09:15:33Z

David.bauer: /* How-to articles */

<div class="title">AppSuite UI</div>
This page contains articles about the inner workings of the UI.
It is aimed at software developers that want to improve on existing features, implement extensions or just gain a general understanding.

== Getting started ==
* [[AppSuite:UI developer primer| Skills needed to develop the UI]]
* [[AppSuite:Getting started developing the UI | Getting started developing the UI]]
* [[AppSuite:UI_Development_Style_Guide | UI Development Style Guide]]
* [[AppSuite:Apache Configuration | Apache Configuration]]

== How-to articles ==
* [[AppSuite:Date_and_time|Date and time]]
* Extension points:
** [[AppSuite:Extending_the_UI_(Hands-on_introduction)| Hands-on introduction]]
** [[AppSuite:Extending_the_UI | General information on extension points]]
** [[AppSuite:Modifying forms by using extension points | Modifying forms]]
* [[AppSuite:Files App Actions|Adding actions to the files app]]
* [[AppSuite:i18n | Internationalization (i18n)]]
* [[AppSuite:Theming | Theming]]
* [[AppSuite:Upsell | Upsell]]
* [[AppSuite:Writing a portal plugin | Writing a portal plugin]]
* [[AppSuite:Writing a simple application | Writing a simple application]]
* [[AppSuite:Writing a notification area plugin | Writing a plugin for the notification area]]
* [[AppSuite:UI manifests explained | UI manifests explained]] - Vik, Cisco?
* [[AppSuite:VGrid | VGrid]]
* [[AppSuite:Mediaplayer | Mediaplayer]]

== Miscellaneous articles ==
* [[AppSuite:External libraries for the UI | External libraries used by the UI]]
* [[AppSuite:UI build system| The UI build system]]
* All articles regarding the UI are filed in the category [[:Category:UI]]

[[Category:Ui]][[Category:AppSuite]][[Category:Overview]]

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

2013-04-12T11:32:33Z

David.bauer: /* Adding a Sidepopup */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
/* simple helper to trigger some events
normally this is done by mailapi, taskapi, etc. */
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which, in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:31:55Z

David.bauer: /* Registering your 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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
/* simple helper to trigger some events
normally this is done by mailapi, taskapi, etc. */
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:31:48Z

David.bauer: /* Creating the View */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
/* simple helper to trigger some events
normally this is done by mailapi, taskapi, etc. */
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:31:40Z

David.bauer: /* Adding the headline */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
/* simple helper to trigger some events
normally this is done by mailapi, taskapi, etc. */
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:31:27Z

David.bauer: /* Triggering the events */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
/* simple helper to trigger some events
normally this is done by mailapi, taskapi, etc. */
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:31:10Z

David.bauer: /* Helper functions */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/* fill our collection of notification models with new ones
items here is an array of Objects containing our attributes */
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:30:52Z

David.bauer: /* Helper functions */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
/*
fill our collection of notification models with new ones
items here is an array of Objects containing our attributes
*/
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:30:21Z

David.bauer: /* Helper functions */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
//fill our collection of notification models with new ones
//items here is an array of Objects containing our attributes
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:30:02Z

David.bauer: /* Listen for events */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
//fill our collection of notification models with new ones
//items here is an array of Objects containing our attributes
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:29:38Z

David.bauer: /* Drawing the 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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
//fill our collection of notification models with new ones
//items here is an array of Objects containing our attributes
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:29:25Z

David.bauer: /* Adding a Sidepopup */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
//fill our collection of notification models with new ones
//items here is an array of Objects containing our attributes
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

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

2013-04-12T11:29:14Z

David.bauer: /* Adding a Sidepopup */

<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__

==Preparations==

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

Now add a new file to your folder and name it ''register.js'' .
Then add the basic markup such as copyright, define for ''require.js'', use strict and so on.
In our tutorial the result looks like this.

<pre class="language-javascript">
/**
* your copyright here
* @author Mister Test <mister.test@test.test>
*/

define('plugins/notifications/tutorial/register',
['io.ox/core/extensions'], function (ext) {

'use strict';

//just to give something back
return true;
});
</pre>

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

===Manifests===

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

<pre class="language-javascript">

{
namespace: "io.ox/core/notifications"
}
</pre>

For developing add the following code to ''src/manifests.js''

<pre class="language-javascript">
{
namespace: ['io.ox/core/notifications'],
path: 'plugins/notifications/tutorial/register'
}
</pre>

For further information about manifests look [[AppSuite:UI manifests explained|here]].

==Coding the base==
===Registering your plugin===

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

<pre class="language-javascript">
//register our notification plugin
ext.point('io.ox/core/notifications/register').extend({
id: 'tutorial',//unique id
index: 500, //unused index
register: function (controller) {
//give our plugin a name and send it to the controller together with our view
var notifications = controller.get('io.ox/tutorial', NotificationsView);
}
});
</pre>

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

===Creating the View===

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

<pre class="language-javascript">
//the view of our plugin
var NotificationsView = Backbone.View.extend({

className: 'notifications',
id: 'io-ox-notifications-tutorial',

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

<pre class="language-javascript">
//the header and container for the notification plugin
ext.point('io.ox/core/notifications/tutorial/header').extend({
draw: function (baton) {
this.append(
$('<legend class="section-title">').text('Hello World'),//header
$('<div class="notifications">')//the container for our notifications
);
}
});
</pre>

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

==First testing==

Now we want to see how it looks in the program.
To do this add this line of code to your register method:

<pre class="language-javascript">
notifications.collection.reset(new Backbone.Model());
</pre>

This creates an empty notification model and adds it to our plugins collection.
We get to know how this collection works later on, for now we just need something in it for the controller to think that there is a notification to display.

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

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

After it's loaded you should see something like this:

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

<pre class="language-javascript">
//simple helper to trigger some events
//normally this is done by mailapi, taskapi, etc.
var myEventTriggerer = {
lookForItems: function () {
//build some items and put them in an array
var items = [{title: 'I am a notification', description: 'Hello world!'},
{title: 'I am a notification too', description: 'Hooray!'}];
//trigger the event to add them
$(myEventTriggerer).trigger('set-tutorial-notification', [items]);
}
};
</pre>

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

===Helper functions===
Notifications are stored as backbone models in a collection of our view.
Or models have the attributes title and description. A cid is added automatically that we use to identify them later on. You can also give ids as normal attributes and use them if you want more control over it.
This collection is available in the register method under ''notifications.collection''.
The controller looks for changes in this collection and triggers a redraw.

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

<pre class="language-javascript">
//fill our collection of notification models with new ones
//items here is an array of Objects containing our attributes
function reset(e, items) {
var models = [];
items = [].concat(items);//make sure we have an array
_(items).each(function (item) {
models.push(new Backbone.Model(item));
});
notifications.collection.reset(models);//fill the collection
}
</pre>

This function simply loops over the array of items they are given, creates models from them and fills the collection with it. Reset means that the old models are gone now and only the new ones are in our collection.
Functions to add and remove models are done the same way but are not always needed, as in this example.

''Note: notifications.collection.add() does not trigger the add event. You need to do this manually, this seems to be a backbone issue.''

===Listen for events===

So now we need just listen to the event to launch our reset function and call our little dummy to fill our initial collection.
We do this by adding this code to the register method.

<pre class="language-javascript">
//now add the event listeners
$(myEventTriggerer).on('set-tutorial-notification', reset);

//just to make sure it gets filled with values on load we trigger our search method
myEventTriggerer.lookForItems();
</pre>

===Drawing the Notifications===
Now that we have proper models, we need to draw them.
To do this we do the same as with the header, create an extension point and invoke drawing.
In our views render method we need to add:

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which , in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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