CodeCoupler UI System
System a CodeCoupler UI container will be initialized.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
options are optional. If only one argument is given, then it will be used as
options if it is an
object otherwise it will be interpreted as
element the body will be initialized as CodeCoupler System. If you want to initialize the
system into a specific element, you can define this in the argument
element. The value can be any
HTMLElement, jQuery Object or Selector String.
If you initialize the System without
element, or with
html as target container, a
div will be created inside of the
body in which the CodeCoupler System will run. The new
body and the
html element will be stretched to
height: 100% and the
attribute will be set to
Otherwise only the
overflow style attribute of the container element will be set to
Lifecycle and Message Tokens
By initializing a new System the firstly following steps are carried out:
- Preload DataSources, Fonts where no authentication is needed
- Authenticate User
- Preload DataSources, Fonts where authentication is needed
If DataSources or required fons cannot be loaded, or any other error occurs, the Premise
initialized will be rejected. The element will be blocked and a message in the selected language
will be displayed. The returned error corresponds to the message token which is used to display the
message. This token can be catched and it is one of the following:
|ERROR_PRELOAD_DATASOURCES||A DataSource cannot be loaded|
|ERROR_PRELOAD_FONTS||A required Font cannot be loaded|
|NOT_IMPLEMENTED_LANGUAGE||The language specified is not implemented|
The user authentication has its own lifecycle:
- Get current user from authentication module
- Request login if permissions are required and if no current user authenticated.
- Request login and show message if permissions are required and if current user do not have sufficient permission.
- Loop this steps until all requirements are met.
The authentication process uses the following message token to show a message if current user do not have sufficient permission:
|USER_NOT_AUTHORIZED||User does not have the required permission|
After the preloading phase url commands will be checked. With these commands you can start into the
system an app or a widget without any further steps. In case of an error the premise
will be rejected. The element will be blocked and a message in the selected language will be
displayed. The returned error corresponds to the message token which is used to display the message.
This token can be catched and it is one of the following:
|ERROR_START_APP||The requested Application cannot be started|
|ERROR_START_WIDGET||The requested Widget cannot be started|
After executing the url command the initialization fishes and the promise
The url command feature is not full implemented in version 2 yet and will not work for now!
If no url command found the stages like noted in
stages will be added to the system. In case of an
error the premise
initialized will be rejected. The current stage will be blocked and a message in
the selected language will be displayed. The returned error corresponds to the message token which
is used to display the message. This token can be catched and it is one of the following:
|ERROR_STAGE_STYLE||New stage do not have
|ERROR_STAGE_TYPE||Type is unknown|
At last the last used app of the user will be started in the current stage, if this feature is enabled.
The starting last app feature is not full implemented in version 2 yet and will not work for now!
There are two more general errors that can occur:
|OPTIONS_ERROR||An option do not have the correct type (console will print details)|
|UNKNOWN_ERROR||This will returned if an unknown error occured (console will print details)|
- language: string
Language to use to switch to for all external libaries noted as four letter code like
this option is not specified, English is used.
For now only
de-DE is implemented and only experimetial in version 2!
- preloader and preloaderAuth: object
These objects contain ressources that have to be loaded during the initialization phase. The
preloader will be loaded before the user authentication and the ressources in
preloaderAuth after that.
- preloader and preloaderAuth.dataSources: DataSource
Array of DataSources to fetch before authentication.
- preloader and preloaderAuth.fontsRequired: string | object
font-face names to load before authentication. If loading fails the initialization will
In addition to the name, the variation can also be specified. Herefore the
Font Variation Description will be used like explained here: [https://github.com/typekit/fvd]
Example: "Font Awesome 5 Free:n4,n9" will load the font
Font Awesome 5 Free in normal style and
with the weights 400 and 900.
Because the external library Web Font Loader is used under the hood, you can alternatively set the configuration object directly.
All the fonts used by the exetrnal libraries included in CodeCoupler System ("Font Awesome 5
Brands", "Font Awesome 5 Free:n4,n9", "context-menu-icons", "WebComponentsIcons", "DejaVu
Sans:n4,n7,i4,i7", "DejaVu Serif:n4,n7,i4,i7", "DejaVu Mono:n4,n7,i4,i7") will always preloaded.
This list of fonts is defined in
System.defaults.preloaderAuth.fontsDefault and can be adjusted
- preloader and preloaderAuth.fonts: string
Array of font-face names to load before authentication. The system will be initialized even if the loading fails.
auth.module: CodeCoupler Authentication Module
The authentication module to use. If none is given the default module will be used which do provide only anonymous access.
- auth.requiredPermission: string
The permissions the user must have to initialize the CodeCoupler System. Can be set to
$autorized to allow any authorized user to initialize the CodeCoupler System.
Default configuration for blocking messages. Details on this configuration object can be found here: BlockUI Configuration
- block.error: object
Default configuration for blocking error messages. Details on this configuration object can be found here: BlockUI Configuration
- systemId: string
If starting multiple systems on one page, it is usefull to set an id for each one. Only with this id we can use url commands or running the last app the user has started.
These features are not full implemented in version 2 yet and will not work for now!
- history: object
This feature is not full implemented in version 2 yet and will not work for now!
If true, the last started app of the user will be started right after initializing the system.
If true, the last started app of the user will be saved in its configuration.
If true each application that is fronted will be pushed into the browser history so the back and forward buttons will navigate to the previous and the next application.
- stages: object
Array of stages and their options to add sequencially within the initialization phase.
- stages.stage: CodeCoupler Stage Class
The class of the stage to add.
- stages.options: Any value
The options that will be used to instatiate the stage class.
You can set default values for all new created instances of a CodeCoupler System by setting
- block(type, message)
Block the element in which the system is loaded with a message. If you set
error. A different stylesheet will be used.
You do not need to unblock and block again to change the message or switch from
block again and the message and style will change automatically.
Unblock the element in which the system is loaded.
- blockStage(type, message)
block but blocks only the current stage.
unblock but unblocks only the current stage.
- blockElement(type, message, element)
block but blocks only a specific element.
element can be an HTMLElement, a jQuery
object or a selector string.
unblock but unblocks only the current stage.
- stage(stage class, options)
Divide current stage in different areas and create a new stage. The first argument should be a
class derived from
Stage. See documentation of
Stage for more details on how to create an own
The App can be instantiated directly:
var instance = new namespace.appName([element,[options,[panelOptions]]]);
"element" is the container of the app and can be a node object or a jQuery object. If omitted or
body element will be used. Read some more details about this option here:
"options" are the options with which the caller want to start the app. Default options of the app can be set with:
namespace.appName.defaults.optionName = newDefaultValue;
"panelOptions" are the options for the panel creation. the following options cannot be set:
"container" and "syncMargins": The container will be already defined by the first argument of the constructor. "syncMargins" is always "true".
"cssClass": The dashed name of the app will always be used (see below).
"callback": This will be hard wired to an internal function. Inside of this function the instance methods "initApp" and "initWidgets" will be called.
"onbeforeclose": This will be hard wired to the instance method "closeApp".
If you want to start an app only once (singleton) you can use the panelOption "id". In case the existing id belongs to an already existing panel this panel is fronted and no new instance will be created. The existing instance will be returned.
An additional reference will be set inside of the namespace "libs.Apps". This is for collecting all available apps in one place. Therefore you can also instantiate the app or set the default options with:
var instance = new libs.Apps.namespace.appName(element,options,panelOptions); libs.Apps.namespace.appName.defaults.optionName = newDefaultValue;