A graphic menu for launching applications. Based on HTML technologies! This is a rewrite of the IMAGINARY Application launcher.
This is a complete rewrite of the first AppLauncher that is fully configurable, translatable, supports from 1 to 18 applications that can be either HTML apps that run in an iframe or regular executable apps.
- Configurable (without recompiling)
- Translatable (without recompiling)
- Resolution-independent
- Independent from electron, so it can run there, in a standard browser, tablets, etc.
It should aim towards very clean layering:
- Browser
- AppLauncher core (API, Services, Configuration)
- AppLauncher i18n
- AppLauncher layout (visual layout)
- AppLauncher theme (light on dark background, dark on light, etc.)
- Applications
The browser itself and the applications are out of the scope of this project. Facilities for integrating the three parts might be given in a separate repository, document, etc.
Just make the root directory accesible with a web server. You should also configure it... if you have no plans to configure this program then it's not the one you want.
The configuration file is at cfg/config.yml
. It is fully commented so it documents its own format. (NOTE:
The JSON schema used for validation is also available at src/schemas/cfg.schema.json
.)
The default configuration provided is for demo purposes and offers a number of CindyJS applications found
in the internet. A sample configuration that accesses the apps locally is also provided
(sample-local-cindy.config.yml
).
Multiple configurations can be created using the name cfg/<prefix>.config.yml
where prefix is an identifier
made of a combination of uppercase and lowercase ascii letters, digits, underscores or dashes (e.g.
cfg/cindy.config.yml
). The active configuration can be set passing the config identifier through the cfg
query string parameter (e.g. http://localhost/appLauncher/?cfg=cindy
).
Applications are added to the AppLauncher by indicating the paths where they're installed in the config file. The indicated path should contain:
- An
app.json
file that describes the application - An
icons/icon.png
file with a large icon image (1000x1000 is recommended, seedocs/icon template.psd
) - Optionally it can contain other files required to run the app
The app.json should contain the following keys:
-
id: The unique machine name of the application (lowercase letters, numbers, underscore, dash)
-
version: Version identifier, parseable by node-semver (
https://github.com/npm/node-semver
). You can simply use the x.y.z format (e.g.1.0.0
). -
name: The human readable name of the application that will be displayed in the menu. A single string can be specified or an object where each key is a language code and it maps to a translated name. A default name in english (
en
) should always be provided. -
description: (Optional) Description text of the application. It's currently not being displayed but might be in the future. A single string can be specified or an object where each key is a language code and it maps to a translated description. A default description in english (
en
) should always be provided. -
type: (Optional, default: 'iframe') Type of application. Either 'iframe' for launching a web application in an iframe, 'executable' for launching an external process or 'remote' to use a remote launcher (see below).
Extra options can be set depending on the type of application.
These are web apps that will be launched inside an iframe within the appLauncher.
iframe apps can have the following keys:
-
main: File that should be opened in the iframe to launch the application. (e.g.
index.html
) It can be a path or an absolute url. -
width, height: (Optional) Native resolution of the app. If specified the app will be run at this resolution and zoomed (in or out) to fit into the window. If not specified the app will run at the resolution of the frame where it's launched (which might be very small, very large, or change during execution).
-
enableExecution: (Optional) Set to true for apps that are actually an appLauncher2 instance and require launching executable apps. Electron doesn't allow node.js code run in iframes, so executable apps can't be launcehd from iframed appLaunchers. This setting provides appLauncher with a hook to execute in the parent window context.
These are OS-level executable programs (can only be launched when running appLauncher within the electron browser).
-
main: Command to run. The process should stay alive until it's time for the menu to regain control. Note also that the program launched should provide the user for some mechanism to end the process and exit back to the menu.
-
args: (Optional) An array containing the list of string arguments.
-
cwd: (Optional) Working directory for the command
-
env: (Optional) An object with key-value pairs to set as environment for the process. The appLauncher automatically loads the LANG environment variable with the language selected in the menu, but it can be overriden through this setting.
-
shell (Optional, default: false) If
true
the command will be run in the default shell. A different shell can also be specified as a string. Iffalse
the command is run without a shell.
These are apps handled by a "Remote Launcher" registered by a Plug-In (see sample-remote-launcher.js
).
- main: ID of the remote launcher to call.
Iframe apps have access to an API that allows them to execute operations and get information from the host
appLauncher. API methods and properties are accesible through window.IMAGINARY.AppLauncher
,
check src/applauncher-api.js
for documentation.
Themes allow overriding default CSS styles and images. Each theme has a directory inside themes
where its
default.css
file and any extra assets are placed. If a theme is specified in the config.yml
file its
default.css
file will be loaded dynamically when the appLauncher starts.
Note that the theme CSS files are precompiled from SASS files placed in sass/themes/<theme name>
.
Plugins allow injecting JS and CSS into the AppLauncher. Put plugins in the plugins
directory. Each
plugin should have a directory and a plugin.js
file with the following format:
{
"id": "my-plugin-id",
"version": "v1.0",
"scripts": [
"js/path-to-js-file.js"
],
"stylesheets": [
"css/path-to-css-file.css"
]
}
Both scripts
and stylesheets
are optional arrays. Each script and stylesheet specified will get loaded after
the AppLauncher is built. Plugins can interact with the AppLauncher through the IMAGINARY.AppLauncher
global
object and the events published through IMAGINARY.AppLauncher.events
.
This app is built using several compilable languages:
- The HTML pages are built from pug template files.
- The CSS stylesheet is pre-compiled from sass files.
- The JS scripts are trans-compiled from es6 (ES2015) files.
To make any modifications re-compilation is necessary. You should install:
- node and npm
- yarn
- gulp (install globally)
Afterwards run the following in the command line:
yarn
After it runs succesfuly you can compile as needed:
-
sass (stylesheets)
gulp sass
-
scripts (ES6)
gulp scripts:prod
-
scripts (ES6, debug)
gulp scripts:dev
Designed and developed by Eric Londaits (eric.londaits@imaginary.org) for IMAGINARY.
Copyright 2017 IMAGINARY gGmbH
Licensed under the Apache License, Version 2.0.
See the LICENSE and NOTICE files for more details.