Imported Upstream version 4.6.2

install/ui/doc/guides/phases/README.md

@@ -0,0 +1,125 @@
+# Introduction
+
+Declarative nature and support for extensibility of FreeIPA WebUI
+creates demand for structural initialization of the application. Phase
+components were created to solve this tasks.
+
+## Components
+
+Phases functionality consists of the two components/modules:
+`./_base/PhaseController` and `./phases`.
+
+### PhaseController
+
+Phase controller basically does all the work. It provides functionality for running and
+changing phases.
+
+-   define phases
+-   controls instantiation of PhaseController
+-   provides API for phase task registration
+
+## Phase
+
+Phase is a part of application runtime. Most of the phases are related
+to load and initialization process.
+
+### Tasks
+
+Phase consists of task. Each task can have a priority set, 10 is
+default. Task can by synchronous or asynchronous. When phase is started
+it runs all tasks sequentially sorted by priority. If the task is
+synchronous it waits for its completion before starting another task.
+Asynchronous task are just started. Phase is completed when all task
+finishes - waits for all asynchronous tasks.
+
+Asynchronous task is a task which handler returns a promise.
+
+### Phase task registration
+
+Modules should register a phase task through `./phases` module.
+
+    phases.on('phase_name', handler, priority);
+
+## Descriptions of FreeIPA phases
+
+FreeIPA has following phases:
+
+-   customization
+-   registration
+-   init
+-   metadata
+-   post-metadata
+-   profile
+-   runtime
+-   shutdown
+
+### Resource load implicit phase
+
+Each application needs to load its resources. This mainly means
+JavaScript files but also CSS files, images and fonts. Phases modules
+are part of that data and therefore are no initialized until loaded.
+Hence resources load is an implicit and a first phase.
+
+FreeIPA Web UI uses AMD modules therefore resources have to be either
+declared in main HTML file’s header or in modules specification. The
+former one is obsolete and should be replace by the latter.
+
+The main HTML file should require an application module. Application
+module is a module that should have dependencies required for the
+application to run. By specifying these dependencies we may control
+which modules/plugins and their dependencies get loaded. Currently it’s
+`freeipa/app`.
+
+### Alternation phase
+
+Serves for altering components specifications. This phase should be used
+only by plugins and configurable modules. Core modules shouldn’t use
+this phase.
+
+### Registration phase
+
+Modules should register widget, facet, entity final construct
+specifications.
+
+### Init phase
+
+Serves for initialization of core UI components: application controller,
+router, menu, application widget …
+
+### Metadata phase
+
+Metadata, configuration and user specific information should be loaded
+in this phase.
+
+### Runtime phase
+
+Phase where plugins can expect that application is completely
+initialized. Most of user interaction will happen here.
+
+### Shutdown phase
+
+Destroys session. Currently redirects to other page. In future may
+destroy all facets and entities and just show basic UI again.
+
+## Adding a new phase
+
+One can add a new phase at any time. It will be executed only if it’s
+position is after currently running phase.
+
+
+    define(['./phases'], function(phases) {
+
+        // add 'new-phase' on the last position
+        phases.add('new-phase');
+
+        // add 'pre-runtime' phase before 'runtime' phase
+        phases.add('pre-runtime', { before: 'runtime' });
+
+        // add 'post-runtime' phase after 'runtime' phase
+        phases.add('post-runtime', { after: 'runtime' });
+
+        // add '7th-phase' phase on exact position (whatever it is)
+        // or on the last, if position is bigger than number of currently
+        // registered phases
+        phases.add('7th-phase', { position: 7 });
+    });