Description

Following the first Onboarding Analysis, we decided that we should go for a revamping of the old Distribution Wizard, using some "slides" UI, and bringing some new features (e.g. suggestions of extensions)

UI Choices

The idea of this UI is to have the following UI concepts:

• a dialog, that can be displayed on top of the wiki pages and contain any HTML
• several identifiable and numbered steps, knowing that the total number may change dynamically following choices
• buttons allowing to move forward in the step and backwards
• we want to be able to block validating a step until some form is filled

We identified a few existing libraries for that, such as: 

• https://tushargugnani.github.io/vue-step-wizard/#/
• https://github.com/Anivive/vue3-form-wizard

But, those libraries are generally very poorly maintained and our need is so generic that we probably don't need to use an external library and it's probably easier to just implement it ourselves.

Proposal on https://forum.xwiki.org/t/onboarding-status-and-slides-design-decisions/18163 for not using a dedicated library. 

Features of Distribution Wizard

The current Distribution Wizard main features are following:

• automatically displayed when accessing a wiki to install or upgrade it depending on several different conditions (configuration choices, user rights, user previous choices, versions of the wiki etc)
• allow to create a first admin user in case of new install (see also steps)
• allow to select to replay "choices", but with quite a limited UX right now (only allow to replay EM operations, and needs an admin user to have been created)
• allow to select and install the flavor (for install and upgrade)
• allow to search for extension updates and install them (in case of upgrade only)
• allow to perform choices on orphaned extension (in case of upgrade only and only if there's such extensions)
• allow to see the report of installed pages

Open questions:

• do we want to keep asking users to select the flavor when there's only one?
• what exactly the final report is supposed to display? 
• do we want the replay feature to be really accessed from there? 

Requested features:

• suggest to admin a set of recommended extensions to install
• provide what's new info
• allow to upgrade subwikis too

Steps

We can distinguish steps for new install and for upgrade. Note: optional steps can be skipped safely. 

Fresh install

1. Welcome
2. OS checks 
3. Create admin user 
4. Select flavor (mandatory but should be displayed only if more than 1 flavor available else the unique flavor should be selected automatically?)
5. Install flavor
6. Configure logo / title (optional)
7. Recommended extensions to install (optional)
8. Security configuration (optional)
9. Post setup message with instructions and/or release notes (optional)

Upgrade

1. Welcome
2. Release notes
3. Upgrade installed flavor (do we need to propose a flavor to select here?)
4. Orphaned dependencies handling (we know if that applies only after the upgrade so we should always display it)
5. Extension Upgrades (optional)
6. Event migration (only if it applies)
7. Subwiki upgrades (optional)
8. Security configuration (optional)
9. Post setup message

Architecture

Generic Wizard UI

A generic wizard is defined by the following elements:

• a dialog which is the container of the whole wizard
• a breadcrumb displaying the list of steps
• the current step
• buttons to validate and go to next step, or to come back to a previous step

Dialog

It just displays the wizard title and the structure for the different elements. It also has the logic for manipulating the steps. The app is created from that dialog by providing the resolver functions to communicate with the backend (see the protocol).

Breadcrumb

It should display the ordered list of steps, with the title of each step, and some information whether the step depends on another one or not. Since the list of steps is dynamic, the breadcrumb should be clear about the steps that are fixed, the ones that might disappear, and where new steps could appear. 

Step

There's no generic rule for displaying a step: each step defines its own elements. However a step should never add buttons to validate it, since this should always be controlled by the wizard buttons itself. 

The step can be defined using a VueJS component, but it also can use standard velocity template: in such case the javascript needed for the step initialization and callbacks (see also the protocol), should be exposed in a module using this naming convention and signatures:

• <stepId-lowercase>Init : Promise<void>
• <stepId-lowercase>Callback : Promise<boolean>

The step defines the following information:

• startsOnDisplay: a boolean indicating if the step process needs to be triggered on display (false if the step should wait for user inputs, or there's nothing to process)
• needsInput: a boolean indicating if the step needs user inputs (if true the callback method will be resolved and called)
• skippable: a boolean indicating if the step can be immediately skipped or not

Buttons

The button for accessing next step is displayed but disabled by default if the step is not skippable. The step needs to emit an event xwiki:distributionWizard:validateStep if jQuery is used or "validateStep" if VueJS is used (and respectively invalidateStep) to enable or disable the buttons. The step is responsible to know when the button should be enabled or not.

When the button is clicked operations are automatically performed depending on the metadata of the step (see protocol), before displaying the next step or errors.

If it's final step in the list, the button is automatically a finish button and the page is refreshed after clicking on the buttons and performing the actions.

Protocol

The protocol for the generic UI to communicate with the back relies on 3 resolvers that needs to be provided to the app when creating the dialog (main endpoint of the app):

• stepsResolverFunction: () => Promise<WizardDialogProps>
• stepResolverFunction: (stepId: string) => Promise<WizardStepProps>
• startStepFunction: (stepId: string) => Promise<boolean>

The protocol for the app is the following: 

1. The dialog is created with empty values (title and list of steps) and not displayed
2. The dialog performs a request to load the main dialog information using the stepsResolverFunction which doesn't take any argument: once resolved the list of step information and the wizard title are available. The breadcrumb can be built too. 
3. The dialog loads the first step of the list using stepResolverFunction with the step ID as argument 
4. If the step needs to be started on display, the startStepFunction is called there
5. Once the first step is loaded the dialog can be fully displayed
6. Either the step is skippable and the next step button is already enabled, or the user performs actions that leads to the step to trigger the validation event
7. The next step button is enabled
8. The user clicks on the next step button
9. If the step needs user inputs, the callback function of the step is loaded and called
10. If there was no need for user inputs or if the callback is successful, the next step is loaded
11. We repeat operations from stage 4 (ignoring 5) until final step
12. If it's final step the user clicks on "Finish" instead of "Next", same operations happens than on stage 9 but in case of success  the dialog disappears and the page is redirected