Skip to content

CodeCoupler UI System

With System a CodeCoupler UI container will be initialized.

Initialize

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// As one-liner
const system = await new System(element, options).initialized;

// Separate lines
const system = new System(element, options);
await system.initialized;

// Try/Catch Syntax
const system = new System(element, options);
try {
  await system.initialized;
} catch (e) {
  // Catch an error
}

// Then/Fail Syntax
const system = new System(element, options);
await system.initialized
  .then(() => {
    // Do something
  })
  .catch((e) => {
    // Catch an error
  });

element and 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.

Without 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 body or html as target container, a div will be created inside of the body in which the CodeCoupler System will run. The new div, the body and the html element will be stretched to height: 100% and the overflow style attribute will be set to hidden.

Otherwise only the overflow style attribute of the container element will be set to hidden.

Lifecycle and Message Tokens

By initializing a new System the firstly following steps are carried out:

  1. Preload DataSources, Fonts where no authentication is needed
  2. Authenticate User
  3. 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:

Token Cause
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:

  1. Get current user from authentication module
  2. Request login if permissions are required and if no current user authenticated.
  3. Request login and show message if permissions are required and if current user do not have sufficient permission.
  4. 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:

Token Message
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 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:

Token Cause
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 initialized will resolve.

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:

Token Cause
ERROR_STAGE_ROLE data-role attribute not found in new stage
ERROR_STAGE_STYLE New stage do not have absolute, relative or fixed position style
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:

Token Cause
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)

Options

  • language: string

Language to use to switch to for all external libaries noted as four letter code like de-DE. If 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 ressources in 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

Array of font-face names to load before authentication. If loading fails the initialization will be canceled.

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 there.

  • 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: object

  • 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.

  • block: object

  • block.message: object

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!

  • history.open:

If true, the last started app of the user will be started right after initializing the system.

  • history.save:

If true, the last started app of the user will be saved in its configuration.

  • history.navigate:

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.

Global Defaults

You can set default values for all new created instances of a CodeCoupler System by setting System.defaults.

Instance Methods

  • block(type, message)

Block the element in which the system is loaded with a message. If you set type to info or error. A different stylesheet will be used.

You do not need to unblock and block again to change the message or switch from type to info. Just call block again and the message and style will change automatically.

  • unblock()

Unblock the element in which the system is loaded.

  • blockStage(type, message)

Same as block but blocks only the current stage.

  • unblockStage()

Same as unblock but unblocks only the current stage.

  • blockElement(type, message, element)

Same as block but blocks only a specific element. element can be an HTMLElement, a jQuery object or a selector string.

  • unblockElement()

Same as 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 stage class.

  • app(..)

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 falsy the body element will be used. Read some more details about this option here: https://jspanel.de/api.html#options/container

"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;