Open-Xchange - User contributions [en]

AppSuite:OX Drive

2016-06-20T18:18:32Z

Matthias.biggeleben: /* 7.8.1 and later */

= OX Drive =

In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the app setup.

== Key features ==

* Native Apps for Windows, Mac OS, iOS and Android
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)
* Apps are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.
* Controlled synchronization of files across devices
* Storage management (e.g. quota control, upload limits)
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)

== Availability ==

OX Drive is a combination of two components:
* OX Drive in OX App Suite
* OX Drive Apps (optional native app components for synchronization)

OX Drive is available for the following native apps:
* OX Drive for Windows
* OX Drive for Mac OS
* OX Drive for iOS
* OX Drive for Android

== Requirements ==

You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive App and Platform Requirements]]

= Server-side Installation and Configuration =

This chapter describes how the backend components of OX Drive are installed and configured on the server.

== Prerequisites ==

* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details

== Available packages ==

Open-Xchange Drive is available with the following backend packages:

* ''open-xchange-drive'' - The main server components for OX Drive
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop apps
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== OX Drive for Windows ===

Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.8.0 and earlier releases and 7.8.1 and later ones:

==== 7.8.0 and earlier ====

OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then. You don't have to add the repositories below.

==== 7.8.1 and later ====

With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the app is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onboarding|App Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:

* ''open-xchange-drive-client-windows'' - The main server component to provide the app
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.

To make the app download available via the app onboarding wizard, you need to enable the according scenario. Edit ''/opt/open-xchange/etc/client-onboarding-scenarios.yml'' and get to the ''drivewindowsclientinstall'' section, where you have to set the ''enabled'' property to ''true''.

Please note that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the apps out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.

===== Custom branded apps =====

OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.

It is also possible to provide multiple brands of the app via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.

App brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ yum update
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ yum update
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Debian GNU/Linux 7.0 ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Debian GNU/Linux 8.0 ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}
and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ zypper ref
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ zypper ref
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== OX Server Edition / App Suite for UCS ===

If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.

* The new license is already registered at the LDB after purchase.
* Log on at the Univention Management Console (UMC)
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"
* Within the component list, select "Open-Xchange Drive" and press the "Install" button

== Configuration ==

The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the apps.

All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based app notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options.

=== Push via Google Cloud Messaging (GCM) ===

The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android app application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android app. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:

# Specifies the API key of the server application. Required if
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.gcm.key=

Push via GCM can be enabled via:

# Enables or disables push event notifications to apps using the Google
# Cloud Messaging (GCM) service. This requires a valid configuration for the
# GCM API key, see options below. Defaults to "false".
com.openexchange.drive.events.gcm.enabled=true

Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.

=== Push via Apple Push Notification service (APNs) ===

The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop app and the iOS mobile app are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS app applications. Therefore no additional configuration is needed. Alternatively, a external certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:

# Specifies the path to the local keystore file (PKCS #12) containing the APNS
# certificate and keys for the iOS application, e.g.
# "/opt/open-xchange/etc/drive-apns.p12". Required if
# "com.openexchange.drive.events.apn.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.apn.ios.keystore=

This file is opened by the backend using the password as supplied via:

# Specifies the password used when creating the referenced keystore containing
# the certificate of the iOS application. Note that blank or null passwords
# are in violation of the PKCS #12 specifications. Required if
# "com.openexchange.drive.events.apn.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.apn.ios.password=

Configuration also allows to switch between development and production environments, however, this setting should be ''true'' normally:

# Indicates which APNS service is used when sending push notifications to iOS
# devices. A value of "true" will use the production service, a value of
# "false" the sandbox service. Defaults to "true".
com.openexchange.drive.events.apn.ios.production=true

The OX backend contacts the APNs servers from time to time to get informed about apps no longer reachable apps where the applications was uninstalled. The interval can be defined with the following setting:

# Configures the interval between queries to the APN feedback service for the
# subscribed iOS devices. The value can be defined using units of measurement:
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day).
# Leaving this parameter empty disables the feedback queries on this node.
# Since each received feedback is processed cluster-wide, only one node in the
# cluster should be enabled here.
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D

Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:

# Enables or disables push event notifications to apps using the Apple Push
# Notification service (APNS) for Mac OS devices. This requires a valid
# configuration for the APNS certificate and keys, see either options below,
# or install the restricted components packages for drive. Defaults to
# "false".
com.openexchange.drive.events.apn.ios.enabled=false

As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.

=== Further Configuration ===

* The backend component of OX Drive supplies the apps with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop apps. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.

= Enabling OX Drive for Users =

OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:

# Enables or disables the "drive" module capability globally. The capability
# can also be set more fine-grained via config cascade. Per default it is only
# enabled for users that have the "infostore" permission set. This is configured
# in /opt/open-xchange/etc/contextSets/drive.yml.
com.openexchange.capability.drive=false

More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].

= Installation of the Apps =

== Installation of Mac OS X Desktop App ==

The OX Drive for Mac OS X will be provided via the Apple App Store:

* https://itunes.apple.com/app/ox-drive/id818195014?mt=12

=== Enabling the Finder Extension on Mac OS X ===

In order to be able to use the Finder to open documents or share objects on a Mac OS X workstation, you need to enable the Drive Finder Extension.

How to enable the Drive Finder Extension on a Mac OS X workstation:
# Open the System Preferences. In the System Preferences window, select Extensions.
# In the Extensions window, select Finder. Enable Drive Finder Extension.

== Installation of Windows Desktop App ==

See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].

== Installation on Mobile Apps ==

The OX Drive App is available via the different App Stores:

* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8

* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla

== App Configuration and Deployment ==

The user needs to enter the server URL and provide his username and password. Afterwards, app-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation.

After the initial synchronization is completed, all further changes are synchronized instantly across all devices.

= FAQ =

You will find it under [http://knowledgebase.open-xchange.com/sales-marketing/additional-software/frequently-asked-questions/ox-drive-for-clients.html OX Drive App and Platform FAQ].

Portal:AppSuite UI/Topics

2016-06-20T18:17:14Z

Matthias.biggeleben: Fixed typo

== Getting started ==
* [[AppSuite:GettingStarted | Getting started developing an external app]]
* [[AppSuite:Upgrade_app_using_yo | Upgrade your external app to latest App Suite version]]
* [[AppSuite:UI developer primer| Skills needed to develop the UI]]
* [[AppSuite:Getting started developing the UI | Getting started developing the UI]]
* [[AppSuite:UI_Development_Style_Guide | UI Development Style Guide]]
* [[AppSuite:Appserver | Appserver]]
* [[AppSuite:Apache Configuration | Apache Configuration]]
* [[AppSuite:Definition of done|Definition of done]]
* [[Appsuite:UI_FAQ | Frequently asked questions]]

== Upgrading apps, plugins, and themes to 7.6 ==
* [[AppSuite:Upgrading_to_7_6|Upgrading to 7.6]]

== Testing ==
* [[AppSuite:Test basics | Lessons learned while testing]]
* [[AppSuite:RunTests | Running ui tests]]
* [[AppSuite:Testing_3rd-party_code | In-depth article on testing]] aimed at external developers

== How-to articles ==
* [[AppSuite:Action links|Understanding action links]]
** [[AppSuite:Files App Actions|Adding actions to the files app]]
* [[AppSuite:Date_and_time|Date and time]]
* [[AppSuite:i18n | Internationalization (i18n)]]
* [[AppSuite:a11y | Accessibility (a11y)]]
* [[AppSuite:Mediaplayer | Mediaplayer]]
* [[AppSuite:Theming | Theming]]
** [[AppSuite:Dynamic Theme|The Dynamic Theme plugin]]
* [[AppSuite:UI manifests explained | UI manifests explained]]
* [[AppSuite:Upsell | Upsell]]
* [[AppSuite:VGrid | VGrid]]
* [[AppSuite:Mobile | Mobile development]]
* [[AppSuite:Upsell tools| Upsell tools]]
* [[AppSuite:Guided tours| Guided tours]]
* [[AppSuite:Browserdetection | Browser detection with form-login]]
* [[AppSuite:BackboneMiniViews | Backbone mini views]]

=== Server communication ===
* [[AppSuite:APIs | APIs]]
* [[AppSuite:API_Factory | API Factory]]
* [[AppSuite:http.js | http.js]]

=== Extension points ===
* [[AppSuite:Extending_the_UI_(Hands-on_introduction)| Hands-on introduction]]
* [[AppSuite:Extending_the_UI | General information on extension points]]
* [[AppSuite:Modifying forms by using extension points | Modifying forms]]
* [[AppSuite:Create custom folderview entries in settings app | Edit folderview entries in settings]]
* [[AppSuite:Extension points for calendar |extension points: Calendar]]
* [[AppSuite:Extension points for contact |extension points: Contact]]
* [[AppSuite:Extension points for core | extension points: Core]]
* [[AppSuite:Extension points for email | extension points: E-Mail]]
* [[AppSuite:Extension points for files |extension points: Files]]
* [[AppSuite:Extension points for tasks |extension points: Tasks]]
* [[AppSuite:Extension points for miscellaneous |extension points: Miscellaneous]]

=== Writing components ===
* [[AppSuite:Writing a portal plugin | Writing a portal plugin]]
** [[AppSuite:Configuring portal plugins|Configuring a portal plugin]]
** [[AppSuite:Using the Upsell widget|Using the Upsell widget]]
* [[AppSuite:Writing a simple application | Writing a simple application]]
* [[AppSuite:Writing a simple application with embedded iframe | Writing a simple application with embedded iframe and launcher link ]]
* [[AppSuite:Writing a notification area plugin | Writing a plugin for the notification area]]
* [[AppSuite:Writing a wizard | Writing a wizard]]
* [[AppSuite:Capabilities | Capabilities explained]] - if you want to enable or disable your plugin

== Miscellaneous articles ==
* [[AppSuite:External libraries for the UI | External libraries used by the UI]]
* [[AppSuite:Configuration| Configuration]]
* [[AppSuite:Custom configurations| Custom configurations]]
* [[AppSuite:UI build system| The UI build system]]
* [[AppSuite:Embedding your settings into AppSuite settings|How to embed your own settings into the Appsuite settings page]]
* [[AppSuite:Debugging the UI|Debugging the UI]]
* [[Appsuite:Debugging production servers|Debugging production servers]]
* [[AppSuite:Memory leaks (UI)|Finding memory leaks in the UI]]
* [[AppSuite:Device reference|_.device() reference]]
* [[AppSuite:Paste inline images|Paste inline images]]
* [[AppSuite:Client Onboarding|Client Onboarding]]
* All articles regarding the UI are filed in the category [[:Category:UI]]

AppSuite:Client Onoarding

2016-06-20T18:13:32Z

Matthias.biggeleben: Redirected page to "AppSuite:Client Onboarding"

#REDIRECT [["AppSuite:Client_Onboarding"]]

AppSuite:Client Onoarding

2016-06-20T18:10:48Z

Matthias.biggeleben: Delete

AppSuite:Embedding your settings into AppSuite settings

2016-03-08T08:57:05Z

Matthias.biggeleben: /* Declare the page you want to embed */

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

Before you start you need to know the group where you want to add the settings (since 7.8.0):
<pre>
gerneral:
Basic Settings
Accounts

main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive

tools:
Pubications and Subscriptions
Error Log
Download

external:
Groups
Resources
</pre>

Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.

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]"
group: general
title: "Change Plan"
before: "io.ox/settings/accounts"
advancedMode: false # not needed anymore for 7.8.0

''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.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools". For settings inside folders you have to use the group and the name of the config object, for example: group: main/io.ox/mail
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''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 (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)
* '''requires''': A string of capabilities. Supports boolean operators like && (AND), || (OR), ! (NOT), as well as parentheses. Example: !guest.

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:Embedding your settings into AppSuite settings

2016-03-08T08:56:34Z

Matthias.biggeleben: /* Declare the page you want to embed */

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

Before you start you need to know the group where you want to add the settings (since 7.8.0):
<pre>
gerneral:
Basic Settings
Accounts

main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive

tools:
Pubications and Subscriptions
Error Log
Download

external:
Groups
Resources
</pre>

Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.

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]"
group: general
title: "Change Plan"
before: "io.ox/settings/accounts"
advancedMode: false # not needed anymore for 7.8.0

''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.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools". For settings inside folders you have to use the group and the name of the config object, for example: group: main/io.ox/mail
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''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 (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)
* '''requires''' A string of capabilities. Supports boolean operators like && (AND), || (OR), ! (NOT), as well as parentheses. Example: !guest.

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:Embedding your settings into AppSuite settings

2016-02-12T12:10:17Z

Matthias.biggeleben: Added groups

<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.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools".
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''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.

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:Upsell

2015-11-18T12:20:33Z

Matthias.biggeleben: /* Upsell Wizard */

<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/contacts
| icon, color
| title
| carddav
| This trigger is located below the folderview of the address book.
|-
| folderview/calendar
| icon, color
| title
| caldav
| This trigger is located below the folderview of the calendar.
|-
| 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

2015-11-18T12:15:15Z

Matthias.biggeleben: /* Upsell Wizard */

<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/contacts
| icon, color
| title
| carddav
| This trigger is located below the folderview of the address book.
|-
| folderview/calendar
| icon, color
| title
| caldav
| This trigger is located below the folderview of the calendar.
|-
| 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 [http://oxpedia.org/wiki/index.php?title=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

2015-11-18T12:14:30Z

Matthias.biggeleben: /* Upsell Wizard */

<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/contacts
| icon, color
| title
| carddav
| This trigger is located below the folderview of the address book.
|-
| folderview/calendar
| icon, color
| title
| caldav
| This trigger is located below the folderview of the calendar.
|-
| 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 [[http://oxpedia.org/wiki/index.php?title=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

2015-11-18T12:08:10Z

Matthias.biggeleben: /* Upsell Wizard */

<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/contacts
| icon, color
| title
| carddav
| This trigger is located below the folderview of the address book.
|-
| folderview/calendar
| icon, color
| title
| caldav
| This trigger is located below the folderview of the calendar.
|-
| 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>
Hosters 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 [[AppSuite:UI_manifests_explained#Loading_custom_manifest_during_development|enable]] ''plugins/upsell/simple-wizard'', i.e. add the capability '''simple-wizard'''. 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:Writing a notification area plugin

2015-09-10T08:22:48Z

Matthias.biggeleben:

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

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

__TOC__

Lorem ipsum ...

AppSuite:Writing a notification area plugin

2015-09-10T08:22:11Z

Matthias.biggeleben:

Hallo Welt

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

2015-09-10T08:21:28Z

Matthias.biggeleben:

{{Stability-experimental}}

<div class="title">Writing a plugin for the notification area (7.6.x)</div>

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

__TOC__

==Preparations==

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

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

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

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

'use strict';

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

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

===Manifests===

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

<pre class="language-javascript">

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

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

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

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

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

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

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

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

===Creating the View===

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

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

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

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

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

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

==First testing==

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

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

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

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

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

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

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

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

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

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

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

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

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

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

===Listen for events===

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

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

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

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

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which, in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

== 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:Writing a notification area plugin

2015-09-10T08:20:48Z

Matthias.biggeleben: Matthias.biggeleben moved page AppSuite:Writing a notification area plugin to AppSuite:Writing a notification area plugin (7.6.x): Deprecated

#REDIRECT [[AppSuite:Writing a notification area plugin (7.6.x)]]

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

2015-09-10T08:20:47Z

Matthias.biggeleben: Matthias.biggeleben moved page AppSuite:Writing a notification area plugin to AppSuite:Writing a notification area plugin (7.6.x): Deprecated

{{Stability-experimental}}

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

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

__TOC__

==Preparations==

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

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

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

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

'use strict';

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

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

===Manifests===

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

<pre class="language-javascript">

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

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

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

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

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

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

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

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

===Creating the View===

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

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

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

//events from our items
events: {
},

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

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

===Adding the headline===

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

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

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

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

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

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

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

==First testing==

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

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

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

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

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

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

[[Image: header.png]]

Well done now we need to add some real notifications.

==Adding Notifications==

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

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

Our dummy looks like this:

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

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

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

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

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

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

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

===Listen for events===

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

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

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

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

<pre class="language-javascript">
//loop over collection and draw
this.collection.each(function (model) {
baton = ext.Baton({ model: model, view: this });
ext.point('io.ox/core/notifications/tutorial/item')
.invoke('draw', this.$('.notifications'), baton);//draw the item
}, this);
</pre>

This time we draw in the container div we created by our header drawing method.
Next we extend our extension point to draw the actual notification items.

In our example it looks like this:

<pre class="language-javascript">
//draw a single notification item
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
)
);
}
});
</pre>

As you can see we add div with the classes tutorial and item and give it the attribute ''data-cid'' which we fill with our models cid or your custom id from the models attributes for later identification.
After that we add a node and fill it with the title text of our model.

Open up your Appsuite and check if everything works. Be sure to load the custom manifests if needed.
It should look like this:

[[Image: notifications.png]]

==Adding functionality==
===Adding a Sidepopup===

A notification without functions is a bit boring, so lets add some action to them by opening a sidepopup and draw the description in it.

Change your views events so it looks like this.

<pre class="language-javascript">
//events from our items
events: {
'click .item': 'openPopup',
},
</pre>

This calls the ''openPopup'' function of our view if you click on a div with the class item, which, in this case, are our notifications.
We will create the ''openPopup'' function now, add this function to your view:

<pre class="language-javascript">
//the action for our sidepopup
openPopup: function (e) {

var overlay = $('#io-ox-notifications-overlay'),//the overlay we draw our sidepopup in
cid = $(e.currentTarget).attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

require(['io.ox/core/tk/dialogs'], function (dialogs) {//require dialogs
//create the popup
new dialogs.SidePopup({ arrow: false, side: 'right' })
.setTarget(overlay)
.show(e, function (popup) {
//fill it with our data
popup.append($('<div>').text(model.get('title')),
$('<br>'),
$('<div>').text(model.get('description')));
});
});
}
</pre>

First we define some variables. ''overlay'' is the div we append our popup to, ''cid'' is the cid we added as an attribute to our notification div earlier and ''model'' is the model we get from our collection by this cid.
After this we require our ''dialogs'' plugin and create a new sidepopup. The target we draw it on is the overlay we grabbed earlier.
In the show method we draw the contents of our popup. In this case its the models title variable and description variable.

Time to check if it works. In the appsuite your notifications should now open a sidepopup if you click on them.

===Add a remove option===
We don't want our notifications to stay there forever, so we need a way to remove them.
Let's add a button to do this.

Add the button in your item draw function:

<pre class="language-javascript">
ext.point('io.ox/core/notifications/tutorial/item').extend({
draw: function (baton) {
this.append(
$('<div class="tutorial item">')
.attr('data-cid', baton.model.cid)//needed for identification
.append(
$('<div class="mytext">').text(baton.model.get('title')),//some text to fill it
$('<button class="mybutton btn btn-primary" data-action="close">').text('close')//close button
)
);
}
});
</pre>

Now add an event to your view to be triggered on clicking it.

<pre class="language-javascript">
events: {
'click .item': 'openPopup',
'click [data-action="close"]': 'closeNotification'
}
</pre>

This will call the closeNotification if the user clicks on a dom node where the attribute data-action has the value close, like our button.

Finally add the close funktion to your view:

<pre class="language-javascript">
//the action for the close button
closeNotification: function (e) {
e.stopPropagation();//to prevent sidepopup from opening

var cid = $(e.currentTarget).closest('.item').attr('data-cid'),//getting the right model
model = this.collection.getByCid(cid);

this.collection.remove(model);//remove it from the collection
}
</pre>

Again get the cid to identify the right model, then remove it from the collection.
''e.stopPropagation()'' is important here because otherwise the event would bubble up and trigger the click event for opening our sidepopup too.

Congratulations your notifications should be removed if you click the button.

The final version should look like this.

[[Image: finished.png]]

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

[[File: Notification_tutorial.zip]].

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

== 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:Wizard framework

2015-08-10T09:04:08Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
or hotspot(array)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values). The API also support multiple hotspots: hotspot(array) with array containing selectors (string) or array of [selector, options].
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector, [timeout])
| The step waits for a certain element to exist before showing the popup. Optional: Use a custom timeout. Default is 5 seconds.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
| step:*
| All step-based events are forwarded, e.g. step:back, step:next, step:before:show
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|-
| before:navigate
| Triggered before the step navigates to another app
|-
| navigate
| Triggered after the step has navigated to another app
|-
| wait
| Triggered when the step wait for a certain element (waitFor)
|-
| ready
| Triggered when "waitFor" is resolved (this event is always triggered, when a step is ready to be displayed)
|-
| align
| Triggered right after the automatic alignment but shortly before the step is shown
|-
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-08-10T09:01:28Z

Matthias.biggeleben: /* Events */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
or hotspot(array)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values). The API also support multiple hotspots: hotspot(array) with array containing selectors (string) or array of [selector, options].
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
| step:*
| All step-based events are forwarded, e.g. step:back, step:next, step:before:show
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|-
| before:navigate
| Triggered before the step navigates to another app
|-
| navigate
| Triggered after the step has navigated to another app
|-
| wait
| Triggered when the step wait for a certain element (waitFor)
|-
| ready
| Triggered when "waitFor" is resolved (this event is always triggered, when a step is ready to be displayed)
|-
| align
| Triggered right after the automatic alignment but shortly before the step is shown
|-
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-08-10T09:00:12Z

Matthias.biggeleben: /* Events */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
or hotspot(array)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values). The API also support multiple hotspots: hotspot(array) with array containing selectors (string) or array of [selector, options].
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
| step:*
| All step-based events are forwarded, e.g. step:back, step:next, step:before:show
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|-
| wait
| Triggered when the step wait for a certain element (waitFor)
|-
| ready
| Triggered when "waitFor" is resolved (this event is always triggered, when a step is ready to be displayed)
|-
| align
| Triggered right after the automatic alignment but shortly before the step is shown
|-
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-23T09:58:50Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
or hotspot(array)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values). The API also support multiple hotspots: hotspot(array) with array containing selectors (string) or array of [selector, options].
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-23T09:58:10Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values). The API also support multiple hotspots: hotspot(array) with array containing selectors (string) or array of [selector, options].
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-22T13:33:41Z

Matthias.biggeleben: /* Screenshot */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup

[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot

[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values).
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-22T13:33:25Z

Matthias.biggeleben: /* Screenshot */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

Basic popup
[[File:Wizard_example_popup.png|500px|frameless]]

Step with hotspot
[[File:Wizard-hotspot.png|799px|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values).
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-22T13:32:58Z

Matthias.biggeleben: /* Screenshot */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|500px|frameless|Basic popup]]

[[File:Wizard-hotspot.png|799px|frameless|Step with hotspot]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values).
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-22T13:31:36Z

Matthias.biggeleben: /* Screenshot */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|500px|frame|Basic popup]]

[[File:Wizard-hotspot.png|799px|frame|Step with hotspot]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values).
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

File:Wizard-hotspot.png

2015-07-22T13:29:10Z

Matthias.biggeleben:

AppSuite:Wizard framework

2015-07-22T11:34:11Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| hotspot(selector, options)
| Places a hotspot on top left corner of given element; options can define "top" and "left" to adjust the position (pixel values).
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-22T11:31:34Z

Matthias.biggeleben: Renamed pointAt to referTo

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| referTo(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.referTo('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, referTo(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-21T17:58:04Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, pointAt(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-20T18:42:50Z

Matthias.biggeleben: /* Smartphone support */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their overall appearance is different, i.e. tours run in fullscreen. Therefore, pointAt(), spotlight(), navigateTo(), waitFor() have no effect because you cannot see the underlying UI; which probably has an impact on the text as well. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-20T14:07:29Z

Matthias.biggeleben: /* Smartphone support */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their appearance is different, i.e. a tour runs in fullscreen. Therefore, alignment, spotlight, navigateTo, waitFor have no effect because you cannot see the underlying UI. Generally, a tour should be quite simple. Less is more.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-20T14:06:29Z

Matthias.biggeleben: /* Smartphone support */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their appearance is different, i.e. a tour runs in fullscreen. Therefore, alignment and spotlight have no effect because you cannot see the underlying UI.

[[File:Tour_on_smartphone.png|frameless|319px]]

AppSuite:Wizard framework

2015-07-20T14:06:20Z

Matthias.biggeleben: /* Smartphone support */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their appearance is different, i.e. a tour runs in fullscreen. Therefore, alignment and spotlight have no effect because you cannot see the underlying UI.

[[File:Tour_on_smartphone.png|frameless]]

AppSuite:Wizard framework

2015-07-20T14:06:02Z

Matthias.biggeleben: /* Smartphone support */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their appearance is different, i.e. a tour runs in fullscreen. Therefore, alignment and spotlight have no effect because you cannot see the underlying UI.

[[File:Tour_on_smartphone.png|frameless|300px]]

File:Tour on smartphone.png

2015-07-20T14:05:29Z

Matthias.biggeleben:

AppSuite:Wizard framework

2015-07-20T14:03:20Z

Matthias.biggeleben:

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

=== Smartphone support ===
The framework has embedded smartphone support. However, it is recommended to create dedicated tours for smartphones because their appearance is different, i.e. a tour runs in fullscreen. Therefore, alignment and spotlight have no effect because you cannot see the underlying UI.

AppSuite:Wizard framework

2015-07-17T09:14:47Z

Matthias.biggeleben: /* Screenshot */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless|500px]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

File:Wizard example popup.png

2015-07-17T09:14:08Z

Matthias.biggeleben:

AppSuite:Wizard framework

2015-07-17T09:12:41Z

Matthias.biggeleben: /* Simple example */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== Screenshot ===

[[File:Wizard_example_popup.png|frameless]]

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

AppSuite:Wizard framework

2015-07-17T09:06:06Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button. All buttons are enabled by default. The first step doesn't have a back button, of course. And the last step offers a "Done" button instead of the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

AppSuite:Wizard framework

2015-07-15T18:54:48Z

Matthias.biggeleben: /* API */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button.
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button.
|-
| isFirst()
| Returns true if the current step is the first one.
|-
| isLast()
| Returns true if the current step is the last one.
|-
| pointAt(selector)
| Affects the dialog location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element.
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown.
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

AppSuite:Wizard framework

2015-07-15T13:50:40Z

Matthias.biggeleben: /* Using the registry */

<div class="title">Wizard/Tour framework</div>

App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.

=== Simple example ===
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
</pre>
The function '''step()''' adds a new step. Each step is separate '''Backbone view''' instance (DisposableView to be more precise). The following function calls '''title()''' and '''content()''' both work on that view; '''end()''' just returns to the tour (same idea as in jQuery's end()). This allows long definition chains. A more complex example that puts a spotlight on an element:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.mandatory()
.end()
.step()
.title('Step 2')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.mandatory()
.beforeShow(function () {
// do anything you want to customize the step
console.log('before show', this);
})
.end()
.start();
});
</pre>

=== API ===

{|
|-
! Function !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step()
| Add a new wizard/tour step.
|-
| end()
| Go back to parent element, i.e. the Wizard or the Tour.
|-
| start()
| Start the wizard/tour.
|-
!colspan="2"|Step
|-
| title()
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| content()
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| footer()
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function.
|-
| mandatory()
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works.
|-
| toggleNext(state)
| Enables (true) or disables (false) the "Next" button
|-
| toggleBack(state)
| Enables (true) or disables (false) the "Back" button
|-
| isFirst()
| Returns true if the current step is the first one
|-
| isLast()
| Returns true if the current step is the last one
|-
| pointAt(selector)
| Affects the dialogs location (alignment happens automatically).
|-
| spotlight(selector)
| Sets a spotlight on a given element
|-
| modal([state])
| Shows a darker backdrop. Default is true.
|-
| waitFor(selector)
| The step waits for a certain element to exist before showing the popup.
|-
| navigateTo(id, [options])
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch().
|-
| scrollIntoView(selector)
| This element will be scrolled into view before the popup is shown
|-
| beforeShow(callback)
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view.
|}

=== Events ===

{|
|-
! Event name !! Description
|-
!colspan="2"|Wizard/Tour
|-
| step:next
| Triggered when moving ahead.
|-
| step:back
| Triggered when moving back.
|-
| step:close
| Triggered when closing the wizard/tour.
|-
| step:done
| Triggered when finishing the wizard/tour.
|-
| before:start
| Triggered before starting the wizard or the tour.
|-
| start
| Triggered when the wizard or the tour has been started
|-
| before:stop
| Triggered before closing the wizard or the tour.
|-
| stop
| Triggered when the wizard or the tour has been closed
|-
!colspan="2"|Step
|-
| next / back
| Same as step:next or step:back (see above)
|-
| close / done
| Same as step:close or step:done (see above)
|-
| before:show
| Triggered before showing the step
|-
| show
| Triggered when the step is visible
|-
| before:hide
| Triggered before hiding the step
|-
| hide
| Triggered when the step is hidden
|}

=== Using the registry ===
A tour only works once, i.e. its steps get disposed once the tour stops. This is intended behavior in order to avoid side-effects and memory leaks. If you want to run a tour twice you have to redefine it. The registry simplifies that:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {

// you can store any data you want; only 'id' is mandatory
Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr.')
.spotlight('.classic-toolbar')
.end()
.start();
});

// run a tour
Tour.registry.run('test');
});
</pre>

The registry also helps at listing existing tours:
<pre class="language-javascript">
require(['io.ox/core/tk/wizard'], function (Tour) {
// get all items
console.log(Tour.registry.list());
// just get type=tour
console.log(Tour.registry.list('tour'));
// which is a shortcut for
console.log(Tour.registry.collection.where({ type: 'tour' }));
});
</pre>

=== Complex example ===
<pre class="language-javascript">
void require(['io.ox/core/tk/wizard'], function (Tour) {

Tour.registry.add({ id: 'test', title: 'Test', type: 'tour' }, function () {

new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.classic-toolbar')
.end()
.step()
.title('Top-bar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('#io-ox-topbar')
.pointAt('.launchers-secondary')
.end()
.step()
.title('Search')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.io-ox-find')
.end()
.step()
.title('Something at the bottom')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.generic-toolbar.bottom')
.end()
.step()
.title('Top toolbar')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.')
.spotlight('.toolbar.generic-toolbar.top')
.end()
.step()
.title('Step 2')
.navigateTo('io.ox/mail/main')
.waitFor('.thread-view-list')
.mandatory()
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt.')
.spotlight('.thread-view-list')
.end()
.step()
.title('Step 3')
.content('Lorem ipsum dolor sit amet.')
.navigateTo('io.ox/contacts/main')
.waitFor('.folder[data-id="6"]')
.spotlight('.folder-tree')
.scrollIntoView('.folder[data-id="6"]')
.beforeShow(function () {

this.$('.content').append(
$('<p><a href="#" class="enable-next">Enable</a></p>')
);

this.toggleNext(false);

this.$el.on('click', '.enable-next', function (e) {
e.preventDefault();
this.toggleNext(true);
}.bind(this));
})
.end()
.step()
.title('Last step')
.content('Lorem ipsum dolor sit amet.')
.modal(false)
.end()
.start();
});

Tour.registry.run('test');
});
</pre>

AppSuite:Wizard framework

2015-07-15T13:48:53Z

Matthias.biggeleben: /* Using the registry */

AppSuite:Wizard framework

2015-07-15T13:48:02Z

Matthias.biggeleben: /* Using the registry */

AppSuite:Wizard framework

2015-07-15T13:34:59Z

Matthias.biggeleben: /* Using the registry */

AppSuite:Wizard framework

2015-07-15T13:25:44Z

Matthias.biggeleben: /* Simple example */

AppSuite:Wizard framework

2015-07-15T13:24:07Z

Matthias.biggeleben: /* Simple example */

AppSuite:Wizard framework

2015-07-15T13:22:19Z

Matthias.biggeleben: /* API */

AppSuite:Wizard framework

2015-07-15T13:21:52Z

Matthias.biggeleben: /* API */

AppSuite:Wizard framework

2015-07-15T13:20:54Z

Matthias.biggeleben: /* API */