Open-Xchange - User contributions [en]

AppSuite:Configuring portal plugins

2017-03-16T10:30:18Z

Frank.paczynski:

{{Stability-stable}}
{{VersionFrom|7.4.0}}

= Configuring portal plugins =

''Synopsis:'' This article covers how to configure which plugins ("tiles") are shown, whether they are mandatory or just suggested to the user.

__TOC__

== Configuring the portal ==

When running OX AppSuite you may want to specify a starting configuration for which tiles the portal shows and whether certain tiles are mandatory or not. This is especially useful when you are introducing your own tile implementations. To make this possible, the portal consists of three types of tiles: User tiles, eager tiles and protected tiles. User tiles are tiles that the user added herself to the portal page, eager tiles are those suggested by the installation which can be removed and protected tiles are set by the backend.

In order to specify a tile, you will have to know about the configuration data to enter. You can use an appsuite installation to do that. If you want to configure a tile as eager or protected, navigate to the settings area of the portal page, add the tile you want and, in the JS console, enter:

require("settings!io.ox/portal").get("widgets/user")

and in the list find the tile you want to suggest to or force on your users. As an example, we'll use the birthday widget:

birthdays_0: Object
color: "lightgreen"
enabled: true
id: "birthdays_0"
index: 6
inverse: false
plugin: "plugins/portal/birthdays/register"
props: Object
type: "birthdays"

In order to configure widgets on the backend we have to turn the above into a valid YAML structure:

birthdays_0:
color: "lightgreen" # one of black, red, orange, lightgreen,
# green, lightblue, blue, purple, pink, gray
enabled: true # Has to be true
index: "first" # Where the widget is supposed to show up.
# Possible values are numbers, "first" or
# "last"
inverse: false # If true, the color is applied to the body
# of the tile and not the title. Can highlight
# particular tiles
plugin: "plugins/portal/birthdays/register" # The source file that contains the tile code
type: "birthdays" # The id of the widget type. Not the id above
# has to have the form [type]_[someNumber]

Now we can use this snippet to configure the birthday widget in a variety of ways

== I want to suggest a widget, but the user can remove it, if they don't like it ==

For this, you can use the "eager" configuration method. Not that if you specify an eager or protected widget, all default widgets from Open-Xchange will not be configured as defaults anymore, so you might want to configure them as eager tiles as well. But let's stick to the birthday widget for now.

* Add a file /opt/open-xchange/etc/settings/portal.yml

io.ox/portal//widgets/eager/gen_0:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

This means the widget will be enabled for users, but users can still disable it. If you want to, at a later time and since you've made significant improvements to the tile, want to show it to the user again, you have to increase the "generation" of the widget configuration and offer it again:

io.ox/portal/:
generation: 1

io.ox/portal//widgets/eager/gen_0:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

io.ox/portal//widgets/eager/gen_1:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

All the "gen_[number]" entries up the tie io.ox/portal//generation will be used for this configuration. If a tile is deleted it is deleted only in that generation so can be reintroduced in a later portal configuration generation. If you want to keep the default tiles as used as a fallback for App Suite, you need this configuration to start out with:

io.ox/portal//widgets/eager/gen_0:
mail_0:
plugin: 'plugins/portal/mail/register'
color: 'blue'
enabled: true
index: 1
calendar_0:
plugin: 'plugins/portal/calendar/register'
color: 'red'
enabled: true
index: 2
tasks_0:
plugin: 'plugins/portal/tasks/register'
color: 'green'
enabled: true
index: 3
birthdays_0:
plugin: 'plugins/portal/birthdays/register'
color: 'lightgreen'
enabled: true
index: 4
twitter_0:
plugin: 'plugins/portal/twitter/register'
color: 'pink'
enabled: true
index: 5
linkedin_0:
plugin: 'plugins/portal/linkedin/register'
color: 'lightblue'
enabled: true
index: 6

And then modify this as wanted for your deployment

== Forcing a tile ==

Similarly to the eager tiles, tiles can be "protected", i.e. they can not be moved, removed and disabled. The configuration for this looks like that:

io.ox/portal//widgets/protected:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

If you want to allow movement of the widget, you can enable this in the following way:

io.ox/portal//widgets/protected:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"
changeable:
index: true

In which case, users will be allowed to move the tile.

One caveat in all this: After changing any of the above configuration, you will have to reload the UI *twice*, since App Suite uses read-through caching for the settings data.

== Disabling a tile completely ==
The combination of making a tile both protected and disabling it makes it impossible for the user to enable it. From 7.6.0 on, this means it is not shown in the settings either. Before that, it was greyed out but still present.

io.ox/portal/:
widgets:
protected:
quota_0:
color: "red"
id: "quota_0"
enabled: false
index: 1
inverse: false
plugin: "plugins/portal/quota/register"
type: "quota"

[[Category:Backend]][[Category:AppSuite]]

[[Category:Portal]]

[[Category:Administrator]][[Category:Developer]]

AppSuite:Guided tours

2016-05-03T09:46:54Z

Frank.paczynski:

'''Synopsis:''' Guided tours are series of little steps meant to explain the various functions of OX to an end user. They can be configured by system administrators.

__TOC__

== Basic framework ==
Guided tours are built on [https://github.com/linkedin/hopscotch LinkedIn's hopscotch.js] framework. It forms a series of small information "bubbles" that point to UI elements and display a text as well as small navigation elements.

== State before 7.4.1 ==
In 7.4.0, Guided Tours could not be configured.

== State after 7.4.1 ==
=== Package ===
Guided tours are contained in a separate package, named ''open-xchange-guidedtours''. This will install UI as well as backend components (in the form of a config file).

=== Configuration ===
Several configuration parameters guide the running of Guided Tours:

{|
|io.ox/tours//server/disableTours
|Disabled the tours completely
|-
|io.ox/tours//server/disable/$moduleName
| Disables the tour for a specific module, e.g. "io.ox/tasks"
|-
| io.ox/tours//server/startOnFirstLogin
| start the tour the first time a user logs in
|-
|io.ox/tours//server/version
|arbitrary integer denoting the version of the tour. If startOnFirstLogin is true, the user might have seen a previous version but not the recent one. Increasing the number makes sure the users sees the updated version again.
|}

=== Customizing ===
Tours use [[AppSuite:Extension points|extension points]] as mechanism to extend them. The relevant point is ''io.ox/tours/extensions''.

==== Example tour ====
A tours looks like this:
ext.point('io.ox/tours/extensions').extend({
id: 'default/io.ox/intro',
app: 'io.ox/intro',
priority: 1,
tour: {
id: 'Switching from OX6',
steps: [{
title: gt('Launching an app'),
placement: 'bottom',
target: function () { return $('.launcher[data-app-name="io.ox/mail"]')[0]; },
content: gt('To launch an app, click on an entry on the top-left side of the menu bar.')
},
{
onShow: function () { notifications.hideList(); },
title: gt('Displaying the help or the settings'),
placement: 'left',
target: function () { return $('.launcher .icon-cog:visible')[0]; },
content: gt('To display the help or the settings, use the icons on the right side of the menu bar.'),
arrowOffset: 1,
yOffset: -5
},
{
onShow: function () { notifications.showList(); },
title: gt('New objects icon'),
placement: 'left',
target: function () { return $('#io-ox-notifications-icon:visible')[0]; },
content: gt('The New objects icon shows the number of unread E-Mails or other notifications. If clicking the icon, the info area opens.'),
arrowOffset: -1
}, [...]

==== Components of a tour ====
A tours is a set of steps that are can be navigated by going forward and backwards. It needs...
{|
| id
| This needs to be unique, like for all extension points. Even if you want to overwrite another tour, you need a different id!
|-
| app
| The application this tour is related to.
|-
| Priority
| The tour with the largest number for the priority for a specific app is the one shown. This is how you overwrite an existing tour with your custom one.
|-
| tour
| The steps of a tour
|}

==== Tour steps ====
A tour step is a text bubble that is shown next to a UI element. It needs...
{|
| title
| This needs to be unique, like for all extension points. Even if you want to overwrite another tour, you need a different id!
|-
| target
| The UI element this text bubble is displayed next to. Hopscotch only allows identifiers as passed to JQuery, but App Suite extends this to functions. Most functions used simply return JQuery identifiers, the difference is when it is resolved: Functions are resolved later, which is helpful if your application is built by doing DOM manipulations as late as possible - App Suite is.
|-
| content
| The content of a text bubble. Can be html, as it uses the innerHtml method of JQuery to attach itself.
|-
| placement
| Where the text bubble is placed in relation to the UI element. Possible values are "top", "bottom", "left" and "right"
|-
| xOffset
| Passed directly to hopscotch. Moves the box horizontally relative to its standard position.
|-
| yOffset
| Passed directly to hopscotch. Moves the box vertically relative to its standard position.
|-
| arrowOffset
| Passed directly to hopscotch. Moves the arrow relative to its standard position, horizontally if the bubble is placed "top" or "bottom", vertically if "left" or "right".
|-
| onShow
| Passed directly to hopscotch. A function that is executed when the bubble is shown.
|-
| onShowDeferred
| A workaround for onShow: This waits for the deferred to be resolved before showing the bubble.
|}

And that is all there is to creating a tour.

== State after 7.8.0 ==

This framework was replaced by the [[AppSuite:Wizard_framework|Wizard/Tour framework]]

[[Category:UI]]
[[Category:Administrator]]
[[Category:Developer]]
[[Category:Custom development]]

AppSuite:Client Onboarding

2016-04-28T12:39:06Z

Frank.paczynski: add 'disable old parts'

<div class="title">Client Onboarding</div>

{{VersionFrom|7.8.1}}

__TOC__

= Configuration guide for Open-Xchange Client Onboarding =

With Open-Xchange Server v7.8.1 a new module is added allowing users to integrate several different clients and devices with Open-Xchange; such as providing a link to a commercial App Store to install certain apps on mobile devices.

By default, Open-Xchange ships with several built-in providers; thereof

* CalDAV
* CardDAV
* OX Mail App
* OX Drive App
* Connector for Microsoft Outlook®
* Sync App for Android
* Microsoft ActiveSync
* eM Client
* Mail (IMAP/SMTP)
* Generic Mobile App provider

Those providers allow accessing and/or synchronizing with certain data held by Open-Xchange on a supported device.

== Installation ==

To install the Client Onboarding module, the package open-xchange-client-onboarding needs to be installed.

Moreover the property <code>"com.openexchange.client.onboarding.enabled"</code>; in installed file <code>/opt/open-xchange/etc/client-onboarding.properties</code> needs to be set to <code>"true"</code> (default). So getting rid off the entire client on-boarding module simply requires setting the mentioned property to <code>"false"</code> (and executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool).

== Onboarding scenarios ==

The way to specify what and how a certain device is able to get “on-boarded” is mainly determined by so called scenarios. A scenario describes what gets deployed using which providers that contribute their onboarding possibilities and how it is made accessible to the client’s device.

A scenario consists of the following configuration attributes/options

* A unique scenario identifier
* A flag determining if scenario is enabled or not. If set to 'false' the scenario will not be available, useful for testing/enabling the scenario later on
* A scenario type, which is one of "plist", "manual", or "link"
** "plist" for generating a PLIST configuration file for iOS and OSX devices,
** "manual" for a description for the user for a manual set-up/configuration
** "link" for a link/URL to either Apple App Store / Google Play Store or to downloadable executable
* The "link" attribute, which is only considered it type is set to "link". That attribute consists of the sub-attributes "url" and "type".
** "url" provides the actual link/URL to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. For specifying a property that provides the actual link, please use special "property" scheme; e.g. "property://com.openexchange.client.onboarding.app.mylink"
** "type" indicates if "url" holds a link for either Apple App Store, Apple Mac Store or Google Play Store. Must only be specified in case "url" points either of those commercial stores. Supported values are "appstore", "macstore" and "playstore"
* The identifiers for the providers, which contribute to the scenario;<br />
please check command-line tool <code>/opt/open-xchange/sbin/listonboardingproviders</code> to check, which ones are available
* The identifiers for alternative scenarios. This is typically used to provide alternative manual setup possibility.
* The comma-separated names of Font Awesome icons that are supposed to be displayed for the scenario<br />
(only the ones from v4.4.0 are currently supported)
* The translatable display name; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts
* The translatable description; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts

== Onboarding providers ==

As described in the previous section, a scenario specifies what providers contribute to it. A provider represents a certain App or (synchronization) protocol that a device can install, download and/or communicate with.

Moreover a provider specifies what Onboarding types are supported ("plist", "manual", and/or "link"). Hence, once a provider is chosen to contribute to a certain scenario, the supported on-boarding type needs to match the one of the scenario itself. E.g. a scenario, which indicates to be of type "link", will always fail if the associated provider signals to support types "plist" and "manual".

To check what providers are available on your system, please execute the <code>/opt/open-xchange/sbin/listonboardingproviders</code> command-line tool, which outputs something like:

[[File:onboarding_1.png]]

Each provider might require one or more capabilities/permissions to be available for the requesting user. If capabilities/permissions are not satisfied, the associated scenario cannot be applied, but will be displayed to the user for upsell opportunities.

=== Generic Onboarding provider for Apps ===

Identifier: <code>app</code>

The generic onboarding provider for apps allows specifying custom scenarios of type "link" for arbitrary links/URLs pointing to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. The link can be set directly or via a property.

This provider requires no capability/permission.

An exemplary section in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file might look like (check "Configuring Onboarding scenarios" chapter for more details):

[[File:onboarding_2.png]]

=== CalDAV/CardDAV ===

Identifiers: <code>caldav</code> & <code>carddav</code>

In order for a scenario (having CalDAV/CardDAV in its provider listing) to be executable by a user, the "caldav" capability and "carddav" capability respectively are required.

Moreover, the appropriate *DAV end-points are supposed to be configured through property <code>com.openexchange.client.onboarding.caldav.url</code> in <code>client-onboarding-caldav.properties</code> file and property <code>com.openexchange.client.onboarding.carddav.url</code> in <code>client-onboarding-carddav.properties</code> file.

=== Drive/Mail Apps ===

Identifiers: <code>driveapp</code> & <code>mailapp</code>

Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the "drive" capability and the Mail App requires the "mobile_mail_app" one.

The appropriate links to the apps in the corresponding stores are configured in associated .properties files:

* <code>client-onboarding-driveapp.properties</code>
* <code>client-onboarding-mailapp.properties</code>

By default the links to the official apps are set, but may be changed to ones for branded versions.

=== Drive Windows Client ===

Identifier: <code>drivewindowsclient</code>

The provider for the windows Drive Client. Requires the "drive" capability, but has no configuration options. However, this provider requires the "open-xchange-drive-client-windows" and the orderly configured binaries (e.g. through installing appropriate package according to the brand).

Please check [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive#OX_Drive_for_Windows ''this''] documentation for more details.



=== Mail (IMAP/SMTP) ===

Identifier: <code>mail</code>

The provider for deploying the IMAP/STMP account on target device using native/stock mail app. All IMAP/SMTP related settings are settable in file 'client-onboarding-mail.properties'.

=== Microsoft ActiveSync (EAS) ===

Identifier: <code>eas</code>

Configures the ActiveSync account on target device. Allows specifying the EAS end-point through <code>com.openexchange.client.onboarding.eas.url</code> property in 'client-onboarding-eas.properties'.

=== OX Updater ===

Identifier: <code>oxupdater</code>

The provider offering the download for the OX Client Updater ([http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''http:''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''//oxpedia''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''org/wiki/index''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''php''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''?''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''title=AppSuite''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater '':''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''Open-Xchange_Updater'']). The provider is available as soon as the according package is installed and at least one product can be installed/updated via it by the user. A pre-configured scenario 'oxupdaterinstall' is already contained in <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code>.

== Configuring Onboarding scenarios ==

Onboarding scenarios are configured through the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Each scenario starts with its own "section" in that YAML file by typing its unique identifier. All further attributes as outlined in chapter "Onboarding scenarios" are nested below that identifier.

=== Easily enabling/disabling scenarios ===

By default, Open-Xchange ships with a set of pre-defined scenarios that might apply to the most common installations. Each scenario can easily be enabled/disabled through its "enabled" Boolean attribute in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool applies the changes without the need for restart.

=== Translatable strings ===

Those attributes ending with "_t10e" refer to localizable strings and are placed into "client-onboarding-scenarios.pot" file. Once such attributes ending with "_t10e" are changed/customized and/or added, the appropriate "client-onboarding-scenarios.pot" file needs to be re-created in order to get translated. For generating that "client-onboarding-scenarios.pot" file, please execute the /opt/open-xchange/sbin/parsei18nyaml command-line tool. That .pot file needs then be turned to the .po files for the individual languages.

Thus changing any of the attributes ending with "_t10e" requires (provided that appropriate .po files are available in <code>/opt/open-xchange/i18n</code> directory) either a restart or executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool together with stop/start of the "com.openexchange.i18n" bundle.

=== Scenario scope ===

While the previously mentioned "enabled" attribute offers some kind of generic on/off switch, the properties outlined in this section allow defining the scope for a scenario. Scope in terms of

* For what devices (from the set of those specified by providers) is that scenario available and
* For which users is it available

As explained above, each scenario specifies one or more type-compatible providers associated with it. In turn, each provider determines to which devices the scenario applies. In order to further control, which device and which users are allowed to access a certain scenario, there are appropriate options available in file <code>/opt/open-xchange/etc/client-onboarding.properties</code>. Every option is fully [http://oxpedia.org/wiki/index.php?title=ConfigCascade ''config-cascade''] aware and therefore can be controlled on a global, per context set, per context and per user basis.

Thus, to make a scenario available for certain devices (as dictated by scenario’s providers) and for users as well, the scenario identifier needs to be added to the appropriate properties ending with ".scenarios" (for devices) and added to the "com.openexchange.client.onboarding.enabledScenarios" property (for user) as well:

<blockquote>com.openexchange.client.onboarding.apple.mac.scenarios<br />
com.openexchange.client.onboarding.apple.ipad.scenarios<br />
com.openexchange.client.onboarding.apple.iphone.scenarios<br />
com.openexchange.client.onboarding.android.tablet.scenarios<br />
com.openexchange.client.onboarding.android.phone.scenarios<br />
com.openexchange.client.onboarding.windows.desktop.scenarios

com.openexchange.client.onboarding.enabledScenarios
</blockquote>
Once a scenario is made accessible through configuration it is visible to users trying to perform a client onboarding using one of associated devices. However, whether a user is effectively allowed to execute that scenario is determined by the required capabilities of the denoted providers; if not allowed it gets displayed as an upsell opportunity.

=== Configuring actions ===

The type for a scenario determines what actions are associated with it to "''transport''" the onboarding information to the client. The types "manual" and "link" only show static information like displaying a link. In contrast the type "plist" allows several actions to transport the configuration profile onto the client. Thereof

* E-Mail
* SMS

In order to utilize the "E-Mail" action, a special transport must be configured for system-composed E-Mails [http://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode#Share_Notifications ''as it is for using the sharing functionality'']. This transport is configured in noreply.properties. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.

Using the SMS action requires a SIP Gate being available. Please check [http://oxpedia.org/wiki/index.php?title=AppSuite:SMS_Sipgate ''this documentation''] how to setup a SIP Gate for sending SMS to capable clients.

Moreover, scenarios of type "plist" require having PLIST-signing enabled. Otherwise the device will show a warning when importing a received PLIST configuration profile. Please follow the instructions as outlined in [http://oxpedia.org/wiki/index.php?title=AppSuite:PList_signing ''this article''] how to enable and configure signing for PLIST files.

== Adding custom scenarios ==

The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.

<blockquote>mygoogleapp:<br />
enabled: true<br />
type: link<br />
link:<br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
type: playstore<br />
providers: [app]<br />
alternatives: []<br />
icon: fa-cloud<br />
displayName_t10e: "My App for synchronizing files"<br />
description_t10e: "Synchronize your files with our Drive application."
</blockquote>
The next step is to make that scenario accessible through adapting 'client-onboarding.properties' file. Hence, the scenario identifier needs to be added to the devices, to which it applies (Android devices in this case):

<blockquote>com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp<br />
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp
</blockquote>
Furthermore, that scenario needs to be made accessible to users as well:

<blockquote>com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp
</blockquote>
At last, a .pot file is supposed to be generated from the translatable strings using /opt/open-xchange/sbin/parsei18nyaml command-line tool to yield the .po files for the individual languages.

Provided that target users do hold appropriate capabilities, they are allowed to execute that scenario. In the example above the "app" provider is specified, which does no require any capabilities. Hence, that scenario is available.

== HowTos ==

=== How can I quickly setup a default/test configuration ? ===

# Install open-xchange-client-onboarding package
# Edit <code>/opt/open-xchange/etc/client-onboarding.properties</code> and set <code>com.openexchange.client.onboarding.enabled</code> to <code>true</code>
# Edit <code>noreply.properties</code> to enable autoconfig sending via email. PS: Have a fully working smtp login available like “noreply@yourdomain.tld”
# Edit client-onboarding-scenarios.yml and set “enable” for : “driveappinstall” , “davsync” “davmanual” “mailsync” “mailmanual” to <code>true</code>
# Now set the correct caldav/carddav server FQDNs in the corresponding files for your setup
#*<code>client-onboarding-caldav.properties</code>
#*<code>client-onboarding-carddav.properties</code>
# Restart OX process
# Login to AppSuite. Click on Settings - Connect your device
# Verify that you have following onboarding options available:
#* windows -> imap/smtp details
#* android/fon+tablet -> imap/smtp details
#* android/fon+tablet -> drive app
#* apple -> iphone -> imap/smtp config button
#* apple -> iphone -> imap/smtp details for experts
#* apple -> iphone -> calendar/addressbok -> config button
#* apple -> iphone -> calendar/addressbok -> details for dav setup
#* apple -> iphone -> drive app
#* apple -> ipad -> imap/smtp config send email
#* apple -> ipad -> imap/smtp config button
#* apple -> ipad -> imap/smtp details for experts
#* apple -> ipad -> calendar/addressbook config send email
#* apple -> ipad -> calendar/addressbook config button
#* apple -> ipad -> calendar/addressbook details for experts
#* apple -> ipad -> drive app

=== How can I quickly disable a certain scenario ===

Simply enter the 'client-onboarding-scenarios.yml' file and go to the section specifying the target scenario. Switch the 'enabled' flag to "false" and execute /opt/open-xchange/sbin/reloadconfiguration command-line tool.

E.g. to disable the OX Drive App:

[[File:onboarding_3.png]]

=== How can I disable the outdated ui parts like 'Downloads'? ===

The wizard replaces and extends the functionality of the old Download Section in settings and the corresponding widgets. We recommend to disable these outdated parts.
# widget: get ox drive
# widget: update
# settings entry: downloads

'''remove settings section 'Downloads' '''

Edit the property file and change the value to true:
* ''io.ox/core//settings/downloadsDisabled''

'''remove widgets'''

To remove the both related portal widget/tiles please refer to the
[[AppSuite:Configuring_portal_plugins#Disabling_a_tile_completely | portal plugins wiki page ]]

* ''io.ox/portal/widget/oxdriveclients''
* ''io.ox/portal/widget/updater''

=== How can I add my own App? ===

Provided that the App is accessible by a link (pointing to a commercial App Store or to a downloadable executable/installer), the generic "app" is the suitable provider to choose.

Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and "provider" attribute set to "[app]":

<blockquote>mygoogleapp:<br />
enabled: true<br />
type: link<br />
link:<br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
type: playstore<br />
providers: [app]<br />
alternatives: []<br />
icon: fa-cloud<br />
displayName_t10e: "My App for synchronizing files"<br />
description_t10e: "Synchronize your files with our Drive application."
</blockquote>
The attribute "type" needs to be set to "link".

The attribute "link" should be configured with:

* "url" sub-attribute containing the actual link pointing to the URL location
* "type" sub-attribute specifying of what type that link is: either "appstore", "macappstore", "playstore" or "common".<br />
The type "common" is supposed to be used for links that do not point to a commercial App Store, but to a downloadable executable/installer file.

The "icon" attribute is supposed to contain a comma-separated list of Font Awesome icons (only the ones from v4.4.0 are currently supported) that represent the App; e.g.

* "fa-cloud" for Drive/file-related nature
* "fa-calendar, fa-users" for Calendar and Address Book synchronization
* "fa-envelope-o" for Mail nature

Next, the translatable display name and description should be set through setting the attributes "displayName_t10e" and "description_t10e". As described previously, executing the /opt/open-xchange/sbin/parsei18nyaml command-line tool yields an appropriate .pot file, which can then be used for generating the individual .po file for the different translations.

Finally, the 'client-onboarding.properties' file needs to be modified to specify the "scope" for that new scenario. Add the scenario’s unique name to the appropriate device properties and add it to "com.openexchange.client.onboarding.enabledScenarios" property as well.

After executing /opt/open-xchange/sbin/reloadconfiguration command-line tool the new client onboarding scenario is available for the selected users/devices.

=== How can I upsell my own app? ===

Having the same prerequisites/steps as for "How can I add my own App?" the scenario description in the 'client-onboarding-scenarios.yml' file simply needs to be extended by the desired capabilities, which are supposed to be used for managing the upsell.

Example

<blockquote>mygoogleapp:<br />
enabled: true<br />
type: link<br />
link:<br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br />
type: playstore<br />
'''capabilities: "mygoogleapp_capability"'''<br />
providers: [app]<br />
alternatives: []<br />
icon: fa-cloud<br />
displayName_t10e: "My App for synchronizing files"<br />
description_t10e: "Synchronize your files with our Drive application."
</blockquote>
The special "capabilities" attribute is only supported for scenarios of type "link" with the special "app" provider.

With such a "capabilities" attribute only users, which have the "mygoogleapp_capability" capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.

<blockquote>[[File:onboarding_4.png]]
</blockquote>

AppSuite:Theming the login page

2016-02-11T10:12:32Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Theming the login page</div>

'''Abstract.''' In this article, you can learn how to create a customized theme for the default login page for your appsuite installation and also how to configure different ones for different hostnames. It only explains where and how to configure and apply the modifications but not the [[AppSuite:Theming|basics of App Suite theming]].

__TOC__

== style.less ==

To apply a theme to the login page you just add the relevant snippets to the style.less file like for a normal theme and include the logos and artifacts in the theme directory.

Here are some examples of CSS selectors which can be addressed on the login page:

#io-ox-login-username
#io-ox-login-screen .btn-primary
#io-ox-login-screen .btn-primary:hover
#io-ox-login-header-prefix
#io-ox-login-header-label
#io-ox-login-container
.wallpaper
body.down #io-ox-login-container .alert.alert-info
.language-delimiter
#io-ox-copyright

== as-config.yml ==

To actually apply the above definition the theme needs to be specified in the file /opt/open-xchange/etc/as-config.yml:

signinTheme: MYTHEME

As as-config.yml can have different configuration based on different hostnames a multi branded configuration can be applied as well.

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

AppSuite:Dynamic Theme

2016-02-11T10:11:26Z

Frank.paczynski:

{{Stability-unstable}}

<div class="title">Dynamic Theming</div>

The dynamic theme plugin allows to have custom colors and logo without creating a real theme for each possible color combination. The customization information is stored in the [[ConfigCascade|Configuration Cascade]] and applied at runtime, immediately after login.

== Installation ==

The theme generator consists of the single package <tt>open-xchange-dynamic-theme</tt>, which is installed on the OX middleware.

Before OX App Suite v7.6.2, the package included the command line tool <tt>/opt/open-xchange/sbin/update-dynamic-theme</tt>, which must be called after every update of other plugins. It is called automatically after the installation and upgrades of <tt>open-xchange-dynamic-theme</tt>. The tool examines all installed <tt>.less</tt> files and computes which CSS rules need to be changed to apply the custom colors everywhere.

Since v7.6.2, the tool is called automatically whenever necessary, so it is not necessary to call it manually, and therefore it is not installed in the <tt>/opt/open-xchange/sbin/</tt> directory anymore.

== Configuration ==

=== Enabling the Plugin ===

The plugin is enabled or disabled by the [[AppSuite:Capabilities|capability]] <tt>dynamic-theme</tt>, e.g. in a file <tt>/opt/open-xchange/etc/dynamic-theme.properties</tt> set

com.openexchange.capability.dynamic-theme=true

When using the plugin, the actual theme should be the built-in <tt>default</tt> theme. To prevent all users from changing it and hide the theme selector in the preferences, set the property <tt>io.ox/core//theme</tt> to read-only. To do this, change the file <tt>/opt/open-xchange/etc/meta/appsuite.yaml</tt> as follows:

io.ox/core//theme:
protected: true

If some users won't use dynamic themes, this approach won't work. Instead, the theme selector can be disabled an enabled by controlling the list of available themes. The theme selector is hidden if the list is empty. To be able to do that with the Configuration Cascade, the entire list of themes needs to be specified as a single JSON value, e.g. by changing the file <tt>/opt/open-xchange/etc/settings/appsuite.properties</tt> as follows:

io.ox/core/settingOptions//themes={"default":"Default Theme"}

Then, to hide the theme selector for users with a dynamic theme, use the Configuration Cascade to change the value to <tt>{}</tt>.

=== Specifying a Theme ===

The package installs the file <tt>/opt/open-xchange/etc/settings/open-xchange-dynamic-theme.properties</tt>, which contains the global defaults for the custom theme settings. Any of the settings contained in that file can be changed per-context or at any other granularity supported by the [[ConfigCascade#UI_Properties|Configuration Cascade]]. The individual settings are as follows:

<table class="wikitable" style="width:auto">
<tr><th>Prefix</th>
<th> Key </th><th> Default value </th></tr>
<tr><td rowspan="5" style="vertical-align:middle"><tt>io.ox/dynamic-theme//</tt></td>
<td><tt> frameColor </tt></td><td><tt> #333 </tt></td></tr>
<tr><td><tt> iconColor </tt></td><td><tt> #bbb </tt></td></tr>
<tr><td><tt> selectionColor </tt></td><td><tt> #39a9e1 </tt></td></tr>
<tr><td><tt> logoWidth </tt></td><td><tt> 60 </tt></td></tr>
<tr><td><tt> logoURL </tt></td><td>
<tt> apps/themes/default/logo-small.png </tt></td></tr>
</table>

The colors can be any CSS color; <tt>logoWidth</tt> is specified in pixels; <tt>logoURL</tt> can be relative (to <tt>/appsuite/</tt>), or absolute. When using absolute URLs to point to different hosts, use the form <tt>//<var>hostname</var>/<var>path</var></tt> to keep the protocol (HTTP or HTTPS) and avoid any unnecessary security warnings.

== Maintenance ==

The source file <tt>apps/io.ox/dynamic-theme/definitions.less.in</tt> contains the Less rules for the theme. All keys in the namespace <tt>io.ox/dynamic-theme//</tt> are converted to Less variables by prefixing them with <tt>@io-ox-dynamic-theme-</tt>. The set of keys in the following files must be kept in sync:
* <tt>apps/io.ox/dynamic-themes/definitions.less.in</tt>
* <tt>apps/io.ox/dynamic-theme/settings/defaults.js</tt>
* <tt>lib/update-dynamic-theme.js</tt>
* <tt>conf/settings/open-xchange-dynamic-theme.properties</tt>

AppSuite:Dynamic Theme

2016-02-11T10:10:34Z

Frank.paczynski:

<!-- !!! -

{{Stability-unstable}}

<div class="title">Dynamic Theming</div>

The dynamic theme plugin allows to have custom colors and logo without creating a real theme for each possible color combination. The customization information is stored in the [[ConfigCascade|Configuration Cascade]] and applied at runtime, immediately after login.

== Installation ==

The theme generator consists of the single package <tt>open-xchange-dynamic-theme</tt>, which is installed on the OX middleware.

Before OX App Suite v7.6.2, the package included the command line tool <tt>/opt/open-xchange/sbin/update-dynamic-theme</tt>, which must be called after every update of other plugins. It is called automatically after the installation and upgrades of <tt>open-xchange-dynamic-theme</tt>. The tool examines all installed <tt>.less</tt> files and computes which CSS rules need to be changed to apply the custom colors everywhere.

Since v7.6.2, the tool is called automatically whenever necessary, so it is not necessary to call it manually, and therefore it is not installed in the <tt>/opt/open-xchange/sbin/</tt> directory anymore.

== Configuration ==

=== Enabling the Plugin ===

The plugin is enabled or disabled by the [[AppSuite:Capabilities|capability]] <tt>dynamic-theme</tt>, e.g. in a file <tt>/opt/open-xchange/etc/dynamic-theme.properties</tt> set

com.openexchange.capability.dynamic-theme=true

When using the plugin, the actual theme should be the built-in <tt>default</tt> theme. To prevent all users from changing it and hide the theme selector in the preferences, set the property <tt>io.ox/core//theme</tt> to read-only. To do this, change the file <tt>/opt/open-xchange/etc/meta/appsuite.yaml</tt> as follows:

io.ox/core//theme:
protected: true

If some users won't use dynamic themes, this approach won't work. Instead, the theme selector can be disabled an enabled by controlling the list of available themes. The theme selector is hidden if the list is empty. To be able to do that with the Configuration Cascade, the entire list of themes needs to be specified as a single JSON value, e.g. by changing the file <tt>/opt/open-xchange/etc/settings/appsuite.properties</tt> as follows:

io.ox/core/settingOptions//themes={"default":"Default Theme"}

Then, to hide the theme selector for users with a dynamic theme, use the Configuration Cascade to change the value to <tt>{}</tt>.

=== Specifying a Theme ===

The package installs the file <tt>/opt/open-xchange/etc/settings/open-xchange-dynamic-theme.properties</tt>, which contains the global defaults for the custom theme settings. Any of the settings contained in that file can be changed per-context or at any other granularity supported by the [[ConfigCascade#UI_Properties|Configuration Cascade]]. The individual settings are as follows:

<table class="wikitable" style="width:auto">
<tr><th>Prefix</th>
<th> Key </th><th> Default value </th></tr>
<tr><td rowspan="5" style="vertical-align:middle"><tt>io.ox/dynamic-theme//</tt></td>
<td><tt> frameColor </tt></td><td><tt> #333 </tt></td></tr>
<tr><td><tt> iconColor </tt></td><td><tt> #bbb </tt></td></tr>
<tr><td><tt> selectionColor </tt></td><td><tt> #39a9e1 </tt></td></tr>
<tr><td><tt> logoWidth </tt></td><td><tt> 60 </tt></td></tr>
<tr><td><tt> logoURL </tt></td><td>
<tt> apps/themes/default/logo-small.png </tt></td></tr>
</table>

The colors can be any CSS color; <tt>logoWidth</tt> is specified in pixels; <tt>logoURL</tt> can be relative (to <tt>/appsuite/</tt>), or absolute. When using absolute URLs to point to different hosts, use the form <tt>//<var>hostname</var>/<var>path</var></tt> to keep the protocol (HTTP or HTTPS) and avoid any unnecessary security warnings.

== Maintenance ==

The source file <tt>apps/io.ox/dynamic-theme/definitions.less.in</tt> contains the Less rules for the theme. All keys in the namespace <tt>io.ox/dynamic-theme//</tt> are converted to Less variables by prefixing them with <tt>@io-ox-dynamic-theme-</tt>. The set of keys in the following files must be kept in sync:
* <tt>apps/io.ox/dynamic-themes/definitions.less.in</tt>
* <tt>apps/io.ox/dynamic-theme/settings/defaults.js</tt>
* <tt>lib/update-dynamic-theme.js</tt>
* <tt>conf/settings/open-xchange-dynamic-theme.properties</tt>

AppSuite:Test basics

2016-02-11T08:56:56Z

Frank.paczynski:

Lessons learned painfully while doing testing:
* PhantomJS thinks it is a '''touch''' device (Modernizr.touch === true)
* Almost no CSS is loaded. Don't rely on classes like "hidden" (bootstrap class)
* Turn off CSS transitions - any DOM-based test might fail (caused by random DOM reflow delay)
* Don't clear <body> (e.g. $(document.body).empty()). UI is not robust against that.
** instead attach a new element to the body (or anywhere else) and remove it afterwards
* The browser window is elastic. It has no fixed size. Usually affects scrolling tests.
* If weird things happen, try to check if your app/window/node is really still in the DOM.
* HTML fixtures cannot be loaded (don't know why yet); just rename your files to *.txt
* Please mind that your fake server only works inside "description" (not across specs)
* PhantomJS fails at: Date.parse("2012-01-01"); (see https://code.google.com/p/phantomjs/issues/detail?id=267#c2)
* The fake server is global, if someone has registered your desired api/call already, your response will never get send
** it is possible to use this.server.responses.filter to remove another problematic response implementation
* Any checks for z-index will probably fail due to the lack of loaded CSS. If an element is not positioned (relative or absolute) the computed style is "auto". Just reposition affected elements in your spec.

== Testing on windows ==

A small and incomplete collection of things, that might work different on a windows machine:

* the UI relies on zonefiles being installed on the system, this is the case for mac and linux environments, but not on windows
** it should be possible to install the zonefiles manually and make karma serve those

== Fixtures ==

* using 0 as identifier value (id, user_id, etc.) could cause unexpected system behavior
[[Category:UI]]
[[Category:AppSuite]]
[[Category:Developer]]
[[Category:Testing]]

AppSuite:Testing 3rd-party code

2016-02-11T08:46:22Z

Frank.paczynski:

<div class="title">Testing 3rd-party code</div>

__TOC__

This article explains one way to add automatic testing to UI plugins.

== Libraries ==

* [http://visionmedia.github.io/mocha/ Mocha] - the fun, simple, flexible JS testing framework
* [http://sinonjs.org/ Sinon.JS] - Standalone test spies, stubs and mocks for JavaScript.
* [http://karma-runner.github.io/ Karma Runner] - test runner
* [http://chaijs.com/ Chai.js] - Assertion framework

== using karma-ox-ui ==

The [[AppSuite:GettingStarted_7.6.0|shared grunt configuration]] ships with most of the parts pre-configured. Still, a little setup is needed to enable automatic testing for an external app. Since we use many standard libraries, this approach can be extended as you wish.

=== Setup ===

Make sure, karma executable is installed:

npm install -g karma-cli

Install a few more testing libraries locally:

npm install --save-dev karma-mocha karma-chai karma-sinon karma-ox-ui karma-phantomjs-launcher

After that, in your plugin directory generate a new karma.conf.js:

jb@wiggum ~/code/appsuite/ox_pgp_mail (git)-[ding] % karma init

Which testing framework do you want to use ?
Press tab to list possible options. Enter to move to the next question.
> mocha

Do you want to use Require.js ?
This will add Require.js plugin.
Press tab to list possible options. Enter to move to the next question.
> no

Do you want to capture any browsers automatically ?
Press tab to list possible options. Enter empty string to move to the next question.
> PhantomJS
>

What is the location of your source and test files ?
You can use glob patterns, eg. "js/*.js" or "test/**/*Spec.js".
Enter empty string to move to the next question.
>

Should any of the files included by the previous patterns be excluded ?
You can use glob patterns, eg. "**/*.swp".
Enter empty string to move to the next question.
>

Do you want Karma to watch all the files and run the tests on change ?
Press tab to list possible options.
> no

Config file generated at "/home/jb/code/appsuite/ox_pgp_mail/karma.conf.js".

Edit the generated file and adjust the following configuration variables:

<pre class="language-javascript">
basePath: 'build/',
frameworks: ['ox-ui', 'sinon', 'mocha', 'chai'],
files: [
'spec/test-main.js',
{pattern: 'apps/**/*.js', included: false},
{pattern: 'spec/**/*_spec.js', included: false}
]
</pre>

Generate a main loader script to start the test after App Suite Core UI
has been booted. The file should be put in `spec/test-main.js`:

<pre class="language-javascript">
var allTestFiles = [];
var TEST_REGEXP = /_spec\.js$/i;

var pathToModule = function(path) {
return path;
// return path.replace(/^\/base\//, '').replace(/\.js$/, '');
};

Object.keys(window.__karma__.files).forEach(function(file) {
if (TEST_REGEXP.test(file)) {
// Normalize paths to RequireJS module names.
allTestFiles.push(pathToModule(file));
}
});

require(['io.ox/core/extPatterns/stage'], function (Stage) {

'use strict';

ox.testUtils.stubAppsuiteBody();

new Stage('io.ox/core/stages', {
id: 'run_tests',
index: 99999,
run: function (baton) {
requirejs.config({
// Karma serves files from '/base/apps'
baseUrl: '/base/apps',

// ask Require.js to load these files (all our tests)
deps: allTestFiles,

// start test run, once Require.js is done
callback: window.__karma__.start
});
}
});
});
</pre>

=== Dealing with JSHINT ===
JSHINT is notoriously picky. And rightly so. But we still need to teach it to ignore our test frameworks' peculiarities. Extend the <tt>global</tt> part of your <tt>.jshintrc</tt> by these switches:

<code>
"globals": {
"assert": false,
"describe": false,
"it": false,
"beforeEach": false,
"afterEach": false,
"expect": false,
"waitsFor": false,
"runs": false,
"chai": false,
"sinon": false,
"spyOn": false,
"xit": false,
"xdescribe": false,
"jasmine": false
}
</code>

=== Running the tests ===

There are multiple targets provided in
[https://github.com/Open-Xchange-Frontend/shared-grunt-config shared grunt configuration].

The <tt>grunt/local.conf.json</tt> needs to be configured and point to an existing build of the core UI (coreDir setting). When testing on a machine with the core UI installed from distribution packages, also the German translations need to be installed to run the tests. After that, coreDir can be set to <tt>/opt/open-xchange/appsuite/</tt>.

The recommended way to start testing is to run:

grunt dev

This will start a connect server, the karma
test server and a watcher for changes. Optionally, it is possible to connect multiple browsers to the host running the karma server (port 9876). Tests will run in those browsers, too. You can trigger a test run manually by running:

grunt testrun

in another terminal. This will be done automatically by the grunt watch
task, after any source file of your project has been changed.

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

AppSuite:RunTests

2016-02-11T08:39:42Z

Frank.paczynski:

{{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
* [http://chaijs.com/ Chai.js] - Assertion framework

== Setting up your system ==

=== Before starting: Mac only ===
brew install phantomjs
...or link it in path and set executable bit on phantomjs binary yourself. After this follow the rest of the guide.

=== All ===
You need at least ''node'' version 0.8 to use the latest version of ''karma'', which we need. Karma will be installed with all other development dependencies. So just make sure you ran

npm install

within your ui directory in the appsuite repository.

== Running the tests ==

The recommended way to start testing is to run:

grunt dev

This will start a connect server, the karma
test server and a watcher for changes. Optionally, it is possible to connect multiple browsers to the host running the karma server (port 9876). Tests will run in those browsers, too. You can trigger a test run manually by running:

grunt testrun

in another terminal. This will be done automatically by the grunt watch
task, after any source file of your project has been changed.

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

AppSuite:Http.js

2016-02-11T08:30:13Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Requesting server api with http.js</div>

'''Abstract'''
Http is intended as centralized server communication layer currently heavily used in our [[AppSuite:APIs | front end APIs]]. For more details than covered in this article dive into it's source code found in ''io.ox/core/http.js''.

__TOC__

= HTTP facades =

''general example''

<pre>http.GET({
module: 'mail',
params: {
action: 'all',
folder: 'default0/INBOX'
}
});</pre>
== GET(options) ==

<pre>/**
* Send a GET request
* @param {Object} options Request options
* @returns {Object} jQuery's Deferred
*/</pre>
== POST(options) ==

<pre>/**
* Send a POST request
* @param {Object} options Request options
* @returns {Object} jQuery's Deferred
*/</pre>
== FORM(options) ==

<pre>/**
* Send a POST request using a FormData object
* @param {Object} options Request options
* @param {string} options.module Module, e.g. folder, mail, calendar etc.
* @param {Object} options.params URL parameters
* @returns {Object} jQuery's Deferred
*/</pre>
== PUT(options) ==

<pre>/**
* Send a PUT request
* @param {Object} options Request options
* @returns {Object} jQuery's Deferred
*/
</pre>
== DELETE(options) ==

<pre>/**
* Send a DELETE request
* @param {Object} options Request options
* @returns {Object} jQuery's Deferred
*/</pre>
== UPLOAD(options) ==

<pre>/**
* Send a UPLOAD request
* @param {Object} options Request options
* @returns {Object} jQuery's Deferred
*/</pre>
= Column Mappings =

* server requests
** still require use of columns ids
* server response
** column_id keys will be replaced with column names to ease handling

== getAllColumns(module, join) ==
<pre>/**
* get all columns of a module
* @param {string} module (name)
* @param {boolean} join (join array with comma separator )
* @return {arrray|string} ids */ ```
</pre>

== getColumnMapping(module) ==

<pre>/**
* returns the column mapping of a module
* @param {string} module The module name.
* @returns {object} A map from numeric column IDs to the corresponding field names.
*/</pre>
== makeObject(data, module, columns) ==

<pre>/**
* transform objects with array-based columns into key-value-based columns
* @param {Array} data Data
* @param {string} module Module name
* @param {Array} columns Columns
* @returns {Object} Transformed object
*/</pre>

= Request Stacking =

* stack ability for calls to minimize overhead of server communication

== pause() ''and'' resume() ==

'''example'''

<pre>// pause http layer
http.pause();

// process all updates
_(list).map(function (item) {
return http.PUT({
module: 'calendar',
params: {
action: 'update',
id: item.id,
folder: item.folder_id,
timestamp: item.timestamp
},
data: { ... },
});
});

// resume & trigger refresh
http.resume()</pre>
== retry (request) ==

* retry request

= Utils =

== simplify(list) ==

* simplify objects in array for list requests
* returns array of items
* possible returned item types
** { id: '8978989' }
** { folder: 'inbox' }<br />
** { recurrence_position: 'inbox' }
** 8978989
** 'inbox'

<pre>/**
* Simplify objects in array for list requests
* @param {array} list
* @returns {array} list
*/</pre>
== fixList(ids, deferred) ==

<pre>/**
* Fixes order of list requests (temp. fixes backend bug)
* @param {array} ids
* @param {deferred} deferred
* @return {deferred} resolve returns array
*/</pre>

= Logging =

== log() ==

<pre>/**
* returns failed calls
* @return {backbone.collection}
*/</pre>

[[Category:AppSuite]]
[[Category:UI]]
[[Category:UI-Server-Interaction]]

AppSuite:Paste inline images

2016-02-11T06:59:49Z

Frank.paczynski:

{{Stability-experimental}}

'''Abstract: ''' Pasting images is basically supported by any major browser. But there are several difficulties to provide a cross-browser solution. This article covers, how to paste images into the different browsers.

== Paste images ==

If speaking about pasting images, it is important to consider the source where the image was copied. Basically, copying images from an application is possible (for details see Section Applications). It seems like these applications are simply storing the image data in the clipboard which can be accessed by the paste events of the browser.

Pasting images from a folder of the operating system does not work on any tested environment. Whereas OS X does provide the filename and a dummy picture, the clipboard of all browsers on Windows Systems remains empty.

== Support ==

The following table lists all major browsers and their ability to insert pasted images from applications.

{|
! browser
! paste support (tested version)
! specifics
|-
| Chrome
| 43.0.2357.81
|
|-
| Safari
| <span style="color: red;">no support in 8.0.6</span>
| Does not provide images in clipboardData. After pasting, the browser inserts an img-tag with webkit-fake-url. There is no pure javascript solution to retrieve the image data for upload.
|-
| Firefox
| 38.0.1
| Does not provide images in clipboardData. After pasting, the browser inserts an img-tag with base64 encoded src.
|-
| Internet Explorer
| 11.0.9600.16428
| IE 10 does not support image pasting.
|-
|}

== Applications ==

This table lists some applications which were tested as copy sources for images. Mainly, OS related applications does are not supported as copy source whereas image viewing/editing related applications are supported.

{|
! application
! paste support
! operating system
|-
| Finder
| <span style="color:red;">no</span>
| OS X
|-
| Preview
| <span style="color: green;">yes</span>
| OS X
|-
| Fotos
| <span style="color: green;">yes</span>
| OS X
|-
| Chrome
| <span style="color: green;">yes</span>
| OS X and Windows
|-
| Internet Explorer
| <span style="color: green;">yes</span>
| Windows
|-
| Windows Explorer
| <span style="color: red;">no</span>
| Windows
|-
| Windows Photo Viewer
| <span style="color: red;">no</span>
| Windows
|-
| Paint
| <span style="color: green;">yes</span>
| Windows
|-
| GimP
| <span style="color: green;">yes</span>
| OS X and Windows
|-
|}

AppSuite:Memory leaks (UI)

2016-02-11T06:21:05Z

Frank.paczynski:

<div class="title">Finding memory leaks in the UI</div>

'''Intro''': Searching for memory leaks in the UI is not a pleasant task, but sadly necessary.

__TOC__

== Avoiding memory leaks ==

'''resources:'''
*[https://www.ibm.com/developerworks/library/wa-memleak/ Memory leak patterns]

== Issues ==
Different browsers offer different ways of tracing memory leaks. As of writing, the core team's favourite browser is Google Chrome.

== Using Chrome ==
Addy Osmani has written extensively on finding memory leaks with Chrome. His often-quoted article "[http://addyosmani.com/blog/taming-the-unicorn-easing-javascript-memory-profiling-in-devtools/ Taming the Unicorn]" explains how to use the Chrome DevTools for this purpose.

'''additional resources:'''
* [https://developer.chrome.com/devtools/docs/heap-profiling-dom-leaks Uncovering DOM Leaks]

[[Category: UI]]
[[Category: Developer]]
[[Category: Custom development]]
[[Category: AppSuite]]

AppSuite:Supported file types

2016-02-11T06:16:41Z

Frank.paczynski:

= OX App Suite File Support =

OX App Suite web frontend allows you to preview, view and edit files at the different modules.

One of the modules is OX Drive, an integral part the OX App Suite user frontend. OX Drive provides view, preview, run and even edit a variety of media file types (e.g. photos, music documents etc.). Note: to edit documents you do need to have the relevant document editor activated within OX App Suite.

Other components of OX App Suite include OX Document Viewer, which allows users to preview and view various file formats, and OX Documents which further enhances collaboration and creativity by allowing real time sharing, collaboration and editing of documents online. OX Documents contains OX Text and OX Spreadsheet.

A common question is what files are supported of the different modules. The following list is not definitive

== OX Drive integrated Mediaplayer ==

The OX Drive "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:

=== Supported Video-Files inside OX Drive Mediaplayer ===

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

=== Supported Audio-Files inside OX Drive Mediaplayer ===

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, m4a, m4b
* Firefox: mp3, wav, ogg

== OX Document Viewer ==

The OX Document Viewer delivers plugin-free document viewing capabilities for Microsoft Office (.docx, .doc, .rtf, .pptx, .ppt, .xlsx, xls) and OpenDocument (.odt, .ods, .odp, .odg) file types as well as for the Portable Document Format (.pdf). It extends OX App Suite with content thumbnails and preview capabilities.

=== Images ===

* png
* jpg, jpeg

=== Text Documents ===

* docx (Microsoft Office Word text document)
* docm (Microsoft Office Word macro-enabled text document)
* dotx (Microsoft Office Word text document template)
* dotm (Microsoft Office Word macro-enabled text document template)
* odt (OpenDocument text document)
* ott (OpenDocument text document template)
* doc (Microsoft Word 97-2003 text document)
* dot (Microsoft Word 97-2003 text document template)
* rtf (Rich Text Format)

=== Spreadsheet Documents ===

* xlsx (Microsoft Office Excel workbook)
* xlsm (Microsoft Office Excel macro-enabled workbook)
* xltx (Microsoft Office Excel workbook template)
* xltm (Microsoft Office Excel macro-enabled workbook template)
* xlsb (Microsoft Office Excel macro-enabled workbook, binary format)
* xlam (Microsoft Office Excel add-in)
* ods (OpenDocument spreadsheet document)
* ots (OpenDocument spreadsheet document template)
* xls (Microsoft Excel 97-2003 workbook)
* xlt (Microsoft Excel 97-2003 workbook template)
* xla (Microsoft Excel 97-2003 add-in)

=== Presentation Documents ===

* pptx (Microsoft Office PowerPoint presentation)
* pptm (Microsoft Office PowerPoint macro-enabled presentation)
* potx (Microsoft Office PowerPoint presentation template)
* potm (Microsoft Office PowerPoint macro-enabled presentation template)
* ppsx (Microsoft Office PowerPoint slide show)
* ppsm (Microsoft Office PowerPoint macro-enabled slide show)
* ppam (Microsoft Office PowerPoint add-in)
* odp (OpenDocument presentation document)
* otp (OpenDocument presentation document template)
* ppt (Microsoft PowerPoint 97-2003 presentation)
* pot (Microsoft PowerPoint 97-2003 presentation template)
* pps (Microsoft PowerPoint 97-2003 slide show)
* ppa (Microsoft PowerPoint 97-2003 add-in)

=== Miscellaneous ===

* pdf (Portable Document Format)
* odg (OpenDocument drawing document)
* otg (OpenDocument drawing document template)
* odi (OpenDocument image document)
* oti (OpenDocument image document template)
* odc (OpenDocument chart document)
* otc (OpenDocument chart document template)
* odf (OpenDocument formula document)
* otf (OpenDocument formula document template)
* odm (OpenDocument global text document)

== OX Documents ==

OX Documents contains OX Text and OX Spreadsheet.

=== OX Text Documents ===

OX Text, is a web-based word processor. Its main focus is on reducing the complexities of text editing while promoting collaborative document creation.

* docx (Microsoft Office Word text document)
* docm (Microsoft Office Word macro-enabled text document)
* dotx (Microsoft Office Word text document template)
* dotm (Microsoft Office Word macro-enabled text document template)
* odt (OpenDocument text document)
* ott (OpenDocument text document template)
* doc (Microsoft Word 97-2003 text document, converted to "docx" when edited)
* dot (Microsoft Word 97-2003 text document template, converted to "dotx" when edited)
* rtf (Rich Text Format, converted to "docx" when edited)

=== OX Spreadsheet Documents ===

OX Spreadsheet is a cloud based spreadsheet product that can work with Microsoft Excel documents. You can also edit shared spreadsheets on various devices. OX Spreadsheet is the first browser-based spreadsheet application that reads and writes native Microsoft Excel files without loss of format or detail ("Round-trip editing").

* xlsx (Microsoft Office Excel workbook)
* xlsm (Microsoft Office Excel macro-enabled workbook)
* xltx (Microsoft Office Excel workbook template)
* xltm (Microsoft Office Excel macro-enabled workbook template)
* xlsb (Microsoft Office Excel macro-enabled workbook, binary format)
* xlam (Microsoft Office Excel add-in)
* ods (OpenDocument spreadsheet document)
* ots (OpenDocument spreadsheet document template)
* xls (Microsoft Excel 97-2003 workbook)
* xlt (Microsoft Excel 97-2003 workbook template)
* xla (Microsoft Excel 97-2003 add-in)

=== OX Presenter ===

OX Presenter allows you to view presentations in a specialized user interface, where you also can give local presentations or presentations where remote participants can join.

For a list of supported file types, see "Presentation Documents" in the OX Document Viewer section above.

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

AppSuite:UI FAQ

2016-02-11T06:16:04Z

Frank.paczynski:

'''Synopsis:''' Frequently asked questions about running the App Suite UI. If you need a tool set for finding things out about the UI, see [[AppSuite:Debugging the UI]].

= Getting the UI started =
Frequently asked by new developers. And forgetful veterans. Who therefore write documentation pieces like this.

== Does show the login screen after logging in ==
This means you managed to find a bug even before our error message module could be loaded. There is something rather basic broken, maybe the DB connection or some of the standard .js

The only hint we can give from a UI perspective is to use the developer console on your browser and, if applicable, turn on "halt on all errors" or "preserve logging data". You might see an error message that otherwise gets eaten by a redirect.

If you are running the backend yourself, you are in luck, go, look at the server error log.

== Does not load, fails with error: Could not read... ==
"Could not read 'io.ox/core/http.js'"
"Could not read 'io.ox/core/events.js'"
That's not all, the system is probably hiding even more errors. It is more probable that the whole UI cannot be found. Check the com.openexchange.apps.path, usually hidden in manifests.properties. Does it point to where your webserver serves the files from? The default is /var/www/appsuite, on OSX is is more likely to be /Library/WebServer/Documents/appsuite

== App Suite loads, but no apps show up ==
So bother backend and frontend are devoid of errors, the UI loads nicely, you see the top bar with settings, notifications and refresh button but no apps at all, right? This is a manifest problem. Check the capabilities (see hint in the beginning of this page). If even those are correct, check the backend's /tmp folder and the manifest.properties there: Are the paths of <tt>com.openexchange.apps.path</tt> and <tt>com.openexchange.apps.manifestPath</tt> pointing to your build directory?

== Could not read 'io.ox/office/preview/app/... when loading anything but the portal ==
You lack preview capabilities. Since you can choose what to use, here are your options
* use the URL parameter <tt>disableFeature=document_preview%2Ctext</tt>
* figure out how to install office
* use the existing preview bundles

== After logging in I'm dumped back to the login page with a #autologin=false added to the URL ==

You might not see an error message in the console then. Configure your JS console to preserve messages on navigation (so after a redirect), and you might get a hint as to what's wrong.

= UI build environment =

There is an explicit [[AppSuite:GruntFAQ|FAQ page]] for grunt related questions when working with external modules.

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

AppSuite:Emoji

2016-02-11T05:58:36Z

Frank.paczynski:

<div class="title">Emoji Support</div>

'''Abstract.''' In this article, the support for emoji is described in detail. Learn about how different icon sets can be included and configured.
__TOC__
== Enabling emoji support ==
Emoji support is disabled by default. In order to enable the feature, you must define the capability '''emoji'''. This is done by just adding the word "emoji" to the property "permissions" in '''/opt/openexchange/etc/permission.properties''':

<pre>
permissions=...,emoji
</pre>

== Settings ==
Configuration will be served via [[AppSuite:jslob|jslob]] service at the following path.
<pre>
io.ox/mail/emoji
</pre>

The following settings are relevant for emoji support:
<pre>
io.ox/mail/emoji//defaultCollection=unified
io.ox/mail/emoji//availableCollections=unified,two,three
io.ox/mail/emoji//forceEmojiIcons=false
io.ox/mail/emoji//collectionControl=none # possible values 'none', 'tabs', 'dropdown'
io.ox/mail/emoji//autoClose=false
io.ox/mail/emoji//userCollection=emoji/defaultCollection
io.ox/mail/emoji//overrideUserCollection=false
io.ox/mail/emoji//sendEncoding=unified # possible values 'unified', 'pua'
</pre>

In order to configure this server-side, just append to existing appsuite.properties or create a new file emoji.properties (in same directory; please mind the double-slash, this in not a typo! plus: changing such settings requires a backend restart).

{|
|-
! Setting !! Description
|-
| defaultCollection || Default collection.
|-
| availableCollections || Available collections. Comma separated. The order is important, since this will be used as an order for the fallback mechanism. If an icon is not found in the userCollection, the icon is looked up in each available collection and the first 'hit' will be used.
|-
| forceEmojiIcons || always convert emoji unicode characters to img-tags
|-
| collectionControl || none, dropdown, tabs.
|-
| autoClose || Emoji pallet closes when user click or presses any key inside editor
|-
| userCollection || Current user collection
|-
| overrideUserCollection
||Set this setting to true and the current user collection will not be prefered when replacing unicode characters with an image. (See comment for availableCollections describing the fallback mechanism.) Since Mail compose works with a current collection object, this setting has no effect when inserting icons from the editor plugin into the text. But when rendering any text with unicode characters, this setting will have an effect on the icon that is shown.
|-
| sendEncoding || Override the default send encoding to use something else than unified (unicode6)
|}

== How to add a new icon set ==

It is possible to add new icon sets by [[Appsuite:Writing_a_simple_application|writing a core plugin]]. It is recommended, to install the files to

<pre>
apps/3rd.party/emoji/<iconSetName>/
</pre>

Put all your CSS code and images into this directory and create a register.js adding the CSS/LESS files as dependencies.

Once this is done, you need to add the CSS also to the tinyMCE editor, because an iframe is used to edit the text and in order to have full emoji support, you need to load the CSS code there as well. Doing so is really easy. There is an extension point you can use to add the paths to your CSS files.

<pre class="language-javascript">
define('3rd.party/emoji/greatestIconSet/register',
['io.ox/core/extensions',
'css!3rd.party/emoji/greatestIconSet/emoji.css',
'css!3rd.party/emoji/greatestIconSet/emoji_categories.css'
], function (ext) {

"use strict";

ext.point('3rd.party/emoji/editor_css').extend({
id: 'greatestIconSet/categories',
css: '3rd.party/emoji/greatestIconSet/emoji_categories.css'
});
ext.point('3rd.party/emoji/editor_css').extend({
id: 'greatestIconSet/icons',
css: '3rd.party/emoji/greatestIconSet/emoji.css'
});
});
</pre>

=== Naming conventions in CSS code ===

The CSS must follow some easy structure. There must be a base class for all icons that defines the background image. It must match the name of your icon set prefixed with “.emoji-”.

Each icon will then be identified by a string that can be defined in the icon set metadata.

Find here a short example copied from the unified icon set shipped with Appsuite.
<pre>
.emoji-unified {
background: url("emoji.png") top left no-repeat;
width: 20px;
height: 20px;
display: -moz-inline-stack;
display: inline-block;
vertical-align: top;
zoom: 1;
*display: inline;
}
.emoji2600 {
background-position: -500px -120px;
}
</pre>

[[Category:Server]]
[[Category:UI]]
[[Category:i18n]]
[[Category:Config]]
[[Category:AppSuite]]

AppSuite:Embedding your settings into AppSuite settings

2016-02-11T05:57:59Z

Frank.paczynski:

<div class="title">Embedding your settings into AppSuite settings</div>

''Synopsis:'' This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6. Not to be confused with [[AppSuite:Creating_a_settings_section_in_AppSuite_settings | simply adding new settings]] into AppSuite

__TOC__

== Declare the page you want to embed ==

You can declare pages to embed via [[ConfigCascade|Config Cascade]] settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:

➜ /opt/open-xchange/etc/settings/configjump.yml
io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
title: "Change Plan"
after: "io.ox/mail"
advancedMode: false

''io.ox/settings/configjump'' contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.

An object of this type has the following properties:

* '''url''': The URL to be branched to. The place holder [token] will be replaced by the token you get from the token login system
* '''title''': The title as to be seen on the settings page.
* '''after''', '''before''' or '''index''': Where the page is supposed to be positioned. ''Hint:'' If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL.
* '''advancedMode''': true or false to define if shown in advanced settings mode or not. Default is false

It's also possible to provide custom translations for the title. Just add "title_" plus the locale:

io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
title: "Change Plan"
title_en_US: "Change plan"
title_de_DE: "Plan ändern"
title_fr_FR: "..."
...
after: "io.ox/mail"

== Create a secret ==

Now you just need to declare the app your are about to embed in the backend and you are good to go:

➜ cat /opt/open-xchange/etc/tokenlogin-secrets
#
# Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
#
# e.g. 1254654698621354; accessPasword=true
#

# Dummy entry
# 1234-56789-98765-4321; accessPassword=true
12345-phpapp-54321

This secret, combined with the token, can be traded for a login.

== Redeem a token ==

GET /login?action=redeemToken

* '''token''': The token you want to trade.
* '''secret''': A valid secret for your app.

This request can be sent by the embedded app to the AppSuite backend to get authorisation info.

[[Category:AppSuite]]

[[Category:UI]][[Category:Backend]]

[[Category:Administrator]][[Category:Developer]]

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

AppSuite:Device reference

2016-02-11T05:39:11Z

Frank.paczynski:

{{Stability-unstable}}

<div class="title">_.device() reference</div>

The function <tt>_.device()</tt> is used to test various device-specific aspects of the runtime environment. It is also used to evaluate the <tt>device</tt> clause of manifest entries.

__TOC__

= Syntax =

The single parameter of the function is a string describing the test to perform. The string is evaluated as a JavaScript expression which uses one or more pre-defined variables. The result is then always converted to a boolean value. Empty strings and other 'falsy' values evaluate to <tt>true</tt>. While the implementation currently simply uses the native JavaScript interpreter, only parentheses, boolean operators and numerical comparisons are guaranteed to actually work.

= Variables =

This section lists the supported variable names which can be passed to <tt>_.device()</tt>. The current list of variables and their values can be displayed by calling <tt>_.device()</tt> without arguments in the browser's JavaScript console. All variables are case-insensitive, and by convention are lower-case.

While all variables can be used as boolean flags, most variables representing browsers and operating systems are actually numbers and can be used to check for specific browser or OS versions. The remaining browser and OS variables can become numbers in the future, too. The numbers are usually integers, i.e. they contain only the major version number.

== Browsers ==

* Numeric versions
** <tt>ie</tt>
** <tt>opera</tt>
** <tt>safari</tt>
** <tt>phantomjs</tt>
** <tt>chrome</tt>
** <tt>firefox</tt>
* Boolean flags
** <tt>webkit</tt>
** <tt>chromeios</tt>
** <tt>uiwebview</tt>

== Operating systems ==

* Numeric versions
** <tt>blackberry</tt>
** <tt>ios</tt>
** <tt>android</tt>
* Boolean flags
** <tt>windowsphone</tt>
** <tt>macos</tt>
** <tt>windows</tt>

== Display metrics ==

* <tt>small</tt> (up to 480px)
* <tt>medium</tt> (481px to 1024px)
* <tt>large</tt> (1025px and more)
* <tt>landscape</tt>
* <tt>portrait</tt>
* <tt>retina</tt>
* <tt>smartphone</tt>
* <tt>tablet</tt>
* <tt>desktop</tt>

== Language ==

The current language code is defined as a variable. To match any variant of the current language, the second part can be replaced by an asterisk. E.g. if the current language is en_US, then the following variables would be defined:

* <tt>en_us</tt>
* <tt>en_*</tt>

== Miscellaneous ==

* <tt>touch</tt>
* <tt>standalone</tt>
* <tt>emoji</tt>

= Examples =

The simplest example is a single variable, e.g.
<pre class="language-javascript">_.device('smartphone')</pre>
<pre class="language-javascript">_.device('firefox')</pre>
or
<pre class="language-javascript">_.device('de_*')</pre>

Workarounds for specific older browsers can be enabled by testing for a specific version, e.g.
<pre class="language-javascript">_.device('ie && (ie < 11)')</pre>
The additional check for the correct browser is necessary because in other browsers, the variable <tt>ie</tt> evaluates to <tt>undefined</tt>, and the comparisons with numbers always return <tt>false</tt>. This may or may not be what is desired, so an explicit check for the browser is less error-prone and easier to understand.

AppSuite:Debugging production servers

2016-02-11T05:36:52Z

Frank.paczynski:

{{Stability-experimental}}
<div class="title">Debugging production servers</div>

A how-to for debugging your local UI plugin in combination with production and staging servers, which use redirects, HTTPS, and other things which break with the auto-generated Grunt configuration.

== Introduction ==

Not everybody has access to a dedicated test server. Sometimes, a plugin requires a backend system which is hard to access outside of existing infrastructure. And sometimes, a bug appears only on a production server. There are many reasons why a server which is used by <tt>grunt dev</tt> can not be reconfigured and has to be used as-is.

The most frequent reason, why debugging with a remote server fails, is a redirect to an external login page. After the login, the browser is usually redirected to the original domain, and all the cookies used for authentication are also set for that domain, not http://localhost:8337, where Grunt listens.

The solution is to use grunt as an HTTP proxy server, which intercepts all requests to the server's domain.

In this article, <tt>''example.com''</tt> is user for the server domain, which you should replace by the real domain of the OX server.

== Configuring Grunt ==

Following is an example <tt>grunt/local.conf.json</tt> file:

{
"proxy": true,
"appserver": {
"protocol": "https",
"livereload": false,
"server": "https://''example.com''/''custom-path''/",
"path": "/''custom-path''/",
"rejectUnauthorized": false,
"verbose": [],
"prefixes": [
"build/",
"../../web/ui/build"
],
"manifests": [
"build/manifests/",
"../../web/ui/build/manifests"
]
},
"debug": true,
"coreDir": "../../web/ui/build"
}

The relevant settings are:

;<tt>"proxy": true</tt>
: instructs Grunt to start an HTTP proxy on port 8080. Note that the value is outside the <tt>"appserver"</tt> section.
;<tt>"protocol": "https"</tt>
: to use HTTPS on port 8337.
;<tt>"livereload": false</tt>
: because LiveReload can't be proxied.
;<tt>"path": "/''custom-path''/"</tt>
: must correspond to the path in the <tt>"server"</tt> entry and will in most cases be <tt>"/appsuite/"</tt>.
;<tt>"rejectUnauthorized": false</tt>
: is helpful with certificate problems, especially for integration tests of the login mechanism on a POC system with self-signed certificates.
;<tt>"index": "/"</tt>
: If the main path uses an HTTP redirect for a custom login page, then the initial request should not be intercepted by Grunt. Adding this entry in the <tt>"appserver"</tt> section disables the interception. This has two side-effects:
:# The main HTML file is always served by the original server, and therefore
:# The timestamps used for cache-busting are not updated by Grunt.
:Unfortunately, this means clearing the cache will be required more often. If that becomes too much overhead, you can log in, then remove the option and restart Grunt.

== Generating certificates ==

To avoid unnecessary warnings in the browser, Grunt can use a set of certificates which are trusted by the browser. For local use, a self-created CA should be enough. By default, Grunt looks for the certificates in the subdirectory <tt>ssl</tt>, so you can create them there with the following commands:

mkdir ssl
cd ssl
openssl req -x509 -newkey rsa:4096 -keyout rootCA.key -days 3650 -out rootCA.crt
openssl req -newkey rsa:4096 -nodes -keyout host.key -out host.csr

While most data entered for the certificates doesn't matter, the Common Name for the certificate signing request in the second <tt>openssl</tt> command must match the domain of the <tt>"server"</tt> setting in <tt>local.conf.json</tt>. Alternatively, it can be a higher domain with a wildcard, e.g. <tt>*.example.com</tt> for <tt>"server": "https://my.example.com/appsuite/"</tt>.

openssl x509 -req -in host.csr -CA rootCA.crt -CAkey rootCA.key \
-CAcreateserial -out host.crt -days 365

<tt>host.csr</tt> is only temporary and can be deleted now. Only the files <tt>rootCA.crt</tt>, <tt>host.key</tt> and <tt>host.crt</tt> are used by Grunt. The <tt>rootCA.*</tt> files can be reused to create multiple host certificates. The first <tt>openssl</tt> command then only needs to be executed once. The <tt>host.*</tt> files can also be reused as long as the domain(-wildcard) matches.

The file <tt>rootCA.crt</tt> needs to be imported into your browser as a trusted certificate authority (only once, if you are going to reuse the <tt>rootCA.*</tt> files). For Firefox, look in Preferences → Advanced → Certificates → View Certificates → Authorities → Import...
For Chrome, look in Settings → Show advanced settings... → HTTPS/SSL → Manage certificates... → Authorities → Import...
Since the authority can sign certificates for any domain, and its key is not protected much, it's better to not use the browser(-profile) which trusts this authority for normal Internet browsing.

== Launching the browser ==

After starting the proxy with <tt>grunt dev</tt>, you just need to use it when debugging your code in the browser. Most browsers have their own proxy settings, which override system-wide settings. They also respect environment variables like <tt>http_proxy</tt>.

http_proxy=http://localhost:8080 firefox

Chrome does not have its own settings (it starts the global settings dialog) and it ignores <tt>http_proxy</tt>. Instead, you have to use a command line parameter:

chromium --proxy-server=http://localhost:8080

AppSuite:Configuration

2016-02-11T05:24:59Z

Frank.paczynski:

{{Stability-experimental}}
<div class="title">Configuration</div>
Overview of server-side settings mainly hiding/disabling front end elements without affecting backend. Please mind that this listing isn't complete yet.

==Folders: hiding folders in panel==
In order to configure this server-side, just create a new property file in '''/opt/open-xchange/etc/settings''' or append to the existing file '''/opt/open-xchange/etc/settings/appsuite.properties''' (mind the '''double-slash'''; this in not a typo!):
<pre class="language-config">
io.ox/core//folder/blacklist/<id>=true|false

# example: hide global address book
io.ox/core//folder/blacklist/6=true
</pre>

'''Avoid white-space between the folder id and equal sign!'''

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

==Mediaplayer: enabling/disabling ==
Please take a look at the [[ AppSuite:Mediaplayer#How_to_enable.2Fdisable_the_media_player | media player article ]]

AppSuite:Custom configurations

2016-02-11T05:16:52Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Custom configurations</div>

'''Abstract:''' This article is a summary of special settings to customize the ui. This article is still in developement. It is not complete and may change.

__TOC__

==Mail==

These are special settings for the mail app.

io.ox/mail/features/alwaysDeleteDraft: true/false

This setting is used when drafts should always be deleted when sending them. This is useful if you don't want to manually delete your not needed drafts. Keep in mind that this will affect every draft, with this setting drafts that were used as templates will also be deleted when sending.

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

AppSuite:External libraries for the UI

2016-02-11T05:14:15Z

Frank.paczynski:

{{Stability-stable}}

'''Abstract: ''' An overview over libraries that are used by the UI, either when running or when building it. The field "modified" is a hint that simply updating the library to a newer version might break some feature that we depend on. Feel free to explain the details of the change, too.

== UI ==
Libraries that are used by the frontend, as delivered to the customer, are listed here: [http://www.open-xchange.com/licenses-ox-app-suite List of 3rd party libraries used in the UI]

== Build system ==
{|
! Name & Link
! License
! Modified?
|-
| [http://nodejs.org Node.js] <em>not included</em>
|
|
|-
| [https://github.com/mde/jake Jake]
| Apache
| Yes
|-
| [https://github.com/mishoo/UglifyJS#readme UglifiyJS]
| BSD
| No
|-
| [http://jshint.com/ JSHint]
| modified MIT license
| No
|-
| [http://vowsjs.org/ Vows]
| BSD
| No
|-
| [https://github.com/cloudhead/eyes.js eyes.js]
| BSD
| No
|-
| [https://github.com/isaacs/rimraf rimraf]
| BSD
| No
|-
| [http://lesscss.org/ LESS]
| Apache
| No
|-
| [https://github.com/isaacs/sax-js sax-js]
| MIT
| No
|-
| [https://github.com/Leonidas-from-XIV/node-xml2js node-xml2js]
| MIT
| No
|-
| [https://github.com/zzdhidden/node-jquery-deferred node-jquery-deferred]
| MIT
| No
|}

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

AppSuite:Upsell

2016-02-10T13:58:23Z

Frank.paczynski:

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

'''Abstract.''' This article is mainly for UI developers and introduces the concept of upsell from a technical point of view. In short: End-user has a set of so-called ''capabilities''. UI, however, offers functionality beyond that limited set for promotion purposes. Actions, e.g. inline links, that require missing capabilities trigger an '''in-app upsell'''. This process leads to a trial period or a new subscription. Technical challenge for the UI developer is to check what the end-user has, what can be shown beyond that, and how to handle upsell. It is also possible for hosting companies to easily integrate their own online shop into OX Upsell, since the internal mechanisms are ''loosely coupled'' via events.
__TOC__
==Enable upsell==
In order to configure upsell server-side, just create a new file '''upsell-appsuite.properties''' or append to existing '''appsuite.properties''' (mind the '''double-slash'''; this in not a typo!). If you configure upsell in the '''upsell-appsuite.properties''' the properties are loaded when you trigger the '''live reload''' function.

<pre class="language-settings">
io.ox/core//upsell/enabled/infostore=true
io.ox/core//upsell/enabled/portal=true
io.ox/core//upsell/enabled/tasks=true
</pre>
Each line enables a specific [[AppSuite:Upsell#Capabilities|capability]] for upsell. That means whenever a feature misses one these capabilities a special upsell-related event is triggered.

Hint: For simple demo purposes, you can enable an internal upsell configuration by appending '''"&demo=upsell"''' to the URL. Needs to reload page, of course.

==Custom upsell links==
Since other upsell triggers than the usual links would require custom development of the UI, the appsuite provides several upsell triggers which can be configured via settings. Those triggers will appear, when the expression of required capabilities is not satisfied and the required set of upsell triggers is satisfied. If you configure the upsell settings, the custom upsell triggers will be enabled by default but you can disable them if you want to.

===Example===

To clearify, when triggers are shown or not, we proceed with an example: A hoster can provide a custom upsell trigger in the secondary toolbar (next to the reload icon). This upsell trigger is inteded to sell a premium account to a user and has the default requirement of '''active_sync''' OR '''caldav''' OR '''carddav'''. That means, if one of those capabilities is not set for a user and the upsell is activated for '''active_sync''' AND '''caldav''' AND '''carddav''' the upsell trigger will be shown. You can enable upsell for those capabilities with
<pre class="language-settings">
io.ox/core//upsell/enabled/active_sync=true
io.ox/core//upsell/enabled/caldav=true
io.ox/core//upsell/enabled/carddav=true
</pre>
inside an existing or new '''.properties''' file. Note that you have to restart the server so that the changes take place.

If a user clicks on the upsell trigger, a upsell event of type 'custom' and with id 'secondary-toolbar' is triggered so that the page or dialog which will be opened can react depending on the clicked link.

===Change appearance===

Any custom upsell triggers which have icons will use a '''fa-star''' as default icon. You can change the default icon to any font-awesome icon (or a set of space separated icons) via
<pre class="language-settings">
io.ox/core//upsell/defaultIcon="fa-star"
</pre>

You can also change the icon of individual custom triggers with
<pre class="language-settings">
io.ox/core//features/upsell/$id/icon="fa-star"
</pre>
where $id is the id of the upsell trigger.

The color of custom upsell links can be changed with
<pre class="language-settings">
io.ox/core//features/upsell/$id/color="#f00"
</pre>
where $id is the id of the upsell trigger and the color string can be any css color string.

If you want to disable a custom upsell trigger, then you can add
<pre class="language-settings">
io.ox/core//features/upsell/$id/enabled=false
</pre>
to a '''.properties''' file.

===Customize strings===

Some of the custom upsell triggers use have a title (or other strings) which a hoster could customize. It is important, that several translations are provided. You can provide your own texts via
<pre class="language-settings">
io.ox/core//features/upsell/$id/i18n/$lang/title="A custom title"
</pre>
where $lang is the current language identifier (e.g. "en_US"). You can see the current language identifier when you open the webconsole and type
<pre class="language-settings">
ox.language
</pre>

===Customize required capabilities===
If you want certain upsell triggers to appear on different capabilities, you can configure this inside a .properties file. Therefore, you have to configure the '''requires''' field of the appropriate trigger. This field expects a logical expression of capabilities. The following example requires eas and caldav or not carddav. If the actual capabilities does not satisfy the expression and the upsell capabilites satisfy this expression, the upsell trigger will be drawn.
<pre class="language-settings">
io.ox/core//features/upsell/$id/requires="active_sync && (caldav || !carddav)"
</pre>

===List of custom triggers===

This sections lists the custom triggers and how they can be configured.

{|
|-
! ID !! Config !! Texts !! Default capabilities !! Description
|-
| secondary-launcher
| icon, color
| title
| active_sync or caldav or carddav
| This trigger is located in the secondary toolbar left of the notifications icon. It can contain an icon and text and can be colored. It is intended as '''upgrade to premium''' trigger. This trigger is not shown on mobile devices due to space limitations.
|-
| folderview/mail
| icon, color
| title
| active_sync
| This trigger is located below the folderview of mails.
|-
| folderview/mail/bottom
| color
| title
| active_sync
| This trigger is located at the bottom of the folderview of the mail app in the premium area. This trigger is styled as a button with the default text 'Try now' and has no icon by default.
|-
| folderview/contacts
| icon, color
| title
| carddav
| This trigger is located below the folderview of the address book.
|-
| folderview/contacts/bottom
| color
| title
| carddav
| This trigger is located at the bottom of the folderview of the contacts app in the premium area. This trigger is styled as a button with the default text 'Try now' and has no icon by default.
|-
| folderview/calendar
| icon, color
| title
| caldav
| This trigger is located below the folderview of the calendar.
|-
| folderview/calendar/bottom
| color
| title
| caldav
| This trigger is located at the bottom of the folderview of the calendar app in the premium area. This trigger is styled as a button with the default text 'Try now' and has no icon by default.
|-
| folderview/infostore/bottom
| color
| title
| boxcom or google or msliveconnect
| This trigger is located at the bottom of the folderview of the drive app in the premium area. This trigger is styled as a button with the default text 'Try now' and has no icon by default.
|-
| topbar-dropdown
| icon, color
| title
| active_sync or caldav or carddav
| This trigger is located on the first position of the dropdown in the secondary toolbar. It contains a text and an icon.
|-
| portal-widget
| imageURL, removable (boolean), icon
| title
| active_sync or caldav or carddav
| This trigger adds a draggable portal widget to the appsuite portal. This widget is not removable by default and displays a default text. A customer can add a backgroundimage with '''imageURL''' and can make this widget removable by setting '''removable''' to true. If no image is used, the widget displays the title in the center with a customizable space separated list of font-awesome icons.
|-
| mail-folderview-quota
| upsellLimit, icon, color
| title
| active_sync or caldav or carddav
| This trigger is appended below the mail quota in the folderview. You can set the '''upsellLimit''' (in Bytes). If the maximum mail quota is larger than '''upsellLimit''', the upsell button will not be shown. This upsell trigger has no icon by default.
|}

==Upsell Wizard==
<div style="color: #3A87AD; text-align: right; margin: -1em 0 1em 0; padding: 0.5em; background-color: #D9EDF7;">Shipped with 7.2.1</div>
Customers usually want to offer context-sensitive content in an IFRAME if the upsell is triggered. Therefore, App Suite comes with an integrated but optional plugin that takes care of this. Just enable ''plugins/upsell/simple-wizard'' by [[AppSuite:Capabilities#Set_a_capability|setting the capability]] '''simple-wizard''' server-side (or by adding it to the URL '''...&cap=simple-wizard''' for testing/development purposes).

This plugin registers for the event ''"upsell:requires-upsell"'', opens a modal popup, and loads a custom URL in an embedded IFRAME.

[[File:Simple_upsell_wizard.png|800 px|Custom content in an IFRAME]]

===Wizard settings===
In order to configure this server-side, just create a new file '''upsell.properties''' or append to existing '''appsuite.properties''' (mind the '''double-slash'''; this in not a typo! plus: changing such settings requires a backend restart):
<pre class="language-settings">
plugins/upsell/simple-wizard//url=blank.html?user=$user,user_id=$user_id,context_id=$context_id
plugins/upsell/simple-wizard//overlayOpacity=0.5
plugins/upsell/simple-wizard//overlayColor=black
plugins/upsell/simple-wizard//zeroPadding=true
plugins/upsell/simple-wizard//width=750
plugins/upsell/simple-wizard//height=390
plugins/upsell/simple-wizard//closeButton=true
</pre>

{|
|-
! Settings !! Description
|-
| url
| Custom URL that is loaded in IFRAME; can contain special [[AppSuite:Upsell#Custom_URL_variables|variables]].
|-
| overlayOpacity
| CSS opacity value for overlay; default is 0.5
|-
| overlayColor
| CSS background color for overlay; default is black
|-
| zeroPadding
| If true (default) there is no inner padding inside modal dialog, i.e. the IFRAME covers the popup
|-
| width
| Width of outer popup (not IFRAME) in pixel
|-
| height
| Height of IFRAME in pixel
|-
| closeButton
| If true (default) the wizard shows its own close button
|}

===Custom URL variables===
The plugin offers a set of variables that help providing context-sensitive content. ''$missing'' is probably the most prominent one. Other variables help identifying the user. An example:

<pre class="language-setting">
upsell.php?user_id=$user_id&context_id=$context_id&language=$language&missing=$missing
</pre>
{|
|-
! Variable !! Description
|-
| $context_id
| context_id of current user
|-
| $hostname
| hostname of current session, e.g. www.one-of-countless-virtual-hosts.com
|-
| $id
| The trigger's identifier, e.g. "io.ox/files". Can refer to an app, an inline action, or a portal plugin. See $type
|-
| $imap_login
| The current user's imap login
|-
| $language
| The current user's language, e.g. de_DE or en_US
|-
| $mail
| The current user's primary email address
|-
| $missing
| The set of missing capabilities, comma separated, e.g. "files"
|-
| $session
| The current user's session id
|-
| $type
| Either app, inline-action, or portal-widget. Describes what triggered the upsell. See $id
|-
| $user
| The current user's login name (can include context name, i.e somebody@foo)
|-
| $user_id
| The current user's numeric id
|-
| $user_login
| The current user's login (usually without context name)
|}

===Develop and debug===
While experimenting or developing, you can use the following helpful functions:
<pre class="language-javascript">
// get plugin (this must be properly loaded, otherwise you get a runtime error)
var wizard = require('plugins/upsell/simple-wizard/register');

// if you have no chance to enabled this plugin server-side, use the following approach
// but don't use this in production plugins, it's just a hack for console:
// if you don't know the difference please take a look at
// http://requirejs.org/docs/errors.html#notloaded
var wizard; require(['plugins/upsell/simple-wizard/register'], function (w) { wizard = w; });

// get variables (optional: options from upsell:require-upgrade event)
wizard.getVariables({ type: 'app', id: 'io.ox/files', missing: 'files' });

// get URL (optional: options from upsell:require-upgrade event)
// replaces placeholders ($foo) by variable values
wizard.getURL({ type: 'app', id: 'io.ox/files', missing: 'files' });

// get all settings (can be changed on the fly)
console.log(wizard.settings);

// global upsell events; parameters: (e, popup)
ox.on('upsell:simple-wizard:show:before', _.inspect);
ox.on('upsell:simple-wizard:show', _.inspect);
ox.on('upsell:simple-wizard:close', _.inspect);

// special event to customize settings (e, variables, settings)
// triggered before creating dialog instance;
// 2nd parameter has variables like type, missing, user_id etc.
// 3rd parameter refers to a local copy of wizard settings
ox.on('upsell:simple-wizard:init', _.inspect);

// open wizard manually
wizard.open();

// close wizard manually
wizard.close();

// disable wizard (unregisters upsell event)
wizard.disable();

// and of course: enable wizard (registers for upsell event)
wizard.enable();
</pre>
Some examples for customizations in UI plugins or in console:
<pre class="language-javascript">
// get plugin (this muse be properly loaded, otherwise you get a runtime error)
var wizard = require('plugins/upsell/simple-wizard/register');

// extend IFRAME constructor (see http://underscorejs.org/#compose)
var custom = function (iframe) {
return iframe.css({ border: '5px solid #08c', boxSizing: 'border-box' });
};
wizard.getIFrame = _.compose(custom, wizard.getIFrame);

// use an event to customize the IFRAME
ox.on('upsell:simple-wizard:show:before', function (e, popup) {
popup.getContentNode().find('iframe')
.css({ border: '5px solid #08c', boxSizing: 'border-box' });
});
</pre>

===Close wizard===
The upsell wizard can easily be closed via javascript or by redirecting the IFRAME to a prepared HTML page. In order to see this in action, run the following code (step by step):
<pre class="language-javascript">
// get plugin (this must be properly loaded, otherwise you get a runtime error)
var wizard = require('plugins/upsell/simple-wizard/register');

// open wizard
wizard.open();

// redirect now
wizard.setSrc('apps/plugins/upsell/simple-wizard/close.html');
</pre>

Custom backend systems that run on a different domain cannot use javascript to close the wizard [http://en.wikipedia.org/wiki/Cross-site_scripting]. However, such systems can redirect to ''close.html''. Since this page is part of the UI and therefore located on the same domain, it is allowed to call the wizard's close function.

==Custom development==
This section documents some of the inner workings of the upsell layer. It should provide some useful insights and hopefully helps at implementing custom upsell solutions.
===Events===
Whenever the user starts an app or clicks on an inline-action, a capability-check is performed. For example, all inline actions have native support for such checks:

<pre class="language-javascript">
new Action('io.ox/calendar/detail/actions/sendmail', {
// this action requires the capability "webmail"
capabilities: 'webmail',
action: function (baton) {
// send mail
}
});
</pre>

If the end-user does not have "webmail" (e.g. in a files-only setup) but calls this action, a proper event is fired:

<pre class="language-javascript">
// if any action misses a capability
ox.trigger('upsell:requires-upgrade');
// which provides the following data for apps:
{
type: "app", // type of the upsell trigger
id: "io.ox/mail/main", // upsell trigger ID
missing: "webmail"
}
// and for inline-actions:
{
type: "inline-action",
id: "io.ox/calendar/detail/actions/sendmail",
missing: "webmail"
}
</pre>

===Capabilities and Upsell triggers===
There are lots of different capabilities. They are defined on the server-side and basically they are just strings. Let's keep it simple and understand them as either services (e.g. mobility), specific functionalities (e.g. multiple_mail_accounts) or applications (e.g. calendar). Some obvious examples:

{|
|-
! Capability !! Description !! Upsell trigger (if capability is missing)
|-
| calendar
| User has "Calendar" app
|
* Mail/All recipients: Invite to appointment
* Add portal widget
* Top bar
|-
| contacts
| User has "Address Book" app
|
* Mail/App recipients: Save as distribution list
* Calendar: Save participants as distribution list
* Top bar
|-
| infostore
| User has "Files" app
|
* Mail: Save in infostore
* Add portal widget (My latest files, Recently changed files)
* Top bar
|-
| portal
| User has "Portal" app
|
* Mail: Add to portal
* Contacts: Add to portal
* Files: Add to portal
* Top bar
|-
| tasks
| User has "Tasks" app
|
* Mail: Remind me
* Add portal widget
* Top bar
|-
| webmail
| User has "Mail" app
|
* Calendar: Send mail to all participants
* Contacts: Send mail
* Contacts: Send vCard
* Files: Send as link
* Files: Send by mail
* Add portal widget
* Top bar
|}

<pre class="language-javascript">
// list all available capabilities
_(ox.serverConfig.capabilities).pluck('id').sort();
</pre>

An example: Free-mail users might just have '''webmail''' and '''contacts'''. If '''infostore''' is enabled for upsell, end-users will see the link to store mail attachments. But since this capability is missing, the event "upsell:requires-upgrade" is triggered which starts the upsell process. Upon successful completion this process should unlock the capability '''infostore''' for the end-user.

The advantage of using rather atomic capabilities as the foundation for upsell is that developers don't have to consider and implement sales programs or marketing matrices in UI code.

===Example dialog===
Whenever the event ''"upsell:requires-upgrade"'' is triggered there should be some response for the end-user. Usually an upsell dialog should open. This can be implemented as follows:

<pre class="language-javascript">
function showUpgradeDialog(e, options) {
require(['io.ox/core/tk/dialogs'], function (dialogs) {
new dialogs.ModalDialog({ easyOut: true })
.build(function () {
this.getHeader().append(
$('<h4>').text('Upgrade required')
);
this.getContentNode().append(
$.txt('This feature is not available.'),
$.txt('You need to upgrade your account now.'),
$.txt(' '),
$.txt('The first 90 days are free.')
);
this.addPrimaryButton('upgrade', 'Get free upgrade');
this.addButton('cancel', 'Cancel');
})
.setUnderlayStyle({
opacity: 0.70,
backgroundColor: '#08C'
})
.on('upgrade', function () {
ox.trigger('upsell:upgrade', options);
})
.on('show', function () {
ox.off('upsell:requires-upgrade', showUpgradeDialog);
})
.on('close', function () {
ox.on('upsell:requires-upgrade', showUpgradeDialog);
})
.show();
});
}

function upgrade(e, options) {
console.debug('upgrade', options);
alert('User decided to upgrade! (global event: upsell:upgrade)');
}

ox.on('upsell:requires-upgrade', showUpgradeDialog);

/*
* convention: 'upsell:upgrade' is used to trigger final upsell
* the current user and user_id can be found in global variables ox.user and ox.user_id
*/
ox.on('upsell:upgrade', upgrade);

</pre>

The second event '''"upsell:upgrade"''' can be understood as the final imperative to request the upsell server-side.

===Example portal widget===
Besides waiting for the user to click on such links, it's always a good idea to offer explicit controls to trigger an upsell. One option is creating a portal widget that advertises a premium subscription:

<pre class="language-javascript">
/**
* This work is provided under the terms of the CREATIVE COMMONS PUBLIC
* LICENSE. This work is protected by copyright and/or other applicable
* law. Any use of the work other than as authorized under this license
* or copyright law is prohibited.
*
* http://creativecommons.org/licenses/by-nc-sa/2.5/
* © 2013 Open-Xchange Inc., Tarrytown, NY, USA. info@open-xchange.com
*
* @author Matthias Biggeleben <matthias.biggeleben@open-xchange.com>
*/

define('plugins/portal/upsell/register',
['io.ox/core/extensions',
'io.ox/files/api',
'gettext!plugins/portal'], function (ext, api, gt) {

'use strict';

var title = gt('Upgrade to premium');

ext.point('io.ox/portal/widget/upsell').extend({

title: title,

preview: function (baton) {

this.addClass('hide-title').append(
$('<div class="content centered" style="cursor: pointer; padding-top: 3em;">').append(
$('<h2>').append(
$.txt(title + ' '),
$('<i class="icon-star">')
),
$('<div>').text(gt('Click here for free trial.'))
)
.on('click', function () {
ox.trigger('upsell:upgrade', {
type: 'widget',
id: 'io.ox/portal/widget/upsell',
missing: ''
});
})
);
}
});
});
</pre>

===Accessing upsell settings===
The upsell configuration is located in the namespace ''"io.ox/core"'', the path is ''"upsell/enabled"''. Example:

<pre class="language-javascript">
// get all capabilities that can trigger upsell
require('settings!io.ox/core').get('upsell/enabled');

// contains data like this
{
infostore: true,
portal: true,
tasks: true
}
</pre>

If upsell is '''not''' enabled and the end-user lacks specific capabilities, the app or the inline-action is not shown. If upsell is enabled by the upper configuration, inline-actions are shown and trigger the upsell event ''"upsell:requires-upgrade"'' if clicked (but do not execute the action itself).

<pre class="language-javascript">
/*
* if you want to create your own controls, you can use the following helpers
*/
var upsell = require('io.ox/core/upsell');

// check capabilities (space-separated)
upsell.has('portal webmail');

// get missing capabilities (would return "calendar" in demo mode)
upsell.missing(['portal webmail', 'contacts', 'calendar']);

/* checks if upsell is enabled for a set of capabilities
* true if at least one set matches
*/
upsell.enabled(['portal webmail', 'webmail calendar']);

/* convenience function: "visible"
* checks if something should be visible depending on required capabilities
* true if any item matches requires capabilities
* true if any item does not match its requirements but is enabled for upsell
* this function is used for any inline link, for example, to decide whether or not showing it
*/
upsell.visible(['portal webmail', 'contacts', 'calendar']);

// likewise if neither capability set nor enabled for upsell, we get a false
upsell.visible(['foo']);

// in case something weird happens (usually bad configuration) debug() helps
upsell.debug();

// and this one
_(ox.serverConfig.capabilities).pluck('id').sort();

</pre>

==Upsell in OX6==
Please also consider [[Upsell|this article]] as it also covers backend aspects.

[[Category:Upsell]]
[[Category:AppSuite]]
[[Category:UI]]

AppSuite:Upsell tools

2016-02-10T13:51:27Z

Frank.paczynski:

'''Synopsis:''' This article introduces several ways of promoting applications and other upgrades for App Suite. Sine Upsell is usually very customer specific, we do only provide the framework.

__TOC__

== The Upsell Widget ==
The Upsell widget is a widget displayed on the portal. It can show images, text or combinations thereof. A widget can contain several "slides". A click on the widget starts the Upsell Wizard. There can be more than one Upsell Widget (just remember not to annoy your customer with too many!). Upsell widgets can be moved, but not removed from the portal.

The Upsell Widget needs two different configurations:
io.ox/portal//widgets/protected:
upsellads_0:
plugin: "plugins/portal/upsellads/register"
type: "upsellads"
index: 0
changeable:
index: true
props:
ad: "openexchangeAdvertisement"

This part defines a widget as protected. This is not upsell-specific, it is [[AppSuite:Configuring_portal_plugins|an option for every kind of portal widget]]. The upsell-specific part is the value of "props/ad", which identifies the content via the name "openexchangeAdvertisement". That name points to another part of the YAML file that looks like this:

plugins/upsell//ads:
delayInMilliseconds: 10000
openexchangeAdvertisement:
upsellWizard: "shop"
slides:
en_US:
slide1:
type: text-bottom
image: 'https://image1'
text: 'Awesome stuff'
slide2:
type: text-top
image: 'https:image2'
text: 'More awesome stuff'

What you can see here is that an advertisement consists of several slides. Due to some peculiarities of the App Suite YAML parser, you have to name them "slide?" with a number and cannot use an array. The slides will be sorted alphabetically, so if you plan to use more than 10 slides, remember to pad the number with enough zeros, the first slide being 00, the second being 01.

Slides can be provided in different languages. This example provides slides only for en_US. The slides need to match the user language exactly (sorry, no smart guessing so that British users with en_UK get the en_US version). The system defaults to en_US when no appropriate language can be found.

The delayInMilliseconds represents the transition time from one slide to the next.

The text can contain HTML and is inserted via the innerHtml method of JQuery in case you feel the need for markup.

The value of "image" is put into the src attribute of an <img/;gt; element, so you can use a local path as well as a URL.

The type can be one of text-top, text-bottom, text-only and image-only. Text usually takes up a third of an ad that also contains an image. Text and image are cut off in case they exceed the space.

== The Upsell Bubbles ==
Upsell bubbles are little popups based on hopscotch, similar to the [[AppSuite:Guided tours|guided tours]]. They show up after a given amount of time and point to a defined UI element to display some text. Clicking on them starts the Upsell Wizard (unless you click "cancel", of course).

plugins/upsell//bubbles:
skipFirstLogin: true
repeatInMilliseconds: 900000
repeatPerLogins: 1
bubbles:
en_US:
bubble1:
app: 'io.ox/portal'
content: "Did you know...?"
startDate: '2013-07-01'
endDate: '2019-06-31'

Upsell bubbles appear after the amount of time in ''repeatInMilliseconds'' has passed. They can be set up not to bother the first time user (''skipFirstLogin'') and only to show up ''repeatPerLogins''-times every login.

As with Upsell Widgets, they can be internationalized, this example only contains a version for American English (en_US). The name must match the user locality exactly. You can have several bubbles.

Each bubble can be set up to be valid only during a certain time span (or from a date, or to a date), but this can be omitted. Each bubble needs to point to one application.

== The Upsell Wizard ==
The Upsell Wizard is a small shopping cart application that displays things that can be sold. They process is the usual three-step process of putting items in your cart, reviewing them and ordering them. Upon completion the Wizard calls an URL with the ordered items as well as the shoppers's ID and context number. It is left to the provider to implement some handler for that.

plugins/upsell//shop:
priceFormat: '$%sUSD'
target: 'http://localhost/order-confirmation?cartContents=OXUPSELLCART&context=OXUPSELLCONTEXT&user=OXUPSELLUSER'
disclaimer:
en_US: 'You're going to sell your soul to us'
products:
en_US:
p0:
image: 'https://product-image1'
title: 'All - special offer'
price: 99
description: 'This Special Offer is only for a limited time. '

The price format is given as format string to provide maximum flexibility. ''%s'' represents the amount.

The target is the URL that is called after shopping is completed. The values OXUPSELLCART, OXUPSELLCONTEXT and OXUPSELLUSER are replaced by the Wizard with a comma-separated list of the ids of items bought, the buyer's context ID and their user ID.

The disclaimer can be internationalized like texts for upsell widgets and bubbles. The same possibilities and restrictions apply.

Products shown can also be country-specific. If only one locality (here: en_US) is given, that is always picked.

A product consists of an image (displayed on the left), a title (on the right), a description and a price value. The description can, as usual, be marked up as HTML.

== Making all of it work ==
The configuration for all three elements is done in YAML instead of JavaScript, assuming that most users of this feature are not developers but from marketing or sales departments. They will probably need starting help from a sysadmin, though, as by default, the whole Upsell process is disabled two-fold:
* The configuration file is not deployed. To do so, one needs to create one in the settings subfolder of the server configuration. This is usually /opt/openexchange/etc/settings. And example can be found in the UI folder as upsell-examples.yml
* The capability is not enabled. It is called "upsell" and, well, needs to be enabled.

After that, a server restart (necessary for every config change, sorry!) and some hard refreshing to get rid of eventual caching artefacts, you are good to go!

[[Category:AppSuite]]
[[Category:Sales]]
[[Category:Administrator]]

AppSuite:Upgrade app using yo

2016-02-10T13:50:33Z

Frank.paczynski:

<div class="title">Upgrade an app using yo</div>

__TOC__

With the release of App Suite version 7.6.0, we moved towards more easy dependency management for UI modules. We switched to grunt as a task-runner and are using npm and bower to handle dependencies. This article should provide a short guide on what to do in order to upgrade your app to the latest and greatest version of our shared grunt configuration and other development tools.

<div style="clear: both"></div>

== Development Tools ==

First, you might want to check on the versions of the tools which are necessary for UI development.

$ npm outdated -g grunt-cli bower yo generator-ox-ui-module

It's good to have those up-to-date, especially generator-ox-ui-module. You can update them by running <tt>npm install -g <pkg></tt>.

== Upgrading a Workspace using yo ==

You can generate a new version of your workspace using:

$ yo ox-ui-module

It will prompt for every file that will be overwritten with a different version and ask whether you want to overwrite or not. It is possible to view a diff between both versions. If you have not changed any of the defaults, it is save to say <tt>yes</tt> in all of these cases. If you have changed any of these files, you might still want to overwrite the file and later only commit parts of the new things or just reset to the old version. This can be done easily with your favorite SCM tool, like git or cvs (okay, in this case may be not as easy as promised).

Please pay special attention to <tt>package.json</tt> and <tt>bower.json</tt> files, since those are the files you might have changed before. Those contain meta-information unique to your app, so they will be different from the initially generated ones.

== Manually upgrading single node modules ==

If the approach above is a little to radical for you, because you have customized everything, you might only want to update to the latest shared grunt configuration. Go to the [https://github.com/Open-Xchange-Frontend/shared-grunt-config/releases releases page of shared-grunt-config] and add the name of the latest tag to your apps <tt>package.json</tt>. It should look something like

<code>
"shared-grunt-config": "Open-Xchange-Frontend/shared-grunt-config#v0.5.0"
</code>

where the string after the # is the tag-name that will be checked out. Save the file and run:

$ npm install --no-shrinkwrap

to make sure all your node_modules are up-to-date. If something fails, remove the node_modules directory and try again.

== Testing the most important tasks ==

A quick way to check if everything still runs fine is to run the following grunt tasks

grunt dist
grunt install:dist --prefix backend --htdoc www

After that, check if the directories <tt>backend</tt> and <tt>www</tt> contain files that look a little familiar. If everything seems to look fine, you can remove those directories, again.

During this test, keep an eye on the output and check any warning or error message. If everything looks fine, use <tt>grunt dev</tt> task to test your app in a browser.

== Packaging ==

For packaging it works similar as for the app mentioned above. You can re-run the yo generators

$ yo ox-ui-module:deb-pkg
$ yo ox-ui-module:rpm-pkg

to generate new versions of the files. However, in case of packaging the chance is even higher, that you have changed the generated files. So the best advice would be to to check the differences and cherry pick the changes into your packaging information, i.e. manually add the changes you need to your files.

== Further Reading ==

* In case you want to create a new app for OX App Suite, read [[Appsuite:GettingStarted_7.6.0 | the getting started guide]].

AppSuite:Upgrade app using yo

2016-02-10T13:48:27Z

Frank.paczynski:

<div class="title">Upgrade an app using yo</div>

__TOC__

With the release of App Suite version 7.6.0, we moved towards more easy dependency management for UI modules. We switched to grunt as a task-runner and are using npm and bower to handle dependencies. This article should provide a short guide on what to do in order to upgrade your app to the latest and greatest version of our shared grunt configuration and other development tools.

<div style="clear: both"></div>

== Development Tools ==

First, you might want to check on the versions of the tools which are necessary for UI development.

$ npm outdated -g grunt-cli bower yo generator-ox-ui-module

It's good to have those up-to-date, especially generator-ox-ui-module. You can update them by running <tt>npm install -g <pkg></tt>.

== Upgrading a Workspace using yo ==

You can generate a new version of your workspace using:

$ yo ox-ui-module

It will prompt for every file that will be overwritten with a different version and ask whether you want to overwrite or not. It is possible to view a diff between both versions. If you have not changed any of the defaults, it is save to say <tt>yes</tt> in all of these cases. If you have changed any of these files, you might still want to overwrite the file and later only commit parts of the new things or just reset to the old version. This can be done easily with your favorite SCM tool, like git or cvs (okay, in this case may be not as easy as promised).

Please pay special attention to <tt>package.json</tt> and <tt>bower.json</tt> files, since those are the files you might have changed before. Those contain meta-information unique to your app, so they will be different from the initially generated ones.

== Manually upgrading single node modules ==

If the approach above is a little to radical for you, because you have customized everything, you might only want to update to the latest shared grunt configuration. Go to the [https://github.com/Open-Xchange-Frontend/shared-grunt-config/releases releases page of shared-grunt-config] and add the name of the latest tag to your apps <tt>package.json</tt>. It should look something like

<code>
"shared-grunt-config": "Open-Xchange-Frontend/shared-grunt-config#v0.5.0"
</code>

where the string after the # is the tag-name that will be checked out. Save the file and run:

$ npm install --no-shrinkwrap

to make sure all your node_modules are up-to-date. If something fails, remove the node_modules directory and try again.

== Testing the most important tasks ==

A quick way to check if everything still runs fine is to run the following grunt tasks

grunt dist
grunt install:dist --prefix backend --htdoc www

After that, check if the directories <tt>backend</tt> and <tt>www</tt> contain files that look a little familiar. If everything seems to look fine, you can remove those directories, again.

During this test, keep an eye on the output and check any warning or error message. If everything looks fine, use <tt>grunt dev</tt> task to test your app in a browser.

== Packaging ==

For packaging it works similar as for the app mentioned above. You can re-run the yo generators

$ yo ox-ui-module:deb-pkg
$ yo ox-ui-module:rpm-pkg

to generate new versions of the files. However, in case of packaging the chance is even higher, that you have changed the generated files. So the best advice would be to to check the differences and cherry pick the changes into your packaging information, i.e. manually add the changes you need to your files.

== Further Reading ==

* In case you want to create a new app for OX App Suite, read [[Appsuite:GettingStarted_7.6.0 | the getting started guide]].

AppSuite:ISV Mockups Wireframes

2016-02-10T13:40:38Z

Frank.paczynski:

<div class="title">Create Open-Xchange App Suite Mockups / Wireframes</div>

__TOC__

[[File:Ox-contacts.png|300px|thumb|center]]

[[File:Ox-calendar.png|300px|thumb|center]]

[[File:Ox-core.png|300px|thumb|center]]

=== Why build mockups? ===

Here are some reasons, why YOU should think about using the power of mockups:

* It reproduces the experience of sketching on a whiteboard, but using a computer.
* It dramatically helps to visually any kind of ideas, features of a web application. Mockups are very useful, for example in contracts, proposals, user stories or software change request forms.
* Enhance the visibility of your upcoming features inside a product / customization.
* Iterate easily over ideas + get feedback from potential users and customers until they are ready to get implemented via the development department.

This page contains needed informations, to easily build wireframes/mockups for the Open-Xchange App Suite application.

IMPORTANT NOTE: To build/use the mockups, which get described in this article, you need to install a 3rd party software (Balsamiq) on your local PC/Laptop. Balsamiq can be used in a trial period. Once you decide to constantly use it, you must purchase a license from their [http://balsamiq.com/products/mockups/] website.

=== What´s needed to build beautiful App Suite mockups ? ===

Following Steps are required, to get started to build nice mockups for App Suite.

* You need to install the desktop application called "Balsamiq Desktop App". You can download it from: http://balsamiq.com

* Download the Open-Xchange Balsamiq Assets/Library/Samples from [[File:Ox-assets-balsamiq-7.6.2.zip]]

* Import the downloaded App Suite assets/library into the Balsamiq application and use the included examples:

On MAC OS X / Linux / Windows

# Checkout from GIT or download ZIP file.
# Unzip & navigate to the created directory "assets" . Remember/Copy complete local path to this directory. Example: "/Users/<myuser>/Downloads/ox-assets-balsamiq/assets"
# Open Balsamiq Application and > open menu "Balsamiq Mockups" > Click "About Balsamiq Application"
# "About Dialog" opens with a link to "Open Local Store Folder". Click on that link, which opens your explorer/finder application.
# Now create the required file called "BalsamiqMockups.cfg" inside that directory ("Local Store" folder) with following content. '''IMPORTANT''' You must change the '''assets''' path attribute to '''YOUR path''' structure on YOUR local system.
<config>
<fontFace>Helvetica Neue</fontFace>
<rememberWindowSize>true</rememberWindowSize>
<useCookies>true</useCookies>
<'''assetsPath'''>/Users/<myuser>/Downloads/ox-assets-balsamiq/assets</'''assetsPath'''>
</config>
# Now use your explorer/finder/shell and copy all ".bmml" files from within the "visuals/assets" directory to your work/dev directory.
# Close the Balsamiq application and reopen it. You now should see a new tab called "Account Assets" in the UI components library. All OX related components are prefixed with "ox-" for easy find as you type usage.
# Go to your work/dev directory which contains the copied ".bmml" files. Click on one of the .bmml files. You are DONE!

* Let the fun begin! Mockup as your like and save the newly created file to your work/dev directory!

{{#ev:youtube|RstDlq9X-jA}}

==== General basics of Balsamiq ====

* Working with Symbols - http://support.balsamiq.com/customer/portal/articles/110439

* How to Use an Existing File as a Symbol in Mockups - http://support.balsamiq.com/customer/portal/articles/110439

* Working with Text - http://support.balsamiq.com/customer/portal/articles/110121

* Tutorials - http://support.balsamiq.com/customer/portal/topics/49503-tutorials/articles

==== Common pitfalls when using Balsamiq ====
* Any files stored in an subdirectory of your assets folder don't show up in the 'account assets' tab within Balsamic cause currently subdirectories are ignored.
* In case your assets folder only contains images the 'account assets' will not show up

AppSuite:Mobile

2016-02-10T13:34:20Z

Frank.paczynski:

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

The device class <tt>'smartphone'</tt> is used to determine a mobile device and is detected by several criteria. For more details, see this [[AppSuite:UI_smartphone_device_classification | article about smartphone classification. ]]

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

To setup remote debugging on windows, mac and linux you can follow the instructions from the chrome developer tools website.

[https://developer.chrome.com/devtools/docs/remote-debugging Remote Debugging on Android with Chrome]

If this is not working or not applicable for you, use the following description:

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

AppSuite:Media player

2016-02-10T13:31:42Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Mediaplayer</div>
__TOC__
==Browser and device support==
App Suite uses ''mediaelement.js'' [http://mediaelementjs.com] as media player. The player uses native HTML5 audio and video elements plus it falls back to flash or silverlight if they are not available.

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

==Figure out version of mediaelement.js==
We always try to integrate the latest version of mediaelement.js in order to get latest fixes. To figure out which version is integrated in your release, please run the following code:
<pre class="language-javascript">
// logs "2.11.0" in current development branch (April 2013)
require(['apps/mediaelement/mediaelement-and-player.js'], function () {
console.log(mejs.version);
});
</pre>

==How to enable/disable the media player==
In order to configure this server-side, just create a new property file or append to existing '''appsuite.properties''' (mind the '''double-slash'''; this in not a typo!):
<pre class="language-config">
io.ox/files//audioEnabled = true|false
io.ox/files//videoEnabled = true|false
</pre>

AppSuite:Date and time

2016-02-10T12:51:52Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Date and Time</div>

The handling of date and time is a complicated mess of historical conventions, which are still changed from time to time by governments around the world. To keep this away from day-to-day activities of developers, the OX App Suite platform provides the module date, which performs conversion between different time zones, formatting and parsing of date and time values.

__TOC__

The examples in this article use some global variables. For the examples to work the way they are intended, you will first need to load the [[AppSuite:I18n | gettext module]] and the date module and store them in variables <tt>gettext</tt> and <tt>date</tt>.

<pre class="language-javascript">
var gettext;
var date;
require(['gettext!example', 'io.ox/core/date']).done(function (gt, d) {
gettext = gt;
date = d;
});
</pre>

In real code, you should not use global variables. Instead, you would use the <tt>gt</tt> and <tt>d</tt> parameters directly, without storing them in another variable.

== Time Zones ==

The built-in JavaScript class Date supports calculations using UTC and the operating system's local time zone. Unfortunately, this is not enough. Examples include using a time zone different from the time zone of the client system, or displaying times in multiple time zones at once.

The class Local is almost a drop-in replacement for Date, with the main difference being that it operates in the default time zone of the OX App Suite user, even if it is different from the time zone of the browser's operating system. The following code displays the current date and time. It will show a different time when called after changing the user's time zone.

<pre class="language-javascript">
alert(new date.Local());
</pre>

To work with other time zones, the function <tt>getTimeZone()</tt> can be used to create replacement classes similar to Local, which are all descendants of the private class LocalDate (for which all methods are documented below). Since the time zone definitions are loaded on-demand, the function returns a jQuery promise, which is resolved to the class constructor once the time zone definition is loaded. This class can then be used to e.g. convert between time zones.

<pre class="language-javascript">
date.getTimeZone('America/New_York').done(function (NewYork) {
alert(gettext('New York celebrated New Year\'s at %1$s',
new date.Local(new NewYork(2012, 0, 1))));
});
</pre>

The function getTimeZone() is memoized for performance reasons, i.e. multiple calls with the same argument will return the same promise and will therefore resolve to the same class object.

== Formatting ==

The default <tt>LocalDate.prototype.toString()</tt> method displays the full date and time, including the day of week and the time zone. To allow better control of the resulting string, the method <tt>LocalDate.prototype.format()</tt> accepts a set of format flags. The flags determine, which fields should be included in the output. Currently, there are four flags:

<pre class="language-javascript">
var d = new date.Local();
alert(d.format(date.DATE));
alert(d.format(date.TIME));
alert(d.format(date.DAYOFWEEK));
alert(d.format(date.TIMEZONE));
</pre>

Multiple flags can be combined by adding them, or by using one of the predefined combination constants. Not all possible combinations produce unique results. When DAYOFWEEK is specified together with any other fields, DATE is automatically included in the output. Similarly, TIMEZONE implies TIME when used with other fields.

<pre class="language-javascript">
var d = new date.Local();
assert(d.format(date.DAYOFWEEK + date.TIMEZONE) === d.format(date.FULL_DATE);
</pre>

The format flags select one of several predefined format strings, which is stored in the current locale settings. This frees both the developers and the translators from having to remember arcane letter combinations.

For the case that even finer control of the generated output is required, LocalDate.prototype.format() accepts a format string directly. The syntax of the format strings is a subset of CLDR date format patterns. Format specifiers which are not used in the Gregorian calendar will be implemented on-demand.

<pre class="language-javascript">
alert(new date.Local().format('EEEE'));
</pre>

In general, if format strings are required, this indicates that the current date API should be extended. Feedback is always welcome.

One situation where direct access to format strings is useful, is the manipulation of the localized format strings, e.g. to decorate individual fields in a displayed date with HTML markup. To achieve this, the localized format string is retrieved with getFormat(), and parts of it passed individually to LocalDate.prototype.format().

<pre class="language-javascript">
// Get the original format string.
var fmt = date.getFormat(date.FULL_DATE);

// Regular expression to parse the format string.
// . . ( time zone )|quote|'quoted text'|rest
var re = /(v+|V+|z+|Z+)|(?:''|'(?:[^']|'')*'|[^vVzZ'])+/g;

// Appends a formatted date to a jQuery node and returns
// the time zone as a separate node.
function decorateTimeZone(d, parent) {
var span;
fmt.replace(re, function (match, tz) {
if (tz) { // found the time zone field
// Wrap the formatted time zone in a <span> element.
span = $('<span>').text(d.format(match));
parent.append(result);
} else {
// Append all other formatted text as plain text nodes.
parent.append($.txt(d.format(match)));
}
});
// Return the wrapped field for further customization.
return span;
}
</pre>

''Does anybody want this use case as an API function?''

== Intervals ==

In addition to formatting individual dates, LocalDate instances can format intervals. The difference to simply inserting two dates into a translated string is that short intervals may have a compacter representation, e.g. 'Jan 1–10, 2012' instead of 'Jan 1, 2012 – Jan 10, 2012'.

<pre class="language-javascript">
var start = new date.Local(), end = new date.Local(start);
end.add(date.DAY);
alert(start.formatInterval(end, date.DATE));
</pre>

The methods LocalDate.prototype.formatInterval() and LocalDate.prototype.getIntervalFormat() are used like LocalDate.prototype.format() and getFormat(), with two differences. First, the interval functions accept the end of the interval as first parameter before the format flags. And second, since the format string depends on the actual interval, LocalDate.prototype.getIntervalFormat() is a member function and requires the same end value as used later for LocalDate.prototype.formatInterval().

== Parsing ==

Parsing is the reverse of formatting, except that ideally, users should be able to enter almost anything, as long as it is not ambiguous. The practice looks a bit more restricted. The LocalDate.parse() function takes a format parameter like the formatting functions, and expects the parsed string to match it very closely.

<pre class="language-javascript">
var input = prompt(gettext('Please enter a date'), '');
var d = date.Local.parse(input, date.DATE);
alert(gettext('I understood %1$s', d);
</pre>

If there is demand, we can implement some heuristics. There are a lot of abstract algorithm descriptions in the standards, which describe how to parse almost anything while using the format string only as disambiguation help.

== Manipulation of LocalDate objects ==

Since the LocalDate class is designed as a drop-in for the Date class, its instances support getter and setter methods for all fields of a date. They can be used to modify an existing LocalDate object, e. g. to round a date to the nearest day or hour.

<pre class="language-javascript">
var start = new date.Local(), end = new date.Local(start);
start.setHours(0, 0, 0, 0);
end.setHours(24, 0, 0, 0);
alert(gettext('Today is %1$s', start.formatInterval(end)));
</pre>

One manipulation, which is often needed in calendars, is iteration over time. This operation seems simple, at least for iteration steps with a constant duration like hours, days or weeks. One just needs to add the step duration to the timestamp. While there is a method to do exactly this, LocalDate.prototype.addUTC(), you will encounter problems as soon as the iteration transcends a daylight savings switch. First, days and weeks are not actually constant. And second, sometimes the iteration might need to follow the displayed 'wall clock' time instead of the physical time. For these cases, the method LocalDate.prototype.add() increments the local time instead of the UTC time. Both methods accept an increment value in milliseconds, which can also be negative. There are predefined constants for the most common (almost-)fixed-duration periods.

<pre class="language-javascript">
var d = new date.Local(2012, 2);
for (; d.getMonth() < 3; d.add(date.DAY)) {
// Display a day in a month view.
}
</pre>

Iteration with larger intervals like months and years has the additional difficulty, that a single numeric parameter like 30 * date.DAY cannot be interpreted as a month, because it might be just really 30 days. To solve this, there are separate methods for months and years: LocalDate.prototype.addMonths() and LocalDate.prototype.addYears(). They accept the number of months, respective years as parameter.

<pre class="language-javascript">
var d = new date.Local(2012, 0);
for (; g.getYear() < 2013; d.addMonths(1)) {
// Display a month in a year view.
}
</pre>

Finally, most calendars default to displaying the current date, and therefore need to figure out the iteration range based on an arbitrary point inside that range. In most cases, the start can be computed by simply calling the appropriate setters with all zeros as parameters to find the start of the range, and adding the range duration to find the end. One exception is the week. There is no setter for the day of the week. Instead, the method LocalDate.prototype.setStartOfWeek() can be used to find the start of a week.

<pre class="language-javascript">
// Find the start and the end of the current week
var d = new date.Local().setStartOfWeek();
var end = new date.Local(start).add(date.WEEK);
// Iterate over the week
for (; d < end; d.add(date.DAY)) {
// Display a day in a week view.
}
</pre>

In addition to explicit method calls, the JavaScript standard method LocalDate.prototype.valueOf() allows native comparison, addition and subtraction operators to work on LocalDate objects. The result of LocalDate.prototype.valueOf(), and therefore of addition and subtraction, is a timestamp, which can be passed to the LocalDate constructor to get a LocalDate object again.

<pre class="language-javascript">
var start = date.Local.parse(prompt(gettext('Start date'), ''));
var end = date.Local.parse(prompt(gettext('End date'), ''));
if (end < start) alert(gettext('Invalid date range!'));
</pre>

== Differences between LocalDate and Date ==

The LocalDate classes duplicate most of the Date API with a few exceptions:

* The constructor can not be called as a function. The Date constructor does in this case nothing useful anyway.
* The constructor always uses full years, it does not add 1900 for years 0 to 99.
* Date.UTC() should not be necessary, but since it returns a numeric timestamp and has nothing to do with time zones, it can still be used directly.
* Except for LocalDate.prototype.toString(), all to*String() methods are replaced by LocalDate.prototype.format().
* There are no UTC variants of getters and setters. They should not be necessary. But just in case, you can still use a LocalDate class for the time zone 'UTC' instead.
* The getter and setter for the year are called getYear and setYear instead of getFullYear and setFullYear since we have no legacy code with Y2K issues.
* Setters return the modified object instead of the timestamp. This is useful for chaining of method calls.
* Date.prototype.getTimeZoneOffset() should not be necessary, since hiding these details is the whole point of the date module. If still necessary, LocalDate.getTTInfo() can be used instead.

== API Reference ==

This section provides a short reference of the date API.

=== Locale ===

A locale describes the localization settings which usually depend not only on the language, but also on the region and optionally even on the personal preferences of the user. The locale object is loaded at startup and provides various settings and translations.

Various arrays containing translations can be used directly without any other date function.

locale.dayPeriods
A map from an identifier of a day period to the corresponding translation. The members am and pm are used in the 12h time format, but other members may be useful for greetings. Is anyone interested in a function which returns the correct greeting period for a given time? If not, maybe remove everything except AM and PM?
locale.days
An array with translated full names of days of the week, starting with Sunday. CLDR context: "format", CLDR width: "wide".
locale.daysShort
An array with translated abbreviated names of days of the week, starting with Sunday. CLDR context: "format", CLDR width: "abbreviated".
locale.daysStandalone
An array with translated standalone names of days of the week, starting with Sunday. CLDR context: "standalone", CLDR width: "abbreviated".
locale.eras
An array with translated abbreviations for the two eras of the Gregorian calendar: BC and AD (in that order).
locale.months
An array with translated full names of months. CLDR context: "format", CLDR width: "wide".
locale.monthsShort
An array with translated abbreviated names of months. CLDR context: "format", CLDR width: "abbreviated".
Diverse week-based calculations need to know on which day the week starts and how the first week of the year is defined.

locale.daysInFirstWeek
The lowest number of days of a week which must be in the new year for that week to be considered week number 1. Common values are
* 1 if the week of January 1st is week number 1,
* 4 if the first week which has most of its days in the new year is week number 1.
* 7 if the first week which starts in the new year is week number 1.
locale.weekStart
First day of the week. Common values are
* 0 for Sunday,
* 1 for Monday.
Deprecated and internal fields should not be used since they can change or disappear entirely without notice. They are still documented here for completeness.

locale.date
Deprecated, use DATE instead.
locale.dateTime
Deprecated, use DATE_TIME instead.
locale.dateTimeFormat
The default format used to combine a time (%1$s) and a date (%2$s). Not used yet, will probably disappear.
locale.formats
A map from various canonical sets of format fields to the corresponding localized format strings. Used mainly by getFormat(). Maybe remove it from the public interface after loading, since it's internal?
locale.h12
A boolean indicating whether the 12h format is used. WANTED: a better name.
locale.intervals
A map from various canonical sets of format fields to the corresponding formatting rules. A formatting rule is a map from the largest field, which is different between the start and end of the interval, to the corresponding localized formatting string. The field is specified as a single lower case letter. The formatting string is split at the first repeating field. The first part is formatted using the start of the interval, the second part is formatted using the end of the interval. Used mainly by LocalDate.prototype.getIntervalFormat(). Maybe remove it from the public interface after loading, since it's internal?
locale.intervals.fallback
The default format string to combine the start (%1$s) and end (%2$s) of an interval when none of the other members of locale.intervals apply. Maybe remove it from the public interface after loading, since it's internal?
locale.time
Deprecated, use TIME instead.
getTimeZone

The main entry points of the date API are the class Local which replaces Date for use with the user's default time zone and a function to generate similar classes for arbitrary time zones.

getTimeZone(name)
Creates a LocalDate class which operates in the specified time zone. Multiple calls with the same name will return the same object.
name String - The name of the requested time zone. It must be one of the values returned by api/config/availableTimeZones.
Returns Promise - A promise which resolves to a LocalDate class which uses the requested time zone.
Local
A convenience LocalDate class which uses the user's current time zone.

=== LocalDate ===

The core of the date API is the abstract class LocalDate which is the superclass of time zone specific classes. The class itself is not publically available, only its subclasses can be created by calling getTimeZone(). The subclasses and their instances are referred to as LocalDate classes and LocalDate objects.

The constructor mimics the behavior of the Date class, but it can't be called as a function.

<pre class="language-javascript">
new LocalDate()
new LocalDate(timestamp)
new LocalDate(year, month, date, hours, minutes, seconds, ms)
</pre>

The constructor accepts the same parameters as the Date constructor.
The entire functionality of the class is based on a few low level functions. They should not be necessary outside the date module itself, assuming the API is complete. If you find you need these functions, please let's extend the high level APIs instead.

LocalDate.getTTInfo(t)
Returns the GMT offset, daylight savings and the abbreviation of the time zone which are in effect at the specified time.
t Timestamp - The timestamp.
Returns { gmtoff, isdst, abbr } - An object with the GMT offset in milliseconds, whether daylight savings are in effect (0 or 1, not a real boolean) and the abbreviation like 'CET' (!isdst) or 'CEST' (!!isdst).
LocalDate.getTTInfoLocal(t)
* Returns the GMT offset, daylight savings and the abbreviation of the time zone which are in effect at the specified local time. If the local time is ambiguous or invalid, the same fallbacks as for LocalDate.utc() are used. (It is actually implemented as a wrapper for this function.)
* t Number - The local time.
* Returns { gmtoff, isdst, abbr } - An object with the GMT offset in milliseconds, whether daylight savings are in effect (0 or 1, not a real boolean) and the abbreviation like 'CET' (!isdst) or 'CEST' (!!isdst).

LocalDate.localTime(t)
* Converts a UTC timestamp to local time.
* t Timestamp - The UTC timestamp to convert.
* Returns Number - A local time which is used in computations of date and time components.

LocalDate.utc(t)
* Converts local time to a UTC timestamp. If the local time is ambiguous because of a DST switch, the local time is interpreted as before the switch. E.g. 02:30 at the end of DST is interpreted as DST. If the local time is invalid because of a DST switch, the local time is interpreted as if the switch already occurred. E.g. 02:30 at the start of DST returns the same timestamp as 01:30 before the switch.
* t Number - The local time to convert.
* Returns Timestamp - The corresponsing UTC timestamp.
Metadata about a time zone is stored directly on the LocalDate object.

LocalDate.id
* Original name used to retrieve this time zone.

LocalDate.displayName
* A human-readable name of this time zone as provided by the config module under "availableTimeZones".
* Parsing of date and time strings as entered by a user is done using format flags from Constants. The current implementation expects the string to match the corresponding localized format string pretty closely. Any difficulties with parsing common entered dates and times should be taken as an opportunity to extend the parsing heuristics.

LocalDate.parse(string, format)
* Parses a string using either the specified format string or localized version of one of predefined format strings selected by format flags.
* string String - The string to parse.
* format String or Number - Either a format string with the syntax of CLDR date format patterns, or one of the format flag constants. In the second case, the actual format string is localized for the current user's locale according to locale.formats.
* Returns LocalDate or null - A new LocalDate object which represents the parsed date and time or null if the string could not be parsed.
* Methods of LocalDate instances can be grouped into several categories. The first are the setters and getters for individual fields from Date. Since each LocalDate class has its own time zone, There are no UTC variants of each getter and setter. They all work with local time.

<pre class="language-javascript">
LocalDate.prototype.getYear()
LocalDate.prototype.getMonth()
LocalDate.prototype.getDate()
LocalDate.prototype.getHours()
LocalDate.prototype.getMinutes()
LocalDate.prototype.getSeconds()
LocalDate.prototype.getMilliseconds()
</pre>
* Return the corresponding field of the local date or time.
* Returns Number - The requested field, as a number.

<pre class="language-javascript">
LocalDate.prototype.setYear(year, month, date)
LocalDate.prototype.setMonth(month, date)
LocalDate.prototype.setDate(date)
LocalDate.prototype.setHours(hour, min, sec, ms)
LocalDate.prototype.setMinutes(min, sec, ms)
LocalDate.prototype.setSeconds(sec, ms)
LocalDate.prototype.setMilliseconds(ms)
</pre>
* Set the specified date or time fields. Any unspecified fields retain their current value. Values outside of the specified ranges will result in overflow to the neighboring periods and can therefore be used for date arithmetic.
** year Number - The year.
** month Number - The month. Values range from 0 for January to 11 for December.
** date Number - The date. Values range from 1 to 31.
** hour Number - The hours. Values range from 0 to 23.
** min Number - The minutes. Values range from 0 to 59.
** sec Number - The seconds. Values range from 0 to 59.
** ms Number - The milliseconds. Values range from 0 to 999.

LocalDate.prototype.getDay()
* Returns Number - The day of the week. Values range from 0 for Sunday to 6 for Saturday.

LocalDate.prototype.getTimeZone()
* This method is not present in Date. It returns the abbreviation of the specific time zone. The abbreviation indicate the GMT offset and is therefore different between daylight savings time and standard time.
* Returns String - The abbreviation of the specific time zone.
* Other getters and setters work with the entire timestamp and not just individual fields.

LocalDate.prototype.getDays()
* Returns the day number of this object. This may be useful to find the start of the same day (by multiplying the result with DAY).
* Returns Number - The number of days since 1970-01-01 in this object's time zone.

LocalDate.prototype.getTime()
* Returns Timestamp - The UTC timestamp of this object.

LocalDate.prototype.setTime(time)
* Sets the UTC timestamp to a new value.
* time Timestamp - The new UTC timestamp of this object.
* While setters can be used to perform date arithmetic, LocalDate provides convenience functions for the most frequent cases of adding and subtracting a time period and finding the start of a week.

LocalDate.prototype.add(time)
* Adds or subtracts a time period in local time. The results may be invalid if the end result ends up in the middle of a daylight savings switch.
* time Number - The time period to add, in milliseconds. Use negative values to subtract. See also Constants.
* Returns this - This object for chaining.

LocalDate.prototype.addUTC(time)
* Adds or subtracts a physical time period, i.e. simply increments the timestamp.
time Number - The time period to add, in milliseconds. Use negative values to subtract. See also Constants.
* Returns this - This object for chaining.

LocalDate.prototype.addMonths(months)
* Adds or subtracts a number of months in local time. The results may be invalid if the end result ends up in the middle of a daylight savings switch.
months Number - The number of months to add. Use negative values to subtract.
Returns this - This object for chaining.

LocalDate.prototype.addYears(years)
* Adds or subtracts a number of years in local time. The results may be invalid if the end result ends up in the middle of a daylight savings switch.
years Number - The number of years to add. Use negative values to subtract.
* Returns this - This object for chaining.

LocalDate.prototype.setStartOfWeek()
* Sets the date to the start of the same week as determined by locale.weekStart. The time is reset to midnight.
* Returns this - This object for chaining.
* Formatting functions implement the conversion of dates and intervals into localized strings which are suitable for direct presentation to the user.

LocalDate.prototype.format(format)
* Formats the date according to the specified format flags or format string.
* format String or Number - Either a format string with the syntax of CLDR date format patterns, or one of the format flag constants. In the second case, the actual format string is localized for the current user's locale according to locale.formats. The default value is DATE_TIME.
* Returns String - This object formatted according to the specified format.

LocalDate.prototype.getIntervalFormat(end, format)
* Returns a format string for a time interval with this object as the start and another LocalDate object as the end.
* end LocalDate - The end of the interval.
* format String or Number - Either a format string with the syntax of CLDR date format patterns, or one of the format flag constants. In the second case, the actual format string is localized for the current user's locale according to locale.intervals and locale.formats. The default value is DATE_TIME.
* Returns String - The format string for the interval accorging to the specified format.

LocalDate.prototype.formatInterval(end, format)
* Formats an interval with this object as the start and another LocalDate object as the end.
end LocalDate - The end of the interval.
format String or Number - Either a format string with the syntax of CLDR date format patterns, or one of the format flag constants. In the second case, the actual format string is localized for the current user's locale according to locale.intervals and locale.formats. The default value is DATE_TIME.
* Returns String - The interval formatted accorging to the specified format.
* Finally, the JavaScript standard conversion functions allow easy debugging and arithmetic on timestamps.

LocalDate.prototype.toString()
* Converts this object to a string using this.format(FULL_DATE).
* Returns String - The string representation of this object.

LocalDate.prototype.valueOf()
* Converts this object to a primitive value by returning the UTC timestamp. This can be used for arithmetic directly on LocalDate objects and as the single parameter to new LocalDate().
* Returns Timestamp - The UTC timestamp of this object.

=== Constants ===

All date classes operate on timestamps expressed as milliseconds since the UNIX epoch, 1970-01-01 00:00 UTC. The date module defines constants for common time intervals with a constant duration.

SECOND
Number of milliseconds in a second.
MINUTE
Number of milliseconds in a minute.
HOUR
Number of milliseconds in an hour.
DAY
Number of milliseconds in a day.
WEEK
Number of milliseconds in a week.

Format flags for parsing and formatting functions are defined as constants. Multiple flags can be combined via addition or bitwise ORing.

<pre class="language-javascript">
DAYOFWEEK
Day of the week
DATE
Date
TIME
Time
TIMEZONE
Timezone
</pre>
Valid format flag combinations have dedicated constants. In a combination, DAYOFWEEK implies DATE and TIMEZONE implies TIME.

<pre class="language-javascript">
DAYOFWEEK_DATE
DAYOFWEEK + DATE
DATE_TIME
DATE + TIME
DAYOFWEEK_DATE_TIME
DAYOFWEEK + DATE + TIME
TIME_TIMEZONE
TIME + TIMEZONE
DATE_TIME_TIMEZONE
DATE + TIME + TIMEZONE
FULL_DATE
DAYOFWEEK + DATE + TIME + TIMEZONE
Miscellaneous
</pre>
See [[#Formatting|Formatting]] for usage of this function.

getFormat(format)
* Returns the localized format string for the specified format flags.
format String or Number - Either a format string with the syntax of CLDR date format patterns, or one of the format flag constants. In the second case, the actual format string is localized for the current user's locale according to locale.formats. The default value is DATE_TIME.
* Returns String - The localized format string which corresponds to the specified format flags. If format is a string, that string is returned unmodified.

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

AppSuite:Browserdetection

2016-02-10T12:48:55Z

Frank.paczynski:

== Browser detection outside AppSuite ==
[[File:loginpage.png|thumb|250px|This warning is not shown to a user if you use the form-login]]

AppSuite detects the client browser and collects some information about the current device the visitor is using. This information is used to serve the appropriate UI and enable/disable certain features for the visitor's device.

The browser detection is done by a standalone, dependency free lib that can be included via script-tag to other sites. The original AppSuite login page performs this browser detection. But if you use a form-login and jump directly into AppSuite, the user will miss the warning where AppSuite statesthat an unsupported browser is used.

To show the same warning to a user without using the original AppSuite login page, you should include the browser detection lib in your own login page. That way you can show a warning to the user if they do not use a supported browser.

=== Including the browser.js lib ===

You can easily include the browser detection via script-tag in your own login page. It's a small, dependency free piece of Javascript code which adds a function to the global scope called <pre>isBrowserSupported()</pre>

The lib is located in the AppSuite UI under <tt>http://somedomain.com/appsuite/src/browser.js</tt>. Add this script tag to your page head <pre><script src="http://somedomain.com/appsuite/src/browser.js" type="text/javascript" charset="UTF-8"></script></pre>

In your page <tt>onLoad</tt> you can then call the global function <tt>isBrowserSupported</tt> which returns a boolean. If <tt>false</tt> is returned by the function you should show a warning to the user that his browser is not supported.

[[Category:Custom development]]
[[Category:Administrator]]
[[Category:Developer]]

[[Category:UI]]

[[Category:AppSuite]]

AppSuite:A11y

2016-02-10T12:48:06Z

Frank.paczynski:

Accessibility is specific to the application you are developing. Here are resources that the Open-Xchange developers use for this topic:

*

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

AppSuite:Modifying forms by using extension points

2016-02-10T12:46:47Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points:<br>Modifying forms</div>

'''Abstract'''

''This articles covers how to apply different changes to the contact form via modifying its extensionpoints and extensions.''

__TOC__
==Show available extension points==

The edit form of the contacts app is constructed by a set of extension points. Each extension point controls a single aspect of the form. To apply modifications, the id of the point and the extension is needed. For a quick overview of the available points and extensions you can use the browser console:

<pre class="language-javascript">
// show all available extension points (across all apps)
require('io.ox/core/extensions').keys();
</pre>

<pre class="language-javascript">
// you can filter down the list by using regular expression
_(require('io.ox/core/extensions').keys()).filter(function (point) {
if (/io.ox\/contacts\/edit/.test(point)) {
return point;
}
});
</pre>

<pre class="language-javascript">
// show all available extensions of a known extension point
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal').all();
</pre>

==Modify extension points==

As described in [[ AppSuite:Extending_the_UI_(Hands-on_introduction) | Hands-on_introduction]] extension points can be modified in multiple aspects:

<pre class="language-javascript">
// disable the display_name field
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal').disable('display_name');

// reenable the display_name field
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal').enable('display_name');
</pre>

<pre class="language-javascript">
// replace the display_name field by "Hallo World!"
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal')
.replace({
id: "display_name",
draw: function () {
this.append(
$("<div>").addClass("title").text("Hello World!")
);
}
});
</pre>

<pre class="language-javascript">
// modify the index of the display_name field to bring it on top
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal')
.replace({
id:"display_name",
index: 50
});
</pre>

<pre class="language-javascript">
// modify the hidden status to hide the display_name field via get() as alternative way
require('io.ox/core/extensions').point('io.ox/contacts/edit/personal')
.get('display_name', function (extension) {
extension.hidden = true;
});
</pre>

==Extending the form validation via extension points==

In addition to the default validation, another validation step can be implemented by extending the proper extension point:

<pre class="language-javascript">
// extend the validation of the display_name field
require('io.ox/core/extensions')
.point('io.ox/contacts/model/validation/display_name')
.extend({
id: 'check_for_klaus',
validate: function (value) {
if (value !== 'Klaus') {
return 'The display name has to be Klaus';
}
}
});
</pre>

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:I18n

2016-02-10T12:39:22Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Internationalization (i18n)</div>

__TOC__

Providing software for users in the whole world means providing it in multiple languages. This consists of two steps:

* ''Internationalization (i18n)'' - Making the software international, i. e. preparing it to be adapted to different languages and locations.
* ''Localization (L10n)'' - Adapting the software to a particular language and/or location.
The Open-Xchange platform offers several facilities to simplify both parts. The L10n part is mostly a concern for translators. Open-Xchange facilities for that consist mainly of using a well-established format for translations: [http://www.gnu.org/s/gettext/ GNU Gettext] Portable Object (PO) files. This allows translators to use existing dedicated translation tools or a simple UTF-8-capable text editor.

The i18n part is what software developers will be mostly dealing with and is what the rest of this document describes.

==Translation==

The main part of i18n is the translation of various text strings which are presented to the user. For this purpose, the Open-Xchange platform provides the RequireJS plugin <tt>'gettext'</tt>. Individual translation files are specified as a module dependency of the form <tt>'gettext!module_name'</tt>. The resulting module API is a function which can be called to translate a string using the specified translation files:

<pre class="language-javascript">
define('com.example/example', ['gettext!com.example/example'],
function (gt) {
'use strict';
alert(gt('Hello, world!'));
});
</pre>

A file named ox.pot is created by the <tt>ox.pot</tt> (< 7.6.0) or <tt>create_pot</tt> (>= 7.6.0) tasks of the build system. So for versions < 7.6.0 you will need to run:

$ build-appsuite ox.pot

to create the file in the apps root directory.

Working with a version starting from 7.6.0, the command:

$ grunt create_pot

will generate this file within the <tt>i18n/</tt> directory. It will contain an entry for every call to one of <tt>gettext</tt> functions:

<pre class="language-gettext">
#: apps/com.example/example.js:4
msgid "Hello, world!"
msgstr ""
</pre>

This file can be sent to the translators and during the translation process, one PO file for each language will be created. The PO files in the directory <tt>i18n</tt> shoud contain the translated entry:

<pre class="language-gettext">
#: apps/com.example/example.js:4
msgid "Hello, world!"
msgstr "Hallo, Welt!"
</pre>

During the next build, the entries are copied from the central PO files into individual translation files. In our example, this would be <tt>apps/com.example/example.de_DE.js</tt>. Because of the added language ID, translation files can usually have the same name as the corresponding main module. Multiple related modules should use the same translation file to avoid the overhead of too many small translation files.

Most modules will require more complex translations than can be provided by a simple string lookup. To handle some of these cases, the <tt>gettext</tt> module provides traditional methods in addition to being a callable function. Other cases are handled by the build system.

==Composite Phrases==

In most cases, the translated texts will not be static, but contain dynamic values as parts of a sentence. The straight-forward approach of translating parts of the sentence individually and then using string concatenation to compose the final text is a BAD idea. Different languages have different sentence structures, and if there are multiple dynamic values, their order might need to be reversed in some languages, and not reversed in others.

The solution is to translate entire sentences and then to use the <tt>gettext</tt> function to insert dynamic values:

<pre class="language-javascript">
alert(
//#. %1$s is the given name
//#. %2$s is the family name
//#, c-format
gt('Welcome, %1$s %2$s!', firstName, lastName));
</pre>

Results in:

<pre class="language-gettext">
#. %1$s is the given name
#. %2$s is the family name
#, c-format
msgid "Welcome, %1$s, %2$s"
msgstr ""
</pre>

As shown in the example, it is possible to add comments for translators by starting a comment with <tt>"#."</tt>. Such comments must be placed immediately before the name of the variable which refers to the <tt>gettext</tt> module (in this case <tt>gt</tt>). They can be separated by arbitrary whitespace and newlines, but not other tokens. All such <tt>gettext</tt> calls should have comments explaining every format specifier.

Comments starting with <tt>"#,"</tt> are meant for <tt>gettext</tt> tools, which in the case of <tt>"#, c-format"</tt>, can ensure that the translator did not leave out or mistype any of the format specifiers.

For the cases when the format string must be translated by one of the functions described below, there is a dedicated format function <tt>gettext.format</tt> which, except for debugging, is an alias for <tt>_.printf</tt>.

==Debugging==

One of the most common i18n errors is forgetting to use a <tt>gettext</tt> function. To catch this kind of error, the UI can be started with the hash parameter <tt>"#debug-i18n=1"</tt>. (Reloading of the browser tab is usually required for the setting to take effect.)

In this mode, every translated string is marked with invisible Unicode characters, and any DOM text without those characters gets reported on the console. The <tt>gettext.format</tt> function then also checks that every parameter is translated. This is the reason why <tt>_.printf</tt> should not be used for user-visible strings directly.

Unfortunately, this method will also report any string which does not actually require translation. Examples of such strings include user data, numbers, strings already translated by the server, etc. To avoid filling the console with such false positives, every such string must be marked by passing it through the function <tt>gettext.noI18n</tt>:

<pre class="language-javascript">
alert(
//#. %1$s is the given name
//#. %2$s is the family name
//#, c-format
gt('Welcome, %1$s %2$s!', gt.noI18n(firstName), gt.noI18n(lastName)));
</pre>

This results in the strings being marked as 'translated' without actually changing their visible contents. When not debugging, <tt>gettext.noI18n</tt> simply returns its first parameter.

==Advanced gettext Functions==

Besides <tt>gettext.format</tt> and <tt>gettext.noI18n</tt> there are several other functions which are required to cover all typical translation scenarios.

===Contexts===

Sometimes, the same English word or phrase has multiple meanings and must be translated differently depending on context. To be able to tell the individual translations apart, the method <tt>gettext.pgettext</tt> ('p' stands for 'particular') should be used instead of calling <tt>gettext</tt> directly. It takes the context as the first parameter and the text to translate as the second parameter:

<pre class="language-javascript">
alert(gt.pgettext('description', 'Title'));
alert(gt.pgettext('salutation', 'Title'));
</pre>

Results in:

<pre class="language-gettext">
msctxt "description"
msgid "Title"
msgstr "Beschreibung"

msctxt "salutation"
msgid "Title"
msgstr "Anrede"
</pre>

===Plural forms===

In the case of numbers, the rules to select the proper plural form can be very complex. With the exception of languages with no separate plural forms, English is the second simplest language in this respect, having only two plural forms: singular and plural. Other languages can have up to four forms, and theoretically even more. The functions <tt>gettext.ngettext</tt> and <tt>gettext.npgettext</tt> (for a combination of plural forms with contexts) can select the proper plural form by using a piece of executable code embedded in the header of a PO file:

<pre class="language-javascript">
alert(gt.format(
//#. %1$d is the number of mails
//#, c-format
gt.ngettext('You have %1$d mail', 'You have %1$d mails', n),
gt.noI18n(n)));
</pre>

The function <tt>gettext.ngettext</tt> accepts three parameters: the English singular and plural forms and the number which determines the chosen plural form. The function <tt>gettext.npgettext</tt> adds a context parameter before the others, similar to <tt>gettext.pgettext</tt>. They are usually used in combination with <tt>gettext.format</tt> to insert the actual number into the translated string.

The above example results in the following entry:

<pre class="language-gettext">
#. %1$d is the number of mails
#, c-format
msgid "You have %1$d mail"
msgid_plural "You have %1$d mails"
msgstr[0] ""
msgstr[1] ""
</pre>

The number of <tt>msgstr[N]</tt> lines is determined by the number of plural forms in each language. This number is specified in the header of each PO file, together with the code to compute the index of the correct plural form the supplied number.

==Custom Translations==
App Suite has support for custom translations. ''gettext'' provides a function ''addTranslation(dictionary, key, value)'' that allows adding custom translation to a global dictionary ("*") as well as replacing translations in existing dictionaries. In order to use this, you have to create a plugin for the "core" namespace. With release 7.8.0, there is a special namespace for exactly this use-case. It is now possible to define plugins to be loaded for the "i18n" namespace, which is loaded right before gettext is being enabled and after that the core plugins will be loaded.

<pre class="language-javascript">
require(['io.ox/core/gettext'], function (gt) {
gt.addTranslation('*', 'Existing translation', 'My custom translation');
});
</pre>

To keep it simple you can use the internal escaping to build counterparts for ngettext, pgettext, as well as npgettext. A context is escaped by \x00. Singular and plural are separated by \x01:

<pre class="language-javascript">
// load gettext
var gt = require('io.ox/core/gettext');

// replace translation in dictionary 'io.ox/core'. Apps use context "app".
gt.addTranslation('io.ox/core', 'app\x00Address Book', 'My Contacts');

// replace translation - counterpart to ngettext
gt.addTranslation('io.ox/mail', 'Copy\x01Copies', { 0: 'Kopie', 1: 'Kopien' });

// replace translation - counterpart to npgettext
gt.addTranslation('io.ox/mail', 'test\x00One\x01Two', { 0: 'Eins', 1: 'Zwei' });

// some checks
require(['gettext!io.ox/mail'], function (gt) {

console.log('Sigular:', gt.ngettext('Copy', 'Copies', 1));
console.log('Plural:', gt.ngettext('Copy', 'Copies', 2));

console.log('Without context', gt.gettext('Files')); // should be 'My File Box'
console.log('With context', gt.pgettext('test', 'Files')); // should be 'Files'

console.log('Plural with context', gt.npgettext('test', 'One', 'Two', 2)); // should be 'Two'
});

</pre>

''addTranslation()'' always works for current language. If you want to benefit from automatic POT file generation, use the following approach:

<pre class="language-javascript">
define('plugins/example/register', ['io.ox/core/gettext', 'gettext!custom'], function (gettext, gt) {

'use strict';

/* Just list all custom translations in your plugin by standalone gt() calls.
The build system recognizes these strings and collects them in a POT file,
so that they can be subject to translation processes. At runtime, gt('...')
returns translations for current language.
*/
if (false) {
gt('Tree');
gt('House');
gt('Dog');
}

// get internal dictionary (for current language of course)
var dictionary = gt.getDictionary();

// add all translations to global dictionary. Done!
gettext.addTranslation('*', dictionary);
});
</pre>

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

AppSuite:Extending the UI (Hands-on introduction)

2016-02-10T11:54:43Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points:<br>Hands-on introduction</div>

'''Abstract'''

''Abstractly speaking extension points are an architecture for letting plugins contribute functionality to other parts of the program. They form the core of the OX App Suite plugin architecture. This is a hands-on introduction based on simple code examples. For more details take a look at [[ AppSuite:Extending_the_UI| Extending the UI]].''

__TOC__
==Extending the UI==
In case you want try code by your own please follow these steps:
* get a appropriate browser to execute custom javascript during runtime (for example chrome with it's [https://developers.google.com/chrome-developer-tools/docs/console developer tools])
* login on OX App Suite
* copy code from beyond to you console and execute
* perhaps it could be necessary to switch app or reload the page

=== Your first extension ===
Let's start with some example code.
<pre class="language-javascript"> // The extension point system lives in the
// 'io.ox/core/extensions' module
require(["io.ox/core/extensions"], function (ext) {

// An extension point represents the system that can be extended
// It has an id (in this case 'io.ox/mail/detail')
var point = ext.point("io.ox/mail/detail");

// Now, let's extend that extension point. Every extension point
// has some kind of contract about what it expects its extensions to provide.
// In this case, the extension is supposed to provide a draw method
// and is passed the node to draw into as the 'this' variable
point.extend({
id: 'example1', // Every extension is supposed to have an id
index: 1, // Extensions are ordered based on their indexes
draw: function () {
// This function is called by the part of the code that
// offers this extension point
this.append($("<h3>").text("Hello, Traveller!"));
}
});
});
</pre>

Please have a look at the detail view of a mail now. Perhaps you have to select another mail to see the difference.
<gallery>
File:Ui_ext_handson_1_1.png|step 1: default mail detail
File:Ui_ext_handson_1_2.png|step 2: execute code in chrome dev tools console
File:Ui_ext_handson_1_3.png|step 3: extended mail detail
</gallery>


=== A qualified mail footer ===
Let's try and add a section to the mails detail view and use some data of the currently viewed mail. For information about the baton object please take a look at the [[ AppSuite:Extending_the_UI| more detailed]] article how to extend the UI.

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

ext.point("io.ox/mail/detail").extend({
id: "lessonExample",
index: 300,
draw: function (baton) {
var data = baton.data;
this.append("<br>");
this.append($("<em>").append(
$.txt("The eMail '"),
$("<b>").text(data.subject),
$.txt("' was brought to you by: "),
$("<b>").text("Your Name Inc.")
));
}
});

});
</pre>

<gallery>
File:Ui_ext_handson_3_1.png|step 1: default mail detail
File:Ui_ext_handson_3_2.png|step 2: execute code in chrome dev tools console
File:Ui_ext_handson_3_3.png|step 3: extended mail detail
</gallery>

After switching to the mail app again, you might have to select another mail to once again run through the rendering process that calls on the extensions. As you can see in the example above, the code calling the extension passes along the eMail in the ''data'' attribute of the [[AppSuite:Extending_the_UI#Baton | baton]] parameter. The ''index'' of the extension means that it is rendered after the mail body, who's extensions index is '''300'''. Currently (until we have more comprehensive documentation) you can only find the indexes (and the way an extension is supposed to behave) by reading our code. Reload the page (to clear out the registered extensions) and try switching the index to '''190''' and see where the added sentence shows up now.

==Customizing the UI==
Since extensions are a property of the runtime system, you can also modify them. The extension system offers a couple of things you can do with existing extensions like '''changing their order, disabling them or replacing them.''' Let's look at how to accomplish all of these, again by modifying the mail detail view.

===switch off inline links===
<pre class="language-javascript">
require(["io.ox/core/extensions"], function (ext) {
// Here the id of the extension comes into play again.
// If you look at the code of the mail detail view (in io.ox/mail/view-detail)
// You can see the extension registers itself with the id 'inline-links'
// So that is the argument we pass to disable
ext.point("io.ox/mail/detail").disable('inline-links');
});
</pre>

<gallery>
File:Ui_ext_handson_4_1.png|step 1: default mail detail
File:Ui_ext_handson_4_2.png|step 2: execute code in chrome dev tools console
File:Ui_ext_handson_4_3.png|step 3: mail detail with disabled inline links
</gallery>

''Again: When navigating back to the email view you might have to select another mail to make this change visible.''

===replace the way time is rendered===

<pre class="language-javascript">
require(["io.ox/core/extensions", "io.ox/mail/util", "io.ox/core/date"], function (ext, util, date) {
ext.point("io.ox/mail/detail/header").replace({
//current extension will extended not fully replaced
// so we do not have to specify the index to keep time on it's place
id: 'receiveddate', // The extension we want to replace has this id as well
draw: function (baton) {
var data = baton.data;
//show unix timestamp (plus trailing '000' for milliseconds )
var timeToRender = (data.received_date || data.sent_date || 0);
this.append(
$('<div>').addClass('date list').text(timeToRender)
);
}
});
});
</pre>

<gallery>
File:Ui_ext_handson_5_1.png|step 1: default mail detail
File:Ui_ext_handson_5_2.png|step 2: execute code in chrome dev tools console
File:Ui_ext_handson_5_3.png|step 3: extended mail detail with unix timestamp
</gallery>

=== change order ===
And now let's switch the order around:

<pre class="language-javascript">
require(["io.ox/core/extensions"], function (ext) {
// From the extension point 'io.ox/mail/detail' get the extension with
// the id 'subject' (which is passed to the callback)
ext.point("io.ox/mail/detail/header").get("subject", function (extension) {
// Put it last
extension.index = 300;
});

});
</pre>

<gallery>
File:Ui_ext_handson_6_1.png|step 1: default mail detail
File:Ui_ext_handson_6_2.png|step 2: execute code in chrome dev tools console
File:Ui_ext_handson_6_3.png|step 3: pushed subject to header bottom
</gallery>

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

== Trouble finding the right extension point? ==

You don't know where to append your plugin's content / which extension point you should use?
A good way to find the suitable extension point, is to search in the OX Source Code for an HTML-element displayed in the user interface. For example an easy to identify text. Once found the HTML-element in the source, you can see which extension point was used appending this element to the UI and append your content there aswell.

AppSuite:Extending the UI (best practices)

2016-02-10T11:54:21Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points:<br> Best practices</div>

'''Abstract'''

''The extension points system allows different strategies to realize the desired behavior. This is a list of solutions for common scenarios pointing out also some disadvantages of different solutions.''

__TOC__

=== scenario: writing extension in general ===

''separate extension declaration and logic for reusability''

* example: io.ox/mail/common-extensions.js and io.ox/mail/detail/view.js

<code>
var fnProcess = function (baton) { ... };
// use function within some extension
ext.point('io.ox/mail/detail/content').extend({
id: 'links',
index: 100,
process: fnProcess
});
// use function within another extension
ext.point('io.ox/mail/detail/content').extend({
id: 'images',
index: 100,
process: fnProcess
});

</code>

=== scenario: hide/show action ===

''simply register a fresh new extension with an index less than the original action extension.''

<code>
// original extension
new Action('io.ox/mail/actions/compose', {
id: 'compose',
index: 100,
requires: function () {
return true;
},
...
});

// your extension to hide it
ext.point('io.ox/mail/actions/compose').extend({
// must be a different id than used in original extension
id: 'compose_preprocess',
// important: must be smaller than the one used in original extension that is usually 'default'
index: 50,
requires: function (e) {
// is your condition meet?
if (myCondition === true) {
// stop propagation to suppress execution of
// requires-handlers of extensions with a higher index
e.stopPropagation();
// force hide (or force show by using 'return true')
return false;
}
}
});
</code>

'''unfavorable variants'''

''using ext.point(...).replace''

* original requires function is replaced and can not be accessed anymore
* also copy and paste it contents does not help cause future changes are not carried over automatically
* see [[AppSuite:Extending_the_UI#replace_extension | documentation for .replace ]]
<code>
// please do not use replace to overwrite 'requires'
ext.point('io.ox/mail/actions/compose').replace({
requires: function () {
// my custom logic
}
})
</code>

=== scenario: stop propagation of action ===

''simply register a fresh new extension with an index less than the original action extension.''

<code>
// original extension
new Action('io.ox/mail/actions/compose', {
index: 100,
requires: function () {
return true;
},
...
});

// your extension to hide it
ext.point('io.ox/mail/actions/compose').extend({
// must be a different id than used in original extension that is usually 'default'
id: 'compose_preprocess',
// important: must be smaller than the one used in original extension
index: 50,
action: function (baton) {
// be robust when clicked again and conditions may have changed
baton.enable('default');
if (myCondition === true) {
baton.disable('default');
}
}
});
</code>

'''hint'''
In case the condition for a single action target (f.e. a mail item) do not change you can use 'baton.preventDefault()' alternatively when you condition is met.

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extending the UI

2016-02-10T10:16:59Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points:<br>General information </div>

'''Abstract.''' Abstractly speaking extension points are an architecture for letting plugins contribute functionality to other parts of the program. They form the core of the OX App Suite plugin architecture. A less detailed hands-on introduction can be found [[ AppSuite:Extending_the_UI_(Hands-on_introduction) | here]]. Some basics about the extention point concept and advantages compared to inheritance.
__TOC__
== Introduction ==
=== Inheritance vs. Extension points ===
OX App Suite uses the extension point concept to create extension points that allow a simple and flexible way to extending functionality. When system reaches a part that can be extended it asks a central registry if extensions are registered. In that case these extensions will be executes independent of the providing component (some plugin or OX App Suite itself).

The illustrated example compares inheritance and extension points. The main benefit of using extension points is that the programm is still the active component and it's in controll. This leads to the following advantages:
* Reduced coupling
* Increased cohesion
* Modularity- Re-usability
* Dynamic

[[File:Ui_ext_01.gif|frame|border|left]]

=== Some characteristics ===
* good fences: extension points unregister corrupt extenders
* lazy loading: extenders are loaded if they are used
* fair play: all extenders have equal rights
* diversity: extension points support different extension

=== Components ===
The extension point system lives in the 'io.ox/core/extensions' module and consists of these elements:
* extension point system: accessing the outer parts
* registry: manages extension points, extensions and their state
* extension point: part of the systems that can be extended, referenced by a unique id
* extension: adding/replacing functionality during runtime, referenced by a unique id
* baton: object used to store context, passed back through callbacks

==Extension Point System==
<pre class="language-javascript"> //load extension points module
require(['io.ox/core/extensions'], function (ext) {
//insert code here
});</pre>

== Registry ==
* manages extension points, extensions and their state

=== list points ===
<pre class="language-javascript"> // returns array of point ids
var keys = ext.keys();
</pre>

=== get/create point ===
<pre class="language-javascript"> //also registers a point if not happened yet
var mypoint = ext.point('io.ox/calendar/detail');
</pre>

== Extension Point ==
* part of the systems that can be extended
* referenced by a unique id
* defines some kind of contract it's extension that to comply

=== attributes ===
* id
* description (optional)

'''''example'''''

<pre class="language-javascript"> //get a point and it's description
var point = ext.point('io.ox/mail/links/toolbar'),
descr = point.description = '';
</pre>

=== add extension ===
* important: existing extensions with same id will not be overwritten - use replace instead
* If the id is not specified, the value 'default' is used.
* example: add extension with id 'date'

'''''example'''''
<pre class="language-javascript"> // chainable (returns mypoint)
point.extend({
id: 'example1', // Every extension is supposed to have an id
index: 100, // Extensions are ordered based on their indexes
draw: function () {
//draw something
}
});
</pre>

=== replace extension ===
* important: only extension properties will be replaced (jQuery extend is used internally)
* when calling replace on a not yet existing extension a new extension is created
* hint: therefore ''replace'' can also be executed before extension is initially created with ''extend''

'''''example'''''
<pre class="language-javascript"> // chainable (returns mypoint)
mypoint.replace({
id: 'example1',
index: 100,
draw: function (baton) {
//draw something completely different
}
});
</pre>

=== use extensions===
* ''invoking'' extension point extensions by defining functionname, context and baton
* node used as context (function is called via apply(node, args))
* baton forwarded within programmatic flow and used for storing and exchanging data between extensions

<pre class="language-javascript">
mypoint.invoke(name, context, baton);
</pre>

'''''example'''''
<pre class="language-javascript"> //call 'draw' of all registered extensions (order defined by index attribute)
//node used as context ('draw' function is called via apply(node, args))
//baton's data property contains relevant information about current entity (for example a mail object)
mypoint.invoke('draw', node, baton);
</pre>

=== access extensions ===
<pre class="language-javascript">
// returns array containing all extension ids
mypoint.keys();

// returns array containing all extensions
mypoint.all();

// executes callback for a specific extension; chainable (returns point)
mypoint.get(id, callback);

// disabled extension will return true also;
var exists = mypoint.has(id);
</pre>

'''''enabled only'''''
<pre class="language-javascript">
// returns array containing all enabled extensions
mypoint.list();

// returns number containing enabled extensions
mypoint.count();
</pre>

=== enabling/disabling ===
<pre class="language-javascript">
var enabled = mypoint.isEnabled(id);</pre>
<pre class="language-javascript"> // chainable (returns mypoint)
mypoint.enable(id);</pre>
<pre class="language-javascript"> // chainable (returns mypoint)
mypoint.disable(id);</pre>

'''example'''

<pre class="language-javascript"> //disable
ext.point('io.ox/mail/detail/header').disable('receiveddate');</pre>

=== underscore equivalents ===
* only considers enabled extensions
* functions returns underscore-chain object of enabled extensions
* take a look at [ http://underscorejs.org ] for more details

<pre class="language-javascript"> mypoint.chain();
mypoint.each(callback);
mypoint.map(callback);
mypoint.filter(callback); //select alias
mypoint.reduce(callback, memo); //inject alias
mypoint.pluck(propertyName);</pre>

'''example'''

<pre class="language-javascript"> // Shuffle extension order
ext.point('io.ox/calendar/detail').each(function (e) {
e.index = Math.random() * 1000 >> 0;
}).sort();</pre>

=== Event Hub ===

* Event Hub based on jQuery's ''on'', ''off'', ''one'' and ''trigger''
* differences documentated for each function

<pre class="language-javascript"> // attach listener
mypoint.on(type, data, function);</pre>
<pre class="language-javascript"> // detach listener
mypoint.off(type, function);</pre>
<pre class="language-javascript"> // attach listener for a single execution
mypoint.one(type, data, function);</pre>
<pre class="language-javascript"> // trigger event
// difference: allows multiple types separated by spaces.
// difference: actually calls triggerHandler since we are not in the DOM.
mypoint.trigger(types);</pre>
<pre class="language-javascript"> // explicit destroy to clean up.
mypoint.destroy();</pre>

== Extension ==
* adding/replacing functionality during runtime
* referenced by a unique id

=== Attributes ===
* id
* index (optional): numeric value used for specify order of execution (also valid are 'first' and 'last')
* functions: as required by the extension point contract

''''example'''

<pre class="language-javascript">
//defining a extension for some extension point that requires a draw function
{
id: 'example1',
index: 100,
draw: function () {
//draw something
}
};</pre>

=== execution order ===

To ensure your extension is called first or last use the index 'first' or 'last'. Keep in mind that a defined call order does not guarantees all extensions with a lower index finished already when your extension is called (for example some asynchronous code). Nevertheless for the most common use case (draw extensions that create/modify nodes with already present data) this execution order should be quite reliable to do some DOM manipulation within an custom extension indexed as 'last'. If more than one extension of a point has the index 'first' or 'last' these will be executed first/last in the order they were added.

=== extensions patterns ===
OX App Suite uses extensions patterns. Please keep in mind that this list not necessarily covers all pattern currently used.

'''io.ox/backbone/forms.js'''
*CheckBoxField
*ControlGroup
*DateControlGroup
*DatePicker
*ErrorAlert
*Header
*InputField
*Section
*SectionLegend
*SelectBoxField
*SelectControlGroup

'''io.ox/backbone/views.js'''
*AttributeView

'''io.ox/calendar/edit/recurrence-view '''
* RecurrenceView

'''io.ox/core/extPatterns/links'''
*Button
*DropdownLinks
*InlineLinks
*link
*ToolbarLinks

'''io.ox/core/tk/attachments'''
*AttachmentList
*EditableAttachmentList

'''io.ox/contacts/widgets/pictureUpload.js'''

'''io.ox/preview/main.js'''
*Engine

== Baton ==
Part of extension points system is a structure called baton which serves as an context object. The baton passed back through callbacks within programmatic flow allowing data exchange between extension points.

=== attributes ===
* data: usually contains current entity object, also used for data exchange
* options: contains data such as the current active application if a baton is used comprehensively
* flow:
** disabled: stores disabled extensions (managed via baton.disable(pointId, extensionId))<br />
* $: used to reference a jQuery node object

=== disable extensions ===

<pre class="language-javascript"> //disable
baton.disable(pointid, extensionid);

//is disabled
var isDisabled = baton.isDisabled(pointid, extensionid);</pre>

'''example'''

<pre class="language-javascript"> var pointid = 'io.ox/mail/detail',
extensionid = 'example3',
node = $('div'),
baton = ext.Baton();

//disable extension
//returns undefined
baton.disable(pointid,extensionid);

//invoke extension with baton instance
ext.point(pointid).invoke('draw', node, baton)</pre>

=== data exchange ===

'''example'''

<pre class="language-javascript"> //extension using baton to store data
{
id: 'example1',
index: 100,
draw: function (baton) {
//get the currenty process mail object
var mail = baton.data;
//append subject to current node referenced as this
this.append(
$('div').text(mail.subject);
)
//extend mail object to store some flag
mail.drawn = mail.drawn || {};
mail.drawn.subject = true;
//disable extension3
baton.disable()
}
};
{
id: 'example2',
index: 200,
draw: function (baton) {
//get the currenty process mail object
var mail = baton.data;
//use value set by 'example1'
if(mail && mail.drawn && mail.drawn.subject) {
//do something
}
}
};
{
id: 'example3',
index: 300,
draw: function (baton) {
//wil not be executed if baton from 'disable example' is used
}
};</pre>

=== ensure ===
* ensure that submitted object is instanceof baton
* return obj if it's an instanceof baton
* return new baton instance '''where baton.data''' is extended by obj ''or'' obj.data (if exists)

<pre class="language-javascript"> var baton = ext.Baton.ensure(obj)
</pre>

'''example'''

<pre class="language-javascript"> //new baton.data extended by object
var baton = ext.Baton.ensure({ id: 2 })</pre>

[[File:Ui_ext_02.png|Ui_ext_02.png]]

== Conclusion ==

As you can see, unlike adding functionality, customizing and modifying existing extensions is always more of a grey box operation and might incur some risks when updating the software. For example when replacing a certain functionality parts of the original functionality will have to be reimplemented, and all that extra code will have to be maintained in the future.

In essence extension points are better suited to integrating new functionality into the product rather than customizing existing functionality, but, when in a pinch or really wanting to change a certain part of the software, this is certainly a way to consider. At its most extreme use you could even disable all extensions for the mail detail view to register a set of your own extensions to completely change the way mails are displayed, at the cost of having to maintain your own detail view.

This wraps up our little tour of the OX App Suite extension point system. It is used to integrate new functionality into the OX App Suite and provides a system for 3rd party applications to become extensible themselves. It can be used to customize the existing UI at the cost of havint to know a bit more about the internals of our application. For now until more comprehensive documentation becomes available, look at the existing OX App Suite code to see concrete extensions and extension points in action.

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Using the Upsell widget

2016-02-10T10:15:18Z

Frank.paczynski:

'''Summary''': The Upsell widget is going to be released with 7.4.1. It uses an existing portal widget, which you just need to configure on the backend. It makes use of the [[AppSuite:Configuring portal plugins|config options]].

<div class="title">Using the Upsell widget</div>

__TOC__

== Nomenclature and inner workings ==
The ''widget'' is one portal tile. A ''tile'' covers one topic, like "Buy more storage capacity!". One widget contains several slides, like "this is why you need more storage space", "your neighbours have more storage space than you", "Your colleagues at work have more storage space than you" and "Your significant other dreams of more storage space". ''Slides'' contain a picture or a text (or both) that advertise one topic. A click on the tile (independent of which slide is shown) can start an app, usually an Upsell wizard.

== YaML file ==
=== Example layout ===
<pre>
io.ox/portal//widgets/protected:
upsellads_0:
plugin: "plugins/portal/upsellads/register"
type: "upsellads"
index: 0
changeable:
index: true
props:
ad: "loremgibsum"

io.ox/upsell//ads:
loremgibsum:
capabilities: loremgibsum-active
startDate: 2013-01-01
endDate: 2013-12-31
slides:
en_US:
slide1:
type: text-only
text: nodal point -ware pen drone pre- shrine otaku. lights vehicle decay uplink concrete engine vehicle. nano- smart- face forwards office shoes beef noodles courier. computer advert wristwatch A.I.
slide2:
type: text-top
image: http://placekitten.com/1024/768
text: plastic drugs paranoid -ware fluidity artisanal grenade. meta- RAF franchise sentient shrine nodality savant. smart- woman otaku hotdog woman rebar construct. car hacker garage crypto- dolphin industrial grade sprawl. soul-delay pen boat city computer artisanal beef noodles. nodal point table engine A.I. numinous crypto- chrome. denim market render-farm shrine spook meta- footage. claymore mine saturation point dolphin singularity meta- advert decay nano- receding into warehouse motion geodesic RAF faded apophenia.
slide3:
type: text-bottom
image: http://placekitten.com/960/720
text: urban Kowloon assassin skyscraper systema table render-farm. cyber- free-market grenade pistol network engine futurity. youtube paranoid sprawl shoes fetishism nodal point dead. otaku katana decay narrative man tanto dead. range-rover bomb digital BASE jump silent soul-delay crypto-. post- construct apophenia silent soul-delay nodal point drugs. computer tanto receding sensory bridge neon refrigerator. claymore mine saturation point dolphin singularity meta- advert decay nano- receding into warehouse motion geodesic RAF faded apophenia. realism gang warehouse A.I. bridge film post- tank-traps sign youtube
</pre>

=== Explanations ===
The .yml file contains two sections. The first defines the widget itself, how it is place, that it is not removable, but can be moved around. This seems to be a good setup for advertisements, but variations can be found in [[AppSuite:Configuring portal plugins|Configuring portal plugins]].

The second section defines the content of the widget. The main part are the slides, but there is also the option to make sure this ad only runs for a specific time frame.

The two parts are connected by an ID (in this case "loremgibsum"), which is in ...props.ad for the first part and is the key in the second part.

== Conventions ==
* if the user's language cannot be matched, the first language given is used. In most cases, it is prudent to make that some English variant.
* Slides are named "slide1", "slide2" and so on. This is due to the OX parser not being able to deal with YaML lists, not working with integers as keys and due to JavaScript doing some weird sorting of keys in an object.
* Start and end date are interpreted in the user's time zone.
* remember that ''you'' will have to provide the translations. You won't be able to get the translators of the main product to do it for you.

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

[[Category: AppSuite]]

[[Category: UI]]
[[Category: Backend]]

[[Category: Admin]]
[[Category: Sales]]

AppSuite:Extension points for core

2016-02-10T09:20:17Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for appsuite core</div>
'''Abstract:''' This describes extension points for the appsuite core, allowing you to add functions.

==io.ox/core/apps/category==
==io.ox/core/apps/installed==
==io.ox/core/apps/manage==
==io.ox/core/apps/store==
==io.ox/core/desktop==
==io.ox/core/notifications/due-tasks/header==
==io.ox/core/notifications/due-tasks/item==
==io.ox/core/notifications/invites/header==
==io.ox/core/notifications/invites/item==
==io.ox/core/notifications/mail/header==
==io.ox/core/notifications/mail/item==
==io.ox/core/notifications/register==
==io.ox/core/notifications/task-reminder/header==
==io.ox/core/notifications/task-reminder/item==
==io.ox/core/person:action==
==io.ox/core/relogin==
==io.ox/core/tk/attachments/links==
==io.ox/core/topbar==
==io.ox/core/topbar/favorites==
==io.ox/core/topbar/launchpad==
==io.ox/core/topbar/right==
==io.ox/core/topbar/right/dropdown==

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extension points for miscellaneous

2016-02-10T09:19:50Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Miscellaneous Extension points</div>
'''Abstract:''' This describes miscellaneous extension points, allowing you to add functions.

=application-foldertree=
==io.ox/application-foldertree/links==

=backbone=
==io.ox/backbone/validation/formats==

=conversations=
==io.ox/conversations/actions/create==
==io.ox/conversations/links/toolbar==

=folder=
==io.ox/foldertree/folder==

=halo=
==io.ox/halo/contact:renderer==
==io.ox/halo/contact:requestEnhancement==

=help=
==io.ox/help/helper==

=keychain=
==io.ox/keychain/api==
==io.ox/keychain/model==

=portal=
==io.ox/portal/settings/detail==
==io.ox/portal/widget==
==io.ox/portal/widget/mail==
==io.ox/portal/widget/mail/actions/compose==
==io.ox/portal/widget/mail/links/inline==

=preview=
==io.ox/preview/engine==

=settings=
==io.ox/settings/accounts/mail/settings/detail==

=linkedIn=
==io.ox/linkedIn/details/actions==
==io.ox/linkedIn/details/renderer==

=plugins=
==io.ox/plugins/portal/linkedIn/updates/renderer==

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extension points for tasks

2016-02-10T08:58:24Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for tasks</div>
'''Abstract:''' This describes extension points for the tasks module, allowing you to add functions.

==io.ox/tasks/attachment/links==
==io.ox/tasks/detail-attach==
==io.ox/tasks/detail-inline==
==io.ox/tasks/links/inline==
==io.ox/tasks/model/validation==
==io.ox/tasks/settings/detail==
==io.ox/tasks/vgrid/toolbar==

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Create custom folderview entries in settings app

2016-02-10T08:53:34Z

Frank.paczynski:

<div class="title">Extension points:<br>Create custom folderview entries in settings</div>

'''Abstract'''

''This articles covers which extension points are provided by the settings app and how to extend them to add custom folderview entries. ''

__TOC__

==Add a new settings link==

By default, the folderview in settings contains four sections. If you want to add a link to a section, you have to find out the ID of the section. The extension point you are looking for has the name <pre class="language-javascript">'io.ox/settings/pane/' + sectionID</pre>For example, if you want to have a setting in the section external (this is where you should usually put your settings) you can use the following code:

<pre class="language-javascript">
ext.point('io.ox/settings/pane/external').extend({
title: gt('Title'),
index: 350,
id: 'myUniqueID',
ref: 'reference/to/settings/page'
});
</pre>

==Create a subsetting link==

Let's say you have a setting and you want to add a subsetting beyond that. To do this, you have to know the name and ID of the parent extension point. Then you simply have to extend the extension point with the name: <pre class="language-javascript">parentName + '/' + parentID</pre> The following code example creates a subsetting for the setting created above:

<pre class="language-javascript">
ext.point('io.ox/settings/pane/external/myUniqueID').extend({
title: gt('Title of Subsetting'),
index: 100,
id: 'myOtherUniqueID',
ref: 'reference/to/other/settings/page'
});
</pre>

==Create a new settingsgroup==

If you have several settings that should be provided in a seperate section, you can extend the following extension point:

<pre class="language-javascript">
ext.point('io.ox/settings/pane').extend({
id: 'mySectionID',
index: 500,
subgroup: 'io.ox/settings/pane/mySectionID'
});
</pre>

You have to provide a unique sectionID and a unique subgroupID to create a section. If you want to add links to this section, you just have to extend the extension point <pre class="language-javascript">'io.ox/settings/pane/mySectionId'</pre>

AppSuite:Extension points for email

2016-02-10T08:52:52Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for e-mail</div>
'''Abstract:''' This describes extension points for the e-mail module, allowing you to add functions.

== io.ox/mail/all/actions ==
The point for the "all" actions dropdown in the detail view of a selected mail.
This place should be used for actions in context with all involved contacts.
The baton is forwarded to the the single action functions.

baton contains:
data - holds the mail object of the current selected contact

data.threadKey -
data.threadPosition -
data.threadSize -
tracker

== io.ox/mail/attachment/links ==
The point for actions related to the attachments of a mail.

== io.ox/mail/detail ==
The point for the detail view of a selected mail.
The baton is forwarded.
It is followed by points for each mail detail:

* io.ox/mail/detail/contact-picture
* io.ox/mail/detail/receiveddate
* io.ox/mail/detail/fromlist
* io.ox/mail/detail/thread-position
* io.ox/mail/detail/flag
* io.ox/mail/detail/subject
* io.ox/mail/detail/tocopy
* io.ox/mail/detail/attachments
* io.ox/mail/detail/inline-links
* io.ox/mail/detail/phishing-warning
* io.ox/mail/detail/externalresources-warning
* io.ox/mail/detail/content

== io.ox/mail/detail/notification ==
The point for the notification handling.
A extended mail object is forwarded.

== io.ox/mail/detail/notification/update-notification ==
The point to remove read mails in notification Area.

== io.ox/mail/dnd/actions ==
The point for mail import via drag & drop.

== io.ox/mail/links/inline ==
The Point for inserting actions like reply & delete.

== io.ox/mail/settings/detail ==
The point for the mail settings detailpage.

== io.ox/mail/settings/detail/section ==
This point is not longer supported.

== io.ox/mail/thread ==
The Point for inserting actions related to the whole thread like move & delete.
The baton is forwarded.

== io.ox/mail/vgrid/options ==
The point for applying options to the vgrid related to the mail app.

=== sort ===
* specifies default sort field
* in case threadview is enabled/used and default sort field is '''not''' set to 'thread' user has to select 'sort by -> chat' manually after each login/page refresh
* alternatively you can use sever setting ''''io.ox/mail//vgrid/sort=''''

''option: by date''
<pre>
sort: 610
</pre>

''option: by from''
<pre>
sort: 603
</pre>

''option: by subject''
<pre>
sort: 607
</pre>

''option: by label''
<pre>
sort: 102
</pre>

''option: show threads (if threadview is enabled), sort by date (if threadview are disabled)''
<pre>
sort: 'thread'
</pre>

== io.ox/mail/vgrid/toolbar ==
The point for extending the vgrid toolbar in the mail app.

== io.ox/mail/write/toolbar ==
The point for inserting inline buttons on top of the mail write view.

== io.ox/mail/write/actions/send ==
The point for the action related to the send button.
The baton is available.
== io.ox/mail/write/autoCompleteItem (since 7.4.2) ==
The point for extending the autocomplete items in the mail app.

== io.ox/mail/write/contactItem (since 7.4.2) ==
The point for extending the contact list items in the mail app.

== io.ox/mail/write/contactPicture (since 7.4.2) ==
The point for extending contact picture in autocomplete and contact list.

== io.ox/mail/write/displayName (since 7.4.2) ==
The point for extending display name in autocomplete and contact list.

== io.ox/mail/write/emailAddress (since 7.4.2) ==
The point for extending email address in autocomplete and contact list.

== io.ox/mail/write/actions/draft ==
The point for the action related to the save button.
The baton is available.

== io.ox/mail/write/actions/discard ==
The point for the action related to the discard button.
The baton is available.

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extension points for files

2016-02-10T08:39:36Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for files</div>
'''Abstract:''' This describes extension points for the files module, allowing you to add functions.

==io.ox/files/actions/edit/cancel==
==io.ox/files/actions/edit/save==
==io.ox/files/create/action==
==io.ox/files/create/form==
==io.ox/files/details/sections==
==io.ox/files/details/sections/content==
==io.ox/files/details/sections/header==
==io.ox/files/details/sections/header/basicInfo==
==io.ox/files/details/sections/upload==
==io.ox/files/details/sections/versions==
==io.ox/files/details/versions/details==
==io.ox/files/dnd/actions==
==io.ox/files/icons==
==io.ox/files/icons/actions==
==io.ox/files/icons/file==
==io.ox/files/icons/inline==
==io.ox/files/links/edit/inline==
==io.ox/files/links/inline==
==io.ox/files/settings/detail==
==io.ox/files/shortcuts==
==io.ox/files/versions/links/inline==

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extension points for calendar

2016-02-10T08:38:54Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for calendar</div>
'''Abstract:''' This describes extension points for the calendar module, allowing you to add functions.

==io.ox/calendar/detail==
==io.ox/calendar/detail/actions==
==io.ox/calendar/detail/actions-participantrelated==
==io.ox/calendar/detail/actions/create==
==io.ox/calendar/detail/actions/edit==
==io.ox/calendar/detail/attachments==
==io.ox/calendar/detail/date==
==io.ox/calendar/detail/details==
==io.ox/calendar/edit/dnd/actions==
==io.ox/calendar/edit/section/buttons==
==io.ox/calendar/edit/section/title==
==io.ox/calendar/links/inline==
==io.ox/calendar/links/inline-participants==
==io.ox/calendar/model/validation==
==io.ox/calendar/month/view/appointment==
==io.ox/calendar/settings/detail==
==io.ox/calendar/vgrid/toolbar==
==io.ox/calendar/week/view/appointment==

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Extension points for contact

2016-02-10T08:35:16Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Extension points for contact</div>
'''Abstract:''' This describes extension points for the contact module, allowing you to add functions.

==io.ox/contacts/api/search ==
An opportunity to extend search requests. Extensions are called as methods on the search request object and can modify it before it is sent to the server.
The search request as described in the [http://oxpedia.org/wiki/index.php?title=HTTP_API#SearchContactsAlternative HTTP API].
<pre class="text">* this - take a look at the linked HTTP API documentation.
* query ''string'' - The search query as entered by the user.
* options ''Object'' - The options object passed to the contacts search API.
</pre>

==io.ox/contacts/detail==
The mainpoint for the detail view of a selected single contact. The baton is forwarded as argument.<br /><br /> baton contains:<br />

<pre class="text">app

e.g.

app.attributes - functions and infos related to the contact app
app.attributes.window - functions and infos related to the app window (e.g. addButton etc.)
app.currentContact - provides access to the folder_id and the id of the current selected contact
app.settings- provides access to the app settings</pre>
<pre class="text">data - holds the contact data object of the current selected contact</pre>

==io.ox/contacts/detail/head==
The Point in the contact detail view for the headregion of a single selected contact. The baton is forwarded as argument.<br />

==io.ox/contacts/detail/actions==
The mainpoint for inserting actions related to the selected contact. The contact data object (baton.data) is forwarded as argument.<br />

==io.ox/contacts/links/inline ==
The Point for inserting actions like edit & delete.<br />

==io.ox/contacts/edit/view/personal==
The point for the personal section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/personal/title
* io.ox/contacts/edit/view/personal/first_name
* io.ox/contacts/edit/view/personal/last_name
* io.ox/contacts/edit/view/personal/display_name
* io.ox/contacts/edit/view/personal/second_name
* io.ox/contacts/edit/view/personal/suffix
* io.ox/contacts/edit/view/personal/nickname
* io.ox/contacts/edit/view/personal/birthday
* io.ox/contacts/edit/view/personal/marital_status
* io.ox/contacts/edit/view/personal/number_of_children
* io.ox/contacts/edit/view/personal/spouse_name
* io.ox/contacts/edit/view/personal/anniversary
* io.ox/contacts/edit/view/personal/url

==io.ox/contacts/edit/view/messaging==
The point for the messaging section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/messaging/email1
* io.ox/contacts/edit/view/messaging/email2
* io.ox/contacts/edit/view/messaging/email3
* io.ox/contacts/edit/view/messaging/instant_messenger1
* io.ox/contacts/edit/view/messaging/instant_messenger2

==io.ox/contacts/edit/view/phone==
The point for the phone section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/phone/cellular_telephone1
* io.ox/contacts/edit/view/phone/cellular_telephone2
* io.ox/contacts/edit/view/phone/telephone_business1
* io.ox/contacts/edit/view/phone/telephone_business2
* io.ox/contacts/edit/view/phone/telephone_home1
* io.ox/contacts/edit/view/phone/telephone_home2
* io.ox/contacts/edit/view/phone/telephone_company
* io.ox/contacts/edit/view/phone/telephone_other
* io.ox/contacts/edit/view/phone/fax_business
* io.ox/contacts/edit/view/phone/fax_home
* io.ox/contacts/edit/view/phone/fax_other
* io.ox/contacts/edit/view/phone/telephone_car
* io.ox/contacts/edit/view/phone/telephone_isdn
* io.ox/contacts/edit/view/phone/telephone_pager
* io.ox/contacts/edit/view/phone/telephone_primary
* io.ox/contacts/edit/view/phone/telephone_radio
* io.ox/contacts/edit/view/phone/telephone_telex
* io.ox/contacts/edit/view/phone/telephone_ttytdd
* io.ox/contacts/edit/view/phone/telephone_ip
* io.ox/contacts/edit/view/phone/telephone_assistant
* io.ox/contacts/edit/view/phone/telephone_callback

== io.ox/contacts/edit/view/home_address==
The point for the home address section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/home_address/street_home
* io.ox/contacts/edit/view/home_address/city_home
* io.ox/contacts/edit/view/home_address/state_home
* io.ox/contacts/edit/view/home_address/country_home

==io.ox/contacts/edit/view/business_address==
The point for the business address section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/business_address/street_business
* io.ox/contacts/edit/view/business_address/city_business
* io.ox/contacts/edit/view/business_address/state_business
* io.ox/contacts/edit/view/business_address/country_business

==io.ox/contacts/edit/view/other_address==
The point for the other address section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/other_address/street_other
* io.ox/contacts/edit/view/other_address/city_other
* io.ox/contacts/edit/view/other_address/state_other
* io.ox/contacts/edit/view/other_address/country_other

==io.ox/contacts/edit/view/job==
The point for the job section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/job/profession
* io.ox/contacts/edit/view/job/position
* io.ox/contacts/edit/view/job/department
* io.ox/contacts/edit/view/job/company
* io.ox/contacts/edit/view/job/room_number
* io.ox/contacts/edit/view/job/employee_type
* io.ox/contacts/edit/view/job/number_of_employees
* io.ox/contacts/edit/view/job/sales_volume
* io.ox/contacts/edit/view/job/tax_id
* io.ox/contacts/edit/view/job/commercial_register
* io.ox/contacts/edit/view/job/branches
* io.ox/contacts/edit/view/job/business_category
* io.ox/contacts/edit/view/job/info
* io.ox/contacts/edit/view/job/manager_name
* io.ox/contacts/edit/view/job/assistant_name

==io.ox/contacts/edit/view/userfields==
The point for the userfields section in the contact edit form. It is followed by points for each attribute:<br />

* io.ox/contacts/edit/view/userfields/userfield01
* io.ox/contacts/edit/view/userfields/userfield02
* io.ox/contacts/edit/view/userfields/userfield03
* io.ox/contacts/edit/view/userfields/userfield04
* io.ox/contacts/edit/view/userfields/userfield05
* io.ox/contacts/edit/view/userfields/userfield06
* io.ox/contacts/edit/view/userfields/userfield07
* io.ox/contacts/edit/view/userfields/userfield08
* io.ox/contacts/edit/view/userfields/userfield09
* io.ox/contacts/edit/view/userfields/userfield10
* io.ox/contacts/edit/view/userfields/userfield11
* io.ox/contacts/edit/view/userfields/userfield12
* io.ox/contacts/edit/view/userfields/userfield13
* io.ox/contacts/edit/view/userfields/userfield14
* io.ox/contacts/edit/view/userfields/userfield15
* io.ox/contacts/edit/view/userfields/userfield16
* io.ox/contacts/edit/view/userfields/userfield17
* io.ox/contacts/edit/view/userfields/userfield18
* io.ox/contacts/edit/view/userfields/userfield19
* io.ox/contacts/edit/view/userfields/userfield20

==io.ox/contacts/edit/view/comment==
The point for the comment section in the contact edit form. It is followed by a point for the attribute:<br />

* io.ox/contacts/edit/view/comment/note

==io.ox/contacts/edit/view/misc==
The point for the misc section in the contact edit form. It is followed by a point for the attribute:<br />

* io.ox/contacts/edit/view/misc/private_flag

==io.ox/contacts/edit/main/model==
The point for adding additional functions to the model of a contact.

==io.ox/contacts/model/validation/distribution_list ==
The point for adding additional validation to the distribution_list array.<br />

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

AppSuite:Files App Actions

2016-02-10T07:47:31Z

Frank.paczynski:

{{Stability-experimental}}

<div class="title">Adding actions to the files detail area</div>

To add an action to the files app detail area the extensionpoint io.ox/files/links/inline is used.
Use the Link pattern in io.ox/core/extPatterns/links.js to extend this point.
Try via console:

<pre class="language-javascript">
require(['io.ox/core/extensions', 'io.ox/core/extPatterns/links'], function (ext, links) {

new links.Action('io.ox/files/actions/testlink', {
requires: function (e) {
e.collection.has('some') && capabilities.has('webmail');
},
multiple: function (baton) {
console.log(baton);
}
});

ext.point('io.ox/files/links/inline').extend(new links.Link({
id: 'testlink',
index: 400,
label: 'labelname',
ref: 'io.ox/files/actions/testlink'
}));
});
</pre>

== Action ==
The first argument is the unique id of the action.

requires - checks for the needed components and the collection status. (''some'' is used for multiple elements, ''one'' for an single one)

* If the action is used only on a single element use action.
* If the action should be applied to multiple elements use multiple.
* In both cases the baton is available to the action.

== Link==
* id - must be unique
* index - the position/order of the link
* label - the label for the link
* ref - the reference to the action id

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

AppSuite:Writing a wizard

2016-02-10T07:01:28Z

Frank.paczynski:

<div class="title">Writing a wizard</div>

'''Summary:''' In this example we will build a simple welcome wizard that tries to complete the users information.

__TOC__

== A simple welcome wizzard ==

<syntaxhighlight lang="javascript">
/**
* All content on this website (including text, images, source
* code and any other original works), unless otherwise noted,
* is licensed under a Creative Commons License.
*
* http://creativecommons.org/licenses/by-nc-sa/2.5/
*
* Copyright (C) Open-Xchange Inc., 2006-2011
* Mail: info@open-xchange.com
*
* @author Francisco Laguna <...>
*/

/**
* In this example we will build a simple welcome wizard, that tries to complete the users information.
*/
define('io.ox/dev/wizard/welcomeWizard', ['io.ox/core/extensions', 'io.ox/core/wizard/registry'], function (ext, wizards) {
'use strict';
// Grab the extension point for the wizard
// Every page in the wizard will be an extension to this extension point
var point = ext.point("io.ox/dev/wizard/welcomeWizard");

// We will build a few pages here to showcase how you can use the framework.
// Firstly, the simplest case, just a static page
// It's a nice trick to start off with a static page, so the subsequent page
// can already start loading data
// and initialize itself without the user having to wait around for that.
// Distract them with a nice welcome page!
point.extend({
id: 'welcomeMessage',
index: 100,
title: "Welcome to App Suite", // be sure to internationalize this
draw: function (baton) {
// A regular #draw method, that you may know and love from other extension points
// Just append to 'this' to draw what you need. One caveat though: Make sure to
// unlock the 'next' button
// so this step can be finished

// Some text. Note that you want to take some more care here, to make this look
// good and make sense. We'll firmly stay in example land here and not make a
// fuss about looks
// Make sure you do better than this, also, this needs to be internationalized
// with a gt() call!
this.append($("<p>").text("Hi there, stranger! Welcome to OX App Suite, glad you made it. To make sure your experience with us is a pleasant one, let's set up some basics together!"));

// Enable the next (or 'done', if this is the last page) button.
// You will have to call this once for every page, once every needed entry has been made.
baton.buttons.enableNext();
}
});

// Now let's actually ask for some user input. Let's start with the users gender.
point.extend({
id: 'gender',
index: 200,
title: "Gender",
draw: function (baton) {
// Every method of a page is always called with a baton that is unique to
// every page instance, so
// we can set state information in it to our hearts content without
// bothering everyone else.
// The baton holds some interesting objects, though. 'wizard' is the instance
// of the wizard object, 'buttons', like above
// can be used to enable or disable the next button. The wizard also has a
// pageData member object that we can use to store
// data that is available to every subsequent page. Note though, that that
// tightly couples pages together, so use this with care!
// We will use this for some fun, though.
baton.form = {};

this.append(
$('<p/>').text("Please pick one:"),
$('<form>').append(
$("<fieldset>").append(
$('<label class="radio">').append(
baton.form.male = $('<input type="radio" name="genderRadio" value="male">'),
$.txt("Gentleman")
),
$('<label class="radio">').append(
baton.form.female = $('<input type="radio" name="genderRadio" value="male">'),
$.txt("Lady")
)
)
)
);

// We want to enable the navigation once the user picked his or her gender.
// And we'll capture that logic in one method that we call everytime we have
// reason to believe the state changed
baton.helpers = {
updateState: function () {
if (baton.form.male.attr("checked") === 'checked' || baton.form.female.attr("checked") === 'checked') {
// One of the two was picked, so enable the next button
baton.buttons.enableNext();
} else {
// No choice was made, so disable the button
baton.buttons.disableNext();
}
}
};
baton.form.male.on('click', baton.helpers.updateState);
baton.form.female.on('click', baton.helpers.updateState);

},

activate: function (baton) {
// Whenever the page is entered, the activate method is called.
// we just have to make sure the button state is correct
baton.helpers.updateState();
},

finish: function (baton) {
// When the page is left, the 'finish' method is called and we can do something
// with the entered value, in this case we'll remember it in the wizards data section for inter-page stuff

var gender = null;
if (baton.form.male.attr("checked") === 'checked') {
gender = 'male';
} else if (baton.form.female.attr("checked") === 'checked') {
gender = 'female';
}

baton.wizard.pageData.gender = gender;
}
});

// Anything above a trivial form may benefit from using backbone model and view classes
point.extend({
id: 'completeUserInfo',
index: 300,
title: "Personal Information",
load: function (baton) {
// The load method is an optional method. It is called to load data that you
// need to set up the page
// And it is called as soon as the page is the 'next' or 'previous' page of the
// active page, so you can start loading
// even before the page shows up. Return a deferred to let the wizard framework
// know when you're done.

// We will fetch the user data for our example.
var def = $.Deferred();

require(["io.ox/core/api/user", "io.ox/backbone/basicModel", "io.ox/backbone/mini-views"], function (userAPI, Model, mini) {
// Alright, let's stick the APIs into our baton, we'll need these later
// This is also a nice little trick for loading APIs in the wizard framework.
baton.libraries = {
userAPI: userAPI,
mini: mini
};

// And let's load the current user

userAPI.getCurrentUser().done(function (user) {
// Note, that this is a backbone model
// We could turn this into a model by instantiating a BasicModel, otherwise.
baton.user = user;

// We want to enable the next button on this page based on whether a first
// an last name is set, so, let's listen for the change events on the user object
function updateButtonState() {
if (!_.isEmpty(user.get("first_name")) && !_.isEmpty(user.get("last_name"))) {
baton.buttons.enableNext();
} else {
baton.buttons.disableNext();
}
}
baton.user.on('change', updateButtonState);

updateButtonState();

// And we're done
def.resolve();
}).fail(def.reject);
});

return def;
},

draw: function (baton) {
// Now, for fun, let's try and build a backbone backed form
// Depending on the complexity of the form, this is a good route to take
// I would, however, also suggest to scour the appsuite source code for
// reusable parts, as they will usually be internationalized, localized,
// responsive to different devices and accessible. Depending on the use of this
// wizard, you'll have to take care of these aspects yourself.

// Firstly some fun, though. Why not have this wizard be flirtatious, since it's just
// getting to know the user. Personally, I think software would do well to be more
// flirtatious, but I'm just a lonely developer, so YMMV
if (baton.wizard.pageData.gender && baton.wizard.pageData.gender === 'male') {
this.append($("<p>").text("So, who are you, handsome?"));
} else if (baton.wizard.pageData.gender && baton.wizard.pageData.gender === 'female') {
this.append($("<p>").text("So, who are you, beautiful?"));
} else {
this.append($("<p>").text("So, who are you, stranger?"));
}

// Now, on to the serious business
var mini = baton.libraries.mini;

this.append(
$('<form class="form-horizontal" />').append(
$('<div class="control-group" />').append(
$('<label class="control-label" for="first_name" />').text("First Name"), // Don't forget i18n in your own wizard!
$('<div class="controls" />').append(
new mini.InputView({name: 'first_name', model: baton.user}).render().$el
)
),
$('<div class="control-group" />').append(
$('<label class="control-label" for="last_name" />').text("Last Name"), // Don't forget i18n in your own wizard!
$('<div class="controls" />').append(
new mini.InputView({name: 'last_name', model: baton.user}).render().$el
)
)
)
);

},

finish: function (baton) {
// Depending on the capabilities of the model, this could be more complicated
// you might have to interrogate the model for the #changedAttributes
// and call an API method. In any case, finish may return a deferred object
// to denote the state of the save operation
return baton.user.save();
}
});

// If you want to provide your own navigation controls in the page
// (useful for a simple choice), you can get rid of the default buttons
// of the dialog, but have to then call baton.wizard.next or baton.wizard.prev
// or baton.wizard.goToPage(pageNumberOrID) manually.

point.extend({
id: 'spamMe',
index: 400,
title: "Special Offers",
hideButtons: 'true',
draw: function (baton) {
this.append(
$('<div />').text("Would you like to be informed of special offers from time to time?"),
"<br />",
$('<div />').append(
$('<button class="btn btn-primary" />').text("Yes! Send me information about special offers").on("click", function () {
baton.specialOffers = true;
baton.buttons.enableNext();
baton.wizard.next();
})
),
"<br />",
$('<div />').append(
$('<button class="btn" />').text("No, thanks").on("click", function () {
baton.specialOffers = false;
baton.buttons.enableNext();
baton.wizard.next();
})
)
);
},

finish: function (baton) {
// Save baton.specialOffers preference
console.log(baton.specialOffers);
}
});

point.extend({
id: 'byebye',
index: 500,
title: "Thank you!",
draw: function (baton) {
this.append($("<p>").text("Thank you for completing our welcome wizard! Be sure to tell us what you like and what we could improve in App Suite!"));
baton.buttons.enableNext();
}
});

// To enable the wizard to run upon startup, you have to use the extension system to add a new
// stage to the boot process.
// Use a manifest.json to extend the core/main file:
// {
// namespace: 'io.ox/core/main'
// }

// Then, in the plugins file, define a new stage that runs the wizard after the curtain has
// been drawn back:

/*
define('...', ['io.ox/core/extPatterns/stage'], function (Stage) {
'use strict';

new Stage('io.ox/core/stages', {
id: 'welcome-wizard',
after: 'curtain',
run: function (baton) {
var def = $.Deferred();
//TODO: Check a JSLob if the wizard needs to be run, or has been cleared successfully
// If it has to be run, require the wizards source file and trigger the wizard
require(["io.ox/dev/wizard/welcomeWizard"], function (w) {
w.getInstance().start().done(function () {
//TODO: Mark this wizard as passed, so as not to start it again
// Resolve the deferred, so the next stage can start
def.resolve();
}).fail(def.reject);
});

return def;
}
});

});

*/
return {
getInstance: function () {
// Create a new instance of the wizard. Note that the id of the wizard determines
// the extension point
// that pages have to extend
return wizards.getWizard({id: 'io.ox/dev/wizard/welcomeWizard', closeable: true});
}
};
});
</syntaxhighlight>

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

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

AppSuite:BackboneMiniViews

2016-02-10T06:51:17Z

Frank.paczynski:

<div class="title">Backbone mini views</div>

'''Abstract'''

''Mini views are small backbone views which helps you to create single form elements like input fields, checkbox and so on. They should be used to build form pages in a DRY way.
To use the mini-views simply require io.ox/backbone/mini-views in your view pane.''

==Benefits of using mini-views==
* automatic cleanup (model & events) if the form element is removed from the DOM
* the wiring between form element and model data is handled for each mini-view via attribute name or id of the element
* DRY

==Abstract view==
The abstract view is used to manage the dispose feature for all mini-views.

==Common mini-views==
All mini-views provides functions for handling the common interactions between model data and form element like initial setup, update and rendering.
To provide some basic a11y the tabindex is set by default to 1 and can be changed via this.options.tabindex to every needed value.

The 'id' option should be used to connect the view with the model data and render an id attribute. This can be used to connect with a label which is not surrounding the form field.

==List of form-elements included==

===InputView===
It draws a simple input form field.

Usage
<pre class="language-javascript">
new InputView({ id: [attribute], model: [model] }).render().$el
</pre>

It renders the following markup:
<pre class="language-javascript">
<input type="text" id="text" class="form-control" name="text" tabindex="1">
</pre>

===PasswordView===
It draws a simple password form field.

Usage
<pre class="language-javascript">
new PasswordView({ name: [attribute], model: [model] }).render().$el
</pre>

It renders the following markup:
<pre class="language-javascript">
<input type="password" id="password" class="form-control" autocomplete="off" autocorrect="off" name="password" tabindex="1">
</pre>

If no password value is provided via model the field value is changed to „'********“. This especially is needed since already provided passwords are not delivered via the api request. The attributes „autocomplete" and „autocorrect“ are set to „off“ by default.

===TextView===
It draws a simple textarea form field.

Usage
<pre class="language-javascript">
new TextView({ name: [attribute], model: [model], rows: [rowcount] }).render().$el
</pre>

It renders the following markup:
<pre class="language-javascript">
<textarea id="textarea" class="form-control" name="textarea" tabindex="1" rows="4"></textarea>
</pre>

Use this.rows to set the row attribute of the area to the needed value.

===CheckboxView===
It draws a simple checkbox form field.

Usage
<pre class="language-javascript">
new CheckboxView({ name: [attribute], model: [model] }).render().$el
</pre>

It renders the following markup:
<pre class="language-javascript">
<input type="checkbox" id="checkbox" name="checkbox" tabindex="1">
</pre>

===RadioView===
It draws a simple radio form field.

Usage
<pre class="language-javascript">
new RadioView({ name: [attribute], model: [model], list: [radioOptions] }).render().$el
</pre>

Use this.options.list to set the list of available options and labels.

<pre class="language-javascript">
var radioOptions = var options = [
{ label: '1', value: '1'},
{ label: '2', value: '2'},
{ label: '3', value: '3'}
];
</pre>

It renders the following markup:
<pre class="language-javascript">
<div id="radio" class="controls">
<div class="radio">
<label><input type="radio" name="radio" value="1" tabindex="1">1</label>
</div>
<div class="radio">
<label><input type="radio" name="radio" value="2" tabindex="1">2</label>
</div>
<div class="radio">
<label><input type="radio" name="radio" value="3" tabindex="1">3</label>
</div>
</div>
</pre>

===SelectView===
It draws a simple select form field.

Usage
<pre class="language-javascript">
new SelectView({ name: [attribute], model: [model], list: [selectOptions] }).render().$el
</pre>

Use this.options.list to set the list of available options and labels.
<pre class="language-javascript">
var selectOptions = var options = [
{ label: '1', value: '1'},
{ label: '2', value: '2'},
{ label: '3', value: '3'}
];
</pre>

It renders the following markup:
<pre class="language-javascript">
<select id="select" class="input-xlarge form-control" name="select" tabindex="1">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
</select>
</pre>

===ErrorView===
{{VersionFrom|7.6.1}}

It draws a span with the class "help-block" to display error messages in case of a validation fault.
<pre class="language-javascript">
<span class="help-block" aria-live="assertive" style="display: none;"></span>
</pre>

Usage

It always should be placed beneath the corresponding form field.
<pre class="language-javascript">
new ErrorView({ selector: [css selector] }).render().$el;
</pre>

The 'selector' option is used to connect the ErrorView with an custom surrounding container for the ErrorView and the related form field. It returns the closest matching container. This container is used by the ErrorView to listen to the 'valid/invalid' events triggered by the validation.

The default selector returns the closest matching '.form-group' or '[class*="col-"]' container.

===FormView===
{{VersionFrom|7.6.1}}

It draws a simple form element.
As a miniview, it automatically cleans up the connected model & events.
<pre class="language-javascript">
<form></form>
</pre>

<pre class="language-javascript">
new FormView({ model: [model] }).render().$el;
</pre>

===DateView===

It draws a set of 'select' form fields to display and edit a date.
Day, month and year will each be represented by a single <select> item.
<pre class="language-javascript">
new DateView({ name: [attribute], model: [model] }).render().$el
</pre>

It renders the following markup:
<pre class="language-javascript">
<div id="date" class="native-date-picker row">
<div class="col-xs-3 col-sm-3 col-md-3 col-lg-3">
<select tabindex="1" name="date" title="Tag" class="form-control date">
<option value=""></option>
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
*
*
*
<option value="29">29</option>
<option value="30">30</option>
<option value="31" disabled="">31</option>
</select>
</div>
<div class="col-xs-5 col-sm-5 col-md-5 col-lg-5">
<select tabindex="1" name="month" title="Monat" class="form-control month">
<option value=""></option>
<option value="0">Januar</option>
<option value="1">Februar</option>
*
*
*
<option value="10">November</option>
<option value="11">Dezember</option>
</select>
</div>
<div class="col-xs-4 col-sm-4 col-md-4 col-lg-4">
<select tabindex="1" name="year" title="Jahr" class="form-control year">
<option value="0001"></option>
<option value="2014">2014</option>
<option value="2013">2013</option>
<option value="2012">2012</option>
*
*
*
<option value="1866">1866</option>
<option value="1865">1865</option>
<option value="1864">1864</option>
</select>
</div>
</div>
</pre>

===Dropdown===
The Dropdown mini view provides an easy solution to create a drop down.
Multiple settings and / or links may be provided to the user in a single drop-down view.
To use the dropdown mini view simply require io.ox/backbone/mini-views/dropdown in your view pane.

Use this.option to fill the drop down with a single selectable option.<br>
arguments: [attribute], [value], [text used for labeling]

Use this.link to provide a simple link with a callback.<br>
arguments: [value for attribute "data-name"], [text for link], [callback]

Use this.header to build logical groups in the drop down while setting headers between the options.<br>
arguments: [text for header]

Use this.divider to provide a visual devider between groups.

<pre class="language-javascript">
var dropdown = new Dropdown({ model: model, label: gt('Dropdown'), tagName: 'li' })
.header(gt('Options'))
.option('options', 'firstOption', gt('first option'))
.option('options', 'secondOption', gt('second option'))
.divider()
.header(gt('Choices'))
.option(‚'choice', 'firstChoice', gt('first choice'))
.option('choice', 'secondChoice', gt('second choice'))
.divider()
.link('link', gt('link'), function () { console.log('clicked'); }
);

dropdown.render().$el;
</pre>

It renders the following markup:
<pre class="language-javascript">
<li class="dropdown">
<a href="#" tabindex="1" role="menuitem" aria-haspopup="true" aria-label="" data-toggle="dropdown" aria-expanded="false">
<span class="dropdown-label">Dropdown</span>
</a>
<ul class="dropdown-menu" role="menu">
<li class="dropdown-header" role="presentation" aria-hidden="true">Options</li>
<li role="presentation">
<a href="#" role="menuitemcheckbox" aria-checked="true" data-name="dropdownOptions" data-value="firstOption" data-toggle="false">
<i class="fa fa-fw fa-check" aria-hidden="true"></i>
<span>first option</span>
</a>
</li>
<li role="presentation">
<a href="#" role="menuitemcheckbox" aria-checked="false" data-name="dropdownOptions" data-value="secondOption" data-toggle="false">
<i class="fa fa-fw fa-none" aria-hidden="true"></i>
<span>second option</span>
</a>
</li>
<li class="divider" role="presentation"></li>
<li class="dropdown-header" role="presentation" aria-hidden="true">Choices</li>
<li role="presentation">
<a href="#" role="menuitemcheckbox" aria-checked="true" data-name="dropdownChoice" data-value="firstChoice" data-toggle="false">
<i class="fa fa-fw fa-check" aria-hidden="true"></i>
<span>first choice</span>
</a>
</li>
<li role="presentation">
<a href="#" role="menuitemcheckbox" aria-checked="false" data-name="dropdownChoice" data-value="secondChoice" data-toggle="false">
<i class="fa fa-fw fa-none" aria-hidden="true"></i>
<span>second choice</span>
</a>
</li>
<li class="divider" role="presentation"></li>
<li role="presentation">
<a href="#" role="menuitem" tabindex="-1">link</a>
</li>
</ul>
</li>
</pre>

===Dropdown Link===
It draws a link which opens a dropdown. The link text always shows the selected option.

Usage
<pre class="language-javascript">
new DropdownLinkView({ name: [attribute], model: [model], values: [dropdownOptions] }).render().$el
</pre>

Use this.options.values to set the list of available values and labels.
<pre class="language-javascript">
var dropdownOptions = {
'value1': 'Dropdownlink 1',
'value2': 'Dropdownlink 2',
'value3': 'Dropdownlink 3'
};
</pre>

It renders the following markup:
<pre class="language-javascript">
<div class="dropdownlink">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="menuitem" aria-haspopup="true" tabindex="1">label1</a>
<ul class="dropdown-menu" role="menu">
<li><a href="#" data-action="change-value" data-value="value1" tabindex="1">Dropdownlink 1</a></li>
<li><a href="#" data-action="change-value" data-value="value2" tabindex="1">Dropdownlink 2</a></li>
<li><a href="#" data-action="change-value" data-value="value3" tabindex="1">Dropdownlink 3</a></li>
</ul>
</div>
</pre>

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

==Playground==
Simply copy/paste the code beneath in to your browser console while being logged in. This creates an playground for the mentioned mini views.

<pre class="language-javascript">
require(['io.ox/backbone/mini-views', 'io.ox/backbone/mini-views/dropdown'], function(mini, Dropdown) {

var model = window.model = new Backbone.Model({
text: 'text',
radio: '1',
password: 'password',
textarea: 'textarea',
checkbox: true,
select: '1',
date: 1411023212550,
dropdownOptions: 'firstOption',
dropdownChoice: 'firstChoice',
dropdownLink: 'value1'
});

var form = new mini.FormView({ model: model });

// use listenTo to benefit from automatic clean-up
form.listenTo(model, 'change', function () {
console.log(this.model.toJSON());
});

var options = [
{ label: '1', value: '1'},
{ label: '2', value: '2'},
{ label: '3', value: '3'}
];

var dropdownOptions = {
'value1': 'Dropdownlink 1',
'value2': 'Dropdownlink 2',
'value3': 'Dropdownlink 3'
};

var dropdown = new Dropdown({ model: model, label: 'Dropdown' })
.header('Options')
.option('dropdownOptions', 'firstOption', 'first option')
.option('dropdownOptions', 'secondOption', 'second option')
.divider()
.header('Choices')
.option('dropdownChoice', 'firstChoice', 'first choice')
.option('dropdownChoice', 'secondChoice', 'second choice')
.divider()
.link('link', 'link', function () { console.log('clicked'); }
);

form.$el.append(
$('<fieldset>').append(
$('<div class="row form-group">').append(
$('<label for="text" class="control-label col-sm-4">').text('Text'),
$('<div class="col-sm-8">').append(
new mini.InputView({ id: 'text', model: model }).render().$el
)
),
$('<div class="row form-group">').append(
$('<div class="col-sm-8 col-sm-offset-4">').append(
dropdown.render().$el
)
),
$('<div class="row form-group">').append(
$('<label class="control-label col-sm-4">').text('Radio'),
$('<div class="col-sm-8">').append(
new mini.RadioView({
list: options,
id: 'radio',
model: model
}).render().$el
)
),
$('<div class="row form-group">').append(
$('<label for="password" class="control-label col-sm-4">').text('Password'),
$('<div class="col-sm-8">').append(
new mini.PasswordView({ id: 'password', model: model }).render().$el,
new mini.ErrorView({ selector: '.row' }).render().$el
)
),
$('<div class="row form-group">').append(
$('<label for="textarea" class="control-label col-sm-4">').text('Textarea'),
$('<div class="col-sm-8">').append(
new mini.TextView({ id: 'textarea', rows: '4', model: model }).render().$el
)
),
$('<div class="row form-group">').append(
$('<div class="col-sm-8 col-sm-offset-4">').append(
$('<label class="checkbox">').append(
new mini.CheckboxView({ id: 'checkbox', model: model }).render().$el,
document.createTextNode('Checkbox')
)
)
),
$('<div class="row form-group">').append(
$('<label for="select" class="control-label col-sm-4">').text('Select'),
$('<div class="col-sm-8">').append(
new mini.SelectView({
list: options,
id: 'select',
model: model
}).render().$el
)
),
$('<div class="row form-group">').append(
$('<label class="control-label col-sm-4">').text('Date'),
$('<div class="col-sm-8">').append(
new mini.DateView({ id: 'date', model: model }).render().$el,
new mini.ErrorView({ selector: '.row' }).render().$el
)
),
$('<div class="row form-group">').append(
$('<div class="col-sm-8 col-sm-offset-4">').append(
new mini.DropdownLinkView({ id: 'dropdownLink', model: model, values: dropdownOptions }).render().$el
)
)
)
);

// add button to close playground
form.$el.prepend(
button = $('<button type="button" class="close">').append(
$('<span aria-hidden="true">×</span><span class="sr-only">Close</span>')
)
.css({
position: 'absolute',
top: '4px',
right: '8px',
margin: '3px'
})
.on('click', function () {
form.remove();
})
);

form.$el.css({
position: 'absolute',
top: 0,
right: 0,
bottom: 0,
width: '50%',
padding: '40px',
backgroundColor: '#fff',
boxShadow: '0 0 30px #888',
zIndex: 11,
overflowX: 'hidden',
overflowY: 'auto'
});

$('body').append(form.render().$el);
});
</pre>

You can copy/paste the following examples in your browser console to make changes to the data in the playground.

- to modify values via console
<pre class="language-javascript">
window.model.set('password', 'new password');
// window.model.set([attribute], [new value]);
</pre>

- to trigger an validation fault
<pre class="language-javascript">
window.model.trigger('invalid:password', 'something is wrong here');
// window.model.trigger('invalid:' + [attribute], [Error Message]);
</pre>

- to remove an validation fault
<pre class="language-javascript">
window.model.trigger('valid:password');
// window.model.trigger('valid:' + [attribute]);
</pre>

AppSuite:Action links

2016-02-10T06:29:37Z

Frank.paczynski:

{{Stability-experimental}}

<div class="status-disclaimer">
'''Please note:'''
This page is currently under construction. It might change any minute now.
</div>

<div class="title">Understanding action links</div>

Action links can be used to apply an action to an item or even a selection of items. Use them to extend actions for existing items or create a toolbox for your custom items available in your [[Appsuite:Writing a simple application|application]].

= The API =

== Action ==

Creating a new action is pretty straight forward. Just create a new Action and give it a unique name (internally we use slashes to indicate a module hierarchy, so names are inherently unique) and provide a few options.

<pre class="language-javascript">
var action = new Action('unique/name/of/my/action', {
//some options go in here
});
</pre>

=== Available options ===

In the options parameter you can provide the actual logic for the action. You can provide callbacks, requirements and more.

* id
** a unique identifier (String)
* requires (optional)
** (String) - a String containing one or more special keywords that are required for this action to be active
*** toplevel
*** one
*** some
*** delete
*** …
** (Function) - a function that returns a Boolean value and gets a Baton object as parameter
* multiple (optional)
** (Function) - a callback function, called when the action is triggered with a list of elements
* action (optional)
** (Function) - a callback function, called when the action is triggered for one element

== ActionLink ==

== ActionGroup ==

== Link ==

== XLink ==

== Button ==

== ButtonGroup ==

== ToolbarButtons ==

== ToolbarLinks ==

== InlineLinks ==

== DropdownLinks ==

== Dropdown ==

= Examples =

AppSuite:Guided tours

2016-02-10T06:21:52Z

Frank.paczynski:

'''Synopsis:''' Guided tours are series of little steps meant to explain the various functions of OX to an end user. They can be configured by system administrators.

__TOC__

== Basic framework ==
Guided tours are built on [https://github.com/linkedin/hopscotch LinkedIn's hopscotch.js] framework. It forms a series of small information "bubbles" that point to UI elements and display a text as well as small navigation elements.

== State before 7.4.1 ==
In 7.4.0, Guided Tours could not be configured.

== State after 7.4.1 ==
=== Package ===
Guided tours are contained in a separate package, named ''open-xchange-guidedtours''. This will install UI as well as backend components (in the form of a config file).

=== Configuration ===
Several configuration parameters guide the running of Guided Tours:

{|
|io.ox/tours//server/disableTours
|Disabled the tours completely
|-
|io.ox/tours//server/disable/$moduleName
| Disables the tour for a specific module, e.g. "io.ox/tasks"
|-
| io.ox/tours//server/startOnFirstLogin
| start the tour the first time a user logs in
|-
|io.ox/tours//server/version
|arbitrary integer denoting the version of the tour. If startOnFirstLogin is true, the user might have seen a previous version but not the recent one. Increasing the number makes sure the users sees the updated version again.
|}

=== Customizing ===
Tours use [[AppSuite:Extension points|extension points]] as mechanism to extend them. The relevant point is ''io.ox/tours/extensions''.

==== Example tour ====
A tours looks like this:
ext.point('io.ox/tours/extensions').extend({
id: 'default/io.ox/intro',
app: 'io.ox/intro',
priority: 1,
tour: {
id: 'Switching from OX6',
steps: [{
title: gt('Launching an app'),
placement: 'bottom',
target: function () { return $('.launcher[data-app-name="io.ox/mail"]')[0]; },
content: gt('To launch an app, click on an entry on the top-left side of the menu bar.')
},
{
onShow: function () { notifications.hideList(); },
title: gt('Displaying the help or the settings'),
placement: 'left',
target: function () { return $('.launcher .icon-cog:visible')[0]; },
content: gt('To display the help or the settings, use the icons on the right side of the menu bar.'),
arrowOffset: 1,
yOffset: -5
},
{
onShow: function () { notifications.showList(); },
title: gt('New objects icon'),
placement: 'left',
target: function () { return $('#io-ox-notifications-icon:visible')[0]; },
content: gt('The New objects icon shows the number of unread E-Mails or other notifications. If clicking the icon, the info area opens.'),
arrowOffset: -1
}, [...]

==== Components of a tour ====
A tours is a set of steps that are can be navigated by going forward and backwards. It needs...
{|
| id
| This needs to be unique, like for all extension points. Even if you want to overwrite another tour, you need a different id!
|-
| app
| The application this tour is related to.
|-
| Priority
| The tour with the largest number for the priority for a specific app is the one shown. This is how you overwrite an existing tour with your custom one.
|-
| tour
| The steps of a tour
|}

==== Tour steps ====
A tour step is a text bubble that is shown next to a UI element. It needs...
{|
| title
| This needs to be unique, like for all extension points. Even if you want to overwrite another tour, you need a different id!
|-
| target
| The UI element this text bubble is displayed next to. Hopscotch only allows identifiers as passed to JQuery, but App Suite extends this to functions. Most functions used simply return JQuery identifiers, the difference is when it is resolved: Functions are resolved later, which is helpful if your application is built by doing DOM manipulations as late as possible - App Suite is.
|-
| content
| The content of a text bubble. Can be html, as it uses the innerHtml method of JQuery to attach itself.
|-
| placement
| Where the text bubble is placed in relation to the UI element. Possible values are "top", "bottom", "left" and "right"
|-
| xOffset
| Passed directly to hopscotch. Moves the box horizontally relative to its standard position.
|-
| yOffset
| Passed directly to hopscotch. Moves the box vertically relative to its standard position.
|-
| arrowOffset
| Passed directly to hopscotch. Moves the arrow relative to its standard position, horizontally if the bubble is placed "top" or "bottom", vertically if "left" or "right".
|-
| onShow
| Passed directly to hopscotch. A function that is executed when the bubble is shown.
|-
| onShowDeferred
| A workaround for onShow: This waits for the deferred to be resolved before showing the bubble.
|}

And that is all there is to creating a tour.

[[Category:UI]]
[[Category:Administrator]]
[[Category:Developer]]
[[Category:Custom development]]