Wizards deprecated
Upsell wizard
Customers usually want to offer context-sensitive content in an IFRAME if the upsell is triggered. Therefore, OX App Suite comes with an integrated but optional plugin that takes care of this. Just enable plugins/upsell/simple-wizard by setting the capability simple-wizard server-side (or by adding &cap=simple-wizard to the URL for testing/development purposes).
This plugin registers for the event 'upsell:requires-upsell', opens a modal popup/layer, and loads a custom URL in an embedded IFRAME.
The upsell wizard is a small shopping cart application that displays packages/services.
They process is the usual three-step process of putting items in your cart, reviewing and ordering them. Upon completion the upsell wizard calls an URL with the ordered items as well as the shoppers's ID and context number. It is left to the provider to implement some handler for that.
plugins/upsell//shop:
priceFormat: '$%sUSD'
target: 'http://localhost/order-confirmation?cartContents=OXUPSELLCART&context=OXUPSELLCONTEXT&user=OXUPSELLUSER'
disclaimer:
en_US: 'You're going to sell your soul to us'
products:
en_US:
p0:
image: 'https://product-image1'
title: 'All - special offer'
price: 99
description: 'This Special Offer is only for a limited time. '
The price format is given as format string to provide maximum flexibility. '%s' represents the amount.
The target is the URL that is called after shopping is completed. The values OXUPSELLCART, OXUPSELLCONTEXT and OXUPSELLUSER are replaced by the wizard with a comma-separated list of the ids of items bought, the buyer's context ID and their user ID.
The disclaimer can be internationalized like texts for upsell widgets. The same possibilities and restrictions apply.
Products shown can also be country-specific. If only one locality (here: en_US) is given, that is always picked.
A product consists of an image (displayed on the left), a title (on the right), a description and a price value. The description can, as usual, be marked up as HTML.
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 is not a typo!).
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
| Settings | Description |
|---|---|
| url | Custom URL that is loaded in IFRAME; can contain special 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 |
Note: Changing such settings requires a backend restart
Custom URL variables
The upsell wizard 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:
upsell.php?user_id=$user_id&context_id=$context_id&language=$language&missing=$missing
| Settings | Description |
|---|---|
| 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 |
| $language | The current user's language, e.g. de_DE or en_US |
| 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) |
Development and debugging
While experimenting or developing, you can use the following helpful functions:
// 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 enable 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();
Some examples for customizations in UI plugin/console:
// 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' });
});
Close function
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):
// 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');
Custom backend systems that run on a different domain cannot use javascript to close the wizard.
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.
Welcome wizard
You are able to use the Welcome Wizard in order to include upsell as well as cross-sell content. For more information please see Writing a wizard