Skip to content

Core

Jump to bottom
Eric edited this page Jan 18, 2025 · 122 revisions

App is the core of the application. It can hold multi stages, windows, popups and an overlay per stage.

Stack

App by default extend

  Uxi, Overlay, Touch;

And require

 Object, OML, Templater, Controller, Display

Note that if you use a release build ogx.min.js, you do not have to worry about including any other file (but the css).

OGX.App requires a configuration file app.json that must exist in the www folder of your project. If you are using the CLI, the file is automatically created when initialiazing the project by doing ogx init. Otherwise, create that file by hand, here is the skeleton

 {
     "routing":{},
     "vapps":{},
     "templates":{},
     "scope":"public"        
 }

Options

Here are the available options when creating an app

 {
      encrypted: bool,
      exportable: bool,
      max_render_time: int,
      max_depth: int,
      disable_context: bool,
      unique: bool,
      exit: bool,
      splash: ... see splash
 }

Splash 1.31.0+

If you desire to display a loading screen or splash screen, enable the splash and setup the parameters

 { 
      ...,
      splash: {
           enabled : true,
           color: _STRING_,
           image: _STRING_,
           auto_hide: _BOOL_,
           hide_timeout: _INT_
      }
 }

If you are setting auto_hide : false, you can later on call app.splash.hide(); to manually hide the splash screen

Exit

You can prevent the app from exiting or reloading by setting false to exit

 ...,
 exit: false

Encryption

If you have encrypted app.json via the CLI, you need to set a ogx_key cookie with your encryption key as value. The cookie will be detected and deleted and app.json will be decrypted. Note that this is only relevant in a web environment.

 let app = new OGX.App({encrypted:true, ...});

To create an app without encryption

 let app = new OGX.App();

Async fetch encrypted key 1.40.0+

You can also pass a promise that retrieves then passes the encryption key once resolved

 const app = new OGX.App({encrypted: () => {
      return new Promise(function(success, error){
          //do async call then return key
          success('mykey');
      });
 });

Exportable 1.25.0+

If set to true, the OML tree can be exported starting from any node, if set to false, to export possible.

 let app = new OGX.App({exportable: false, ...});

Rendertime

The rendering of an OML tree is automatically halted if it exceeds max_render_time and defaults to 300ms. You can override this value by passing a new value when creating the app, which can be useful for debugging purposes

 let app = new OGX.App({max_render_time: 400, ...});

Disable Context

Context menu upon right click can be disabled by setting disable_context

 let app = new OGX.App({disable_context: true, ...});

Unique 1.25.0+

To prevent the app from running in another tab

 let app = new OGX.App({unique: true, ...});

You can also pass a callback if you want to check the result of the uniqueness

 let app = new OGX.App({unique: (__bool) => {
      //true => is unique
      //false => another instance is already running
 } );

Routing

The routing for the entire application must be defined in this file. To learn more about the routing system, out the page dedicated to this.

To prevent any navigation including the use of the back button, you can lock (and unlock) the core by doing

 app.lock(); 
 app.unlock();
 app.isLocked(); //Returns true or false

Default options

 { 
      "history":true,
      "data":null,
      "reload":false
 }

To navigate to another route

 app.goto(_URL_, _OPTIONS_);

Example

 app.goto('stage/welcome', {history:true, data:user});

To get the current URL. Returns the URL of the stage in use.

 app.getURL();

Stages

The stages to be added to your app upon start. For instance, if your app is going to have one stage that you have named stage1, and will be using the Stage object Stage1 and the HTML template Stage, then your configuration will look like this

 {
     ...
     "vapps":{
          "stage:Stages.Stage":{
               "template": "Stage",                    
               "placeholder": "#view",
               "scope": "public", 
               "theater": false
          }
     },
     ...
 }

You can also use a stage without a template, in this case, the placeholder must be set to default

  {
     ...
     "vapps":{
          "stage:Stages.Stage":{ 
               "placeholder": "default"
          }
     },
     ...
 }

Templates

To load and store your HTML templates into the core, add them to the configuration file, such as

 {
     ...
     "preload":{           
          "html":[
               "template.Stage1.html",
               "template.News.html",
               "template.User.html",
               ...         
           ]
     },
     ...
 }

Note that templates must be placed in the www/html/templates folder.

Sounds

Sounds have their on page, go here

JSON

You can also preload JSON data by including a path and file names in the config. The path is relative to the root (www) folder.

  {...,
       preload:{
            json:["my.json"]
            }
       }, ...
 }

Then access the data directly

 app.getJSON('my');

Scope

An array of available scope for the entire application. If your application doesn't handle multiple types of users with different permissions, leave it to ["public"]

The general rule for scope is that, if it is defined as array for a node, the end user must have at least one of the expected scope to see this node. If the scope of the node is declared as string, then the scope must be exact.

Strict scope example (must have all)

 {"something:Something":{
      "scope":"admin manager"
 }}

Using scope expressions

 {"something:Something":{
      "scope":"(admin|manager)|(support+accessA)"
 }}

Loose scope example (must have as least one), deprecated

 {"something:Something":{
      "scope":["admin", "manager"]
 }}

JWT mode

If your app supports multiple user types and you use JWT tokens, you can change the scope of the app by passing the token and the issuer to OGX.Scope

 OGX.Scope.token(JWT_TOKEN, ISSUER);

Once verified, the scope is inherited from the value of the scope property of the token. To retrieve the current scope, do

 OGX.Scope.scope();

To bind JWT tokens' scope to OGX.Scope, set the jwt flag to true in app.json.

No JWT mode

If you set the jwt flag to false in app.json, then you can manually set the current scope by using

 OGX.Scope.scope(ARRAY);

such as

 OGX.Scope.scope(['user', 'support']);

Instantiate

 let app = new OGX.App();

Methods & Shortcuts

This object also brings some shortcuts to creating, removing object and other time savers.

Check if app is running on iOS device

 app.iOS();

Stages

Add a stage to the app

 app.addStage(_STAGE_NAME_, _STAGE_OBJECT, _CONFIG_);

Remove that stage from the app

 app.removeStage(_STAGE_NAME_);

Note that if you declare your stages in the app.json config, you do not need to add stages by code, but know that the methods are available

Use another stage (to add/remove views for instance)

 app.useStage(_STAGE_NAME_);

Snooze a stage (all views, windows of this stage)

 app.snoozeStage(_STAGE_NAME_);

Wake a stage (all views, windows of this stage)

 app.wakeStage(_STAGE_NAME_);

Show a stage (and hide the current one if any)

 app.showStage(_STAGE_NAME_, _ANIMATION_);

Supported animations are swap, flip, slide, shuffle

Add a view to the stage in use

 app.addToStage(_CONFIG_);

Remove a view from the stage in use

 app.removeFromStage(_SELECTOR_);

Windows

Find a Window

 app.getWindow(__id);

Get all Windows

 app.getWindows();

Check if a Window exists

 app.windowExists(__id);

Add a Window (on current Stage)

 app.addWindow(__config);

Check if a Window is open

 app.windowOpen(__id);

Find and show a Window

 app.showWindow(__id, __anim, __cb, __params);

Find and hide a Window

 app.hideWindow(__id, __anim, __cb, __params);

Swap the depth between 2 Windows

 app.swapWindows(__winA_id, __winB_id);

Find and sleep a Window

 app.sleepWindow(__id);

Find and blur a Window

 app.blurWindow(__id);

Find and focus a Window

 app.focusWindow(__id);

Find and remove a Window

 app.removeWindow(__id);

Find and remove multiple windows

 app.removeWindows(__array_of_ids);

Find and remove all window, parameter is optional

 app.removeAllWindows(__array_of_ids_to_skip);

Find the Window given an Object/Class in it

 app.findWindow(__obj);

Check if a Window exists

 app.windowExists(__id_or_regex);

Popups

Add a Popup to current Stage

 app.addPopup(__config);

Find and remove Popup

 app.removePopup(__id);

Find a Popup

 app.getPopup(__id);

Get visible Popups, return array

 app.getVisiblePopups();

Check if a Popup exists

 app.popupExists(__id_or_regex);

Find the Popup given an Object/Class in it

 app.findPopup(__obj);

Overlays

Add Overlay on current Stage

 app.addOverlay(__anim);

Remove Overlay from current Stage

 app.removeOverlay(__anim);

Themes

OGX.JS supports themes (light & dark). In order to use this features, themes must be set this way in your index file

 <!--framework themes-->
 <link href="themes/io-globules-ogx/base/css/theme.min.css" rel="stylesheet" type="text/css">
 <link href="themes/io-globules-ogx/light/css/theme.min.css" rel="stylesheet" media="(prefers-color-scheme: light)" type="text/css" data="light">
 <link href="themes/io-globules-ogx/dark/css/theme.min.css" rel="stylesheet" media="(prefers-color-scheme: no-preference), (prefers-color-scheme: dark)" type="text/css" data="dark">
 <!-- user themes-->
 <link href="css/themes/light.css" rel="stylesheet" media="(prefers-color-scheme: light)" type="text/css" data="light">
 <link href="css/themes/dark.css" rel="stylesheet" media="(prefers-color-scheme: no-preference), (prefers-color-scheme: dark)" type="text/css" data="dark">

Note that each link node has a data attribute set to the preferred color scheme, which is used to override the OS/Browser theme.

To check if dark mode is on

 app.isDarkMode();

To toggle between dark/light modes/themes

 app.toggleTheme();

Files

Get a loaded json file from the cache

 app.getJSON('myfile');

Get a loaded oml file from the cache

 app.getOML('myfile');

Nodes

Move a Uxi from one parent Uxi to the other

 app.moveNode(_UXI_, _NEW_PARENT_UXI_, _SELECTOR_);

Hard delete a node from the framework 1.28.0+

 app.dropNode(_UXI_);
 app.dropNode(_TYPE_, _NAME_);

Note that only Stages and Views are supported

Hot Reload 1.25.0+

You can live reload HTML and CSS documents (/bin /views /stages only) when using the dev version of OGX.JS

 app.refresh();

Manifest Version 1.31.0+

Fetch the manifest version

 app.version((__version) => { console.log(__version); });

Extending App 1.37.0+

OGX.JS Core class can be extended to fit your needs. Consider a custom Core class

 require('CustomClass', 'Core');
 OGX.CustomClass = function(__config){
      construct(this, 'CustomClass');
      'use strict'
 };

Then when creating the app, use

 let app =  new OGX.App({core: 'CustomClass', ..});

Reserved Keywords

OGX.JS has some reserved keywords out of the OGX namespace, that one should not attempt to overwrite.

 require
 construct
Clone this wiki locally