Core - globules-io/OGX.JS GitHub Wiki
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
}
1.31.0+
Splash 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_
}
}
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 aogx_key
cookie with your encryption key as value. The cookie will be detected and deleted andapp.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();
1.25.0+
Exportable 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, ...});
1.25.0+
Unique 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",
"use": true,
"home": "login",
"placeholder": "#view",
"scope": "public",
"theater": false
}
},
...
}
The
home
attribute defines the default route upon start of the application. It MUST have a default route.placeholder
defines the HTML selector of the template that will be used by the stage to display content.
You can also use a
stage
without atemplate
, in this case, theplaceholder
must be set to default
{
...
"vapps":{
"stage:Stages.Stage":{
"use": true,
"home": "login",
"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 thejwt
flag totrue
inapp.json
.
No JWT mode
If you set the
jwt
flag tofalse
inapp.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);
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);
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
andViews
are supported
1.25.0+
Hot Reload You can live reload
HTML
andCSS
documents (/bin
/views
/stages
only) when using thedev
version ofOGX.JS
app.refresh();
1.31.0+
Manifest Version Fetch the manifest version
app.version((__version) => { console.log(__version); });
1.37.0+
Extending App 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