From 3781d33dbe3b116fc3816b40d867ec91b5999ed8 Mon Sep 17 00:00:00 2001 From: Petr Vobornik Date: Fri, 6 Sep 2013 15:20:36 +0200 Subject: [PATCH] Phases Guide --- install/ui/doc/guides.json | 6 ++ install/ui/doc/guides/phases/README.md | 125 +++++++++++++++++++++++++ install/ui/doc/guides/phases/icon.png | Bin 0 -> 3275 bytes 3 files changed, 131 insertions(+) create mode 100644 install/ui/doc/guides/phases/README.md create mode 100644 install/ui/doc/guides/phases/icon.png diff --git a/install/ui/doc/guides.json b/install/ui/doc/guides.json index 466184d7c..3268c1ee4 100644 --- a/install/ui/doc/guides.json +++ b/install/ui/doc/guides.json @@ -2,6 +2,12 @@ { "title": "FreeIPA Web UI Guides", "items": [ + { + "name": "Phases", + "url": "guides/phases", + "title": "Appliaciton phases", + "description": "Introduction to application phases" + } ] } ] \ No newline at end of file diff --git a/install/ui/doc/guides/phases/README.md b/install/ui/doc/guides/phases/README.md new file mode 100644 index 000000000..3d0058bab --- /dev/null +++ b/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 }); + }); diff --git a/install/ui/doc/guides/phases/icon.png b/install/ui/doc/guides/phases/icon.png new file mode 100644 index 0000000000000000000000000000000000000000..d9d9e0d02cb0d61fc2761574052367fde01f12c6 GIT binary patch literal 3275 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 G8v8%Rt23Se literal 0 HcmV?d00001