Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nwfw/nw-app-example
Example app based on nw-skeleton framework
https://github.com/nwfw/nw-app-example
chromium desktop-app javascript nodejs nwjs nwjs-application vuejs2
Last synced: 8 days ago
JSON representation
Example app based on nw-skeleton framework
- Host: GitHub
- URL: https://github.com/nwfw/nw-app-example
- Owner: nwfw
- Created: 2017-08-15T11:48:43.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-11-25T00:18:17.000Z (about 7 years ago)
- Last Synced: 2024-11-15T08:07:29.244Z (about 1 month ago)
- Topics: chromium, desktop-app, javascript, nodejs, nwjs, nwjs-application, vuejs2
- Language: JavaScript
- Homepage:
- Size: 1.42 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# nw-app-example #
Example app for node-webkit (nwjs) framework [nwfw/nw-skeleton](https://github.com/nwfw/nw-skeleton "nw-skeleton")
| [Top](#nw-app-example) | [Usage](#usage) |
|:---:|:---:|
| [Features](#features) | [Documentation](#documentation) |
| [Components](#components) | [App state](#app-state) |
| [App data](#app-data) | [User data](#user-data) |
| [Mixed context](#mixed-context) | [Clipboard](#clipboard) | [Base classes](#base-classes) | [CSS config files](#css-config-files) |
| [Easy extending](#easy-extending) | [Internationalization](#internationalization) | [Logging](#logging) |
| [Themes](#themes) | [Controlled initialization / shutdown](#controlled-initialization--shutdown) | [Menus / tray](#menus--tray) | [Configuration](#configuration) | [Resetting configuration and / or data](#resetting-configuration-and--or-data) |
## Basic info ##
> __For more info, help and howto refer to [nw-skeleton wiki](https://github.com/nwfw/nw-skeleton/wiki "nw-skeleton wiki")__
This example application shows some of core framework functionalities such as local component overrides and components and/or themes as modules. It relies on themes from [nw-themes](https://github.com/nwfw/nw-themes "nw-themes") module. It has two 'main' components:
* [nw-app-test](https://github.com/nwfw/nw-app-test "nw-app-test") - A test component that allows you to experiment with built-in framework functionailties
* [nw-canvas-playground](https://github.com/nwfw/nw-canvas-playground "nw-canvas-playground") - An example _async_ component that renders a drawing in `` HTML element and allows you to play around with it.
Each component has its own storage and config namespace. Also, __app-main__ component from nw-skeleton is overriden here so it shows interface to pick between __nw-app-test__ and __nw-canvas-playground__ components.
## Usage ##
* Install [git](https://git-scm.com/downloads "git"), [node.js](https://nodejs.org/en/download/ "node.js") and [nwjs.io](https://nwjs.io/downloads/ "nwjs.io") if you don't have those already installed
* Clone [this repository](https://github.com/nwfw/nw-app-example "nw-app-example") - `git clone https://github.com/nwfw/nw-app-example.git`
* Execute `npm install`
* Run with `nw .` (Mac/Linux) or `nw.exe .` (Windows)
## Features ##
* Main framework features:
* I18N (internationalization) with integrated translating and language editing system
* Mac/windows/linux support
* Transparent / frameless window support
* Integrated, overridable window controls and menus
* [Configurable](#configuration) keyboard shortcuts
* Desktop notifications
* Application notifications
* Cancellable application operations functionality with optional progress bar indicator
* [Configurable](#configuration) application tray icon and menus
* [Configurable](#configuration) application (window) menus
* [Configurable](#configuration) command-line parameters
* User data saving in localStorage
* Persistent window position/width/height between sessions
* Custom icons/app info with [nwjs-builder-phoenix](https://github.com/evshiron/nwjs-builder-phoenix "nwjs-builder-phoenix") or nwjs building tool of your choice
* Frontend (UI) features:
* Built-in modal dialog functionality with callbacks
* Frontend application and Vue components structure completely [configurable](#configuration) through [config file](#configuration) with components-as-modules option and async component support.
* All framework Vue components can be overriden simply by creating dirs/files with same names in applications that use the framework.
* Support for [configurable](#configuration) Vue.js mixins, filters, directives etc.
* Theme support with live theme switching and optional themes as node modules
* [Configurable](#configuration) external css/js resource loading
* Optional separate debug window for maximum readability
* Other framework features:
* __ES2016__ ready (async/await, arrow functions, classes etc.)
* Most styles can be changed through CSS variables
* Optional CSS compiling (postcss)
* Optional live CSS reloading when debug is on
* Logging:
* Debug messages (with stack traces, [configurable](#configuration) message levels and grouping in console)
* Per-class [configurable](#configuration) debug output
* User messages (with stack traces and [configurable](#configuration) message levels)
* Per-class [configurable](#configuration) user message output
* Exporting debug/user messages to JSON files for later analysis
* Log viewer for saved user/debug logs
* Planned framework features for the future:
* [ ] Remote (binary and non-binary) js loading
* [ ] Automatic updates
## Documentation ##
You can see online generated documentation for nw-skeleton framework [here](https://nwfw.github.io/nw-skeleton-documentation/ "nw-skeleton documentation") and online generated documentation for nw-app-example [here](https://nwfw.github.io/nw-app-example-documentation/ "nw-app-example documentation")
To generate documentation locally, run `npm run doc` in application directory which will generate documentation in './doc'
## Components ##
Vue.js components are organized in directories:
* __global__ - for global components
* __app__ - for "regular" components
* __modal__ - for modal-dialog components (those will also be registered as global)
|  |
|:---:|
| System window-controls component |
Components can also be loaded as external npm modules. Each component can have its state file that gets merged with app state data. System will also automatically load css files with same name as the component. If necessary, component configuration can include any number of custom css files.
## App state ##
All data for the app is stored under single appState object so components and other code can easily share data. Separate file for application data is provided since that data structure varies from app to app.
## App data ##
Stored in separate file, this object is to be used as temporary current app instance storage.
## User data ##
This object can easily be saved or loaded via localStorage helper in order to preserve data for next sessions
## Mixed context ##
Using nwjs.io mixed node/browser context, you can easily work with filesystem, network, websockets or DOM from single Vue component or javascript class.
## Clipboard ##
Clipboard helper makes it easy to cut/copy/paste text without having to rely on OS support - works same on all platforms (Win, Mac, Linux)
## Base classes ##
Base classes (all system objects extend them) contain all necessary methods and properties for easy coding such as translations, easy helper access, logging and notifying user whether through application or desktop notifications (enabled in nwjs.io by default). There are three of them:
* [BaseClass](https://nwfw.github.io/nw-skeleton-documentation/appWrapper.BaseClass.html "BaseClass") - main base class that contains common methods for extended classes. This one should not be extended directly, instead one of the classes below are used when creating new classes.
* [AppBaseClass](https://nwfw.github.io/nw-skeleton-documentation/appWrapper.AppBaseClass.html "AppBaseClass") - base class for application classes (i.e. ones that run in node/browser context)
* [MainBaseClass](https://nwfw.github.io/nw-skeleton-documentation/mainScript.MainBaseClass.html "MainBaseClass") - base class for main script classes (i.e. ones that run in main nwjs.io script context)
## CSS config files ##
All themes as well as system itself contain config CSS files that declare CSS variables that can be used in all CSS files - changing appearance and UX is wasy as setting the CSS variable to desired value
## Easy extending ##
Using configuration variable `appConfig.mainComponent`, you can easily configure what will be base view for your app. Since components themselves can extend configuration through their componentState file (or using separate config file for npm-module components) you can even override main component from component configuration itself.
## Internationalization ##
Using simple JS objects for language definitions and internationalization, it is easy to adapt the app for all user needs. With auto-scan and auto-clear (auto-trim) functionality, adding new or removing unneeded translations and/or languages is easy and requires no coding or programming skills.
## Logging ##
With [configurable](#configuration) message levels (defaults are debug, info, warning and error) debugging and filtering debug logs is easy. Logs can be saved in JSON format for later analysis, and each log message can contain stack trace for easier bug fixing.
|  |
|:---:|
| Separate debug window |
Both user messages and debug logs can be configured to be automatically saved as files for later analysis as well.
## Themes ##
Each theme can contain config css file that overrides system css config. In addition, you can define your own css files that will be loaded beside system ones, override system css files set css file loading order etc. You can even set your own js files that will be included into application `` tag if theme requires them.
By setting a single flag `liveCss` in configuration file, you can enable live CSS reloading to make styling easier. Live CSS reload works with or without CSS compiling, but only when debug is enabled.
## Controlled initalization / shutdown ##
Application will wait for certain flags in `appState` to be set before it presents its window to the user.
Each of the main JS classes can have async `initialize` and `finalize` methods that will be called upon application initialization or finalization. In addition, they can also have async `shutdown` method that will be automatically called before application closes.
## Menus / Tray ##
You can easily configure application menus using just [config file](#configuration) variables `hasAppMenu` and `menuData`.
|  |
|:---:|
| Tray icon and menu example |
Tray support w/icons is also available and fully [configurable](#configuration) through configuration file variables `hasTrayIcon` and `trayData`.
## Modal dialogs ##
|  |
|:---:|
| Modal language editor |
Easily extendable and highly [configurable](#configuration), modal dialog components can be used for all types of tasks - from loading/saving files to displaying warnings / queries on app closing. Modal dialogs can display app notifications and progress bar if needed, since modal mask can obscure those important UI elements. You can set callbacks for 'onBeforeOpen', 'onOpen', 'onBeforeClose', 'onClose', 'onCancel' and 'onConfirm' events.
## Configuration ##
Almost all application aspects can be controlled through configuration. Configuration variables are explained in [JSDoc documentation](https://nwfw.github.io/nw-skeleton-documentation/global.html#AppWrapperConfig).
Default configuration file looks like:
```javascript
{
main: {
debug: {
enabled: true,
debugToWindow: false,
debugLevel: 2,
displayTimestamps: true,
debugToFile: true,
saveStacksToFile: true,
debugToFileAppend: false,
debugLogFilename: './app/var/log/main-debug.log',
},
},
wrapper: {
appFile: './node_modules/nw-skeleton/app-wrapper/js/app',
themeBaseDir: './node_modules/nw-skeleton/app-wrapper/css/themes',
componentCodeRegex: /\.js$/,
componentDirectories: {
component: ['./node_modules/nw-skeleton/app-wrapper/components/app/'],
globalComponent: ['./node_modules/nw-skeleton/app-wrapper/components/global/', './node_modules/nw-skeleton/app-wrapper/components/form'],
modalComponent: ['./node_modules/nw-skeleton/app-wrapper/components/modal/']
},
systemHelperDirectories: ['./node_modules/nw-skeleton/app-wrapper/js/helper/system/'],
helperDirectories: ['./node_modules/nw-skeleton/app-wrapper/js/helper/'],
mixinRoot: './node_modules/nw-skeleton/app-wrapper/js/mixin/',
mixinExtensionRegex: /\.js$/,
directiveRoot: './node_modules/nw-skeleton/app-wrapper/js/directive/',
directiveExtensionRegex: /\.js$/,
filterRoot: './node_modules/nw-skeleton/app-wrapper/js/filter/',
filterExtensionRegex: /\.js$/,
translationExtensionRegex: /\.i18n\.js$/,
translationsRoot: './app/data/translations/',
componentMapping: {
'app-window': {
name: 'app-window',
components: {
'app-header': {
name: 'app-header',
components: {
'window-controls': {
name: 'window-controls',
components: {
'theme-select': {
name: 'theme-select'
},
'language-select': {
name: 'language-select'
}
}
},
}
},
'app-main': {
name: 'app-main'
},
'app-footer': {
name: 'app-footer',
}
}
}
},
},
minPauseDuration: 10,
shortPauseDuration: 100,
mediumPauseDuration: 250,
longPauseDuration: 700,
longerPauseDuration: 1000,
cancelOperationTimeout: 30000,
appConfig: {
appFile: null,
appSubFiles: [],
mainComponent: 'app-main',
tmpDataDir: './app/var',
showInitializationStatus: true,
showInitializationProgress: true,
themeBaseDir: './app/css/themes',
cssCompiledFile: '/app/var/css/dist.css',
initCssFiles: [
'/node_modules/nw-skeleton/app-wrapper/css/config.css',
],
cssFiles: [
'/node_modules/nw-skeleton/app-wrapper/css/fonts.css',
'/node_modules/nw-skeleton/app-wrapper/css/layout.css',
'/node_modules/nw-skeleton/app-wrapper/css/style.css',
'/node_modules/nw-skeleton/app-wrapper/css/transitions.css'
],
overrideCssFiles: [],
initJsFiles: [],
jsFiles: [
'/node_modules/nw-skeleton/app-wrapper/js/lib/ext/vue.js'
],
debugCssFiles: [
'/node_modules/nw-skeleton/app-wrapper/css/debug.css'
],
debugJsFiles: [],
componentMapping: {},
componentModules: {
component: [],
globalComponent: [],
modalComponent: []
},
mixinRoot: './app/js/mixin/',
directiveRoot: './app/js/directive/',
directiveExtensionRegex: /\.js$/,
disableRightClick: true,
hasAppMenu: false,
menuData: {
editMenu: {
menuItem: {
label: 'Edit',
method: 'noop'
},
children: [
// {
// menuItem: {
// label: 'Undo',
// method: 'helpers.clipboardHelper.undo',
// shortcut: {
// key: 'z',
// modifiers: {
// ctrl: true
// }
// }
// }
// },
// {
// menuItem: {
// label: 'Redo',
// method: 'helpers.clipboardHelper.redo',
// shortcut: {
// key: 'z',
// modifiers: {
// ctrl: true,
// shift: true
// }
// }
// }
// },
{
menuItem: {
type: 'separator'
},
children: []
},
{
menuItem: {
label: 'Cut',
method: 'helpers.clipboardHelper.cut',
shortcut: {
key: 'x',
modifiers: {
ctrl: true
}
}
}
},
{
menuItem: {
label: 'Copy',
method: 'helpers.clipboardHelper.copy',
shortcut: {
key: 'c',
modifiers: {
ctrl: true
}
}
}
},
{
menuItem: {
label: 'Paste',
method: 'helpers.clipboardHelper.paste',
shortcut: {
key: 'v',
modifiers: {
ctrl: true
}
}
}
},
{
menuItem: {
label: 'Select all',
method: 'helpers.clipboardHelper.selectAll',
shortcut: {
key: 'a',
modifiers: {
ctrl: true
}
}
}
}
]
}
},
hasTrayIcon: false,
trayData: {},
allowFullscreen: true,
hideFullscreenHeader: true,
hideFullscreenFooter: true,
windowConfig: {
left: null,
top: null,
width: null,
height: null,
fullscreen: false,
},
},
configData: {
uneditableConfig: [],
editableConfig: [],
noReloadConfig: [],
reloadConfig: [],
ignoreUserConfig: [
'appConfig.menuData',
'appConfig.componentMapping',
'appConfig.appSubFiles',
'userMessages.forceUserMessages',
'debug.forceDebug',
'appInfo',
'currentLanguage',
'currentLanguageName',
'currentLocale',
],
defaultVar: {
editable: true,
reload: true,
control: 'text'
},
vars: {
app: {
editable: false,
reload: true
},
appConfig: {
editable: true,
reload: false
},
logDir: {
editable: false,
reload: true
},
varDir: {
editable: false,
reload: true
},
'debug.debugMessagesFilename': {
editable: false,
reload: true
},
'userMessages.userMessagesFilename': {
editable: false,
reload: true
},
'userMessages.userMessageLevel': {
editable: true,
reload: false,
type: 'string',
control: 'select',
controlData: {
items: {
1: 'debug',
2: 'info',
3: 'warning',
4: 'error'
}
}
},
'debug.debugLevel': {
editable: true,
reload: false,
type: 'string',
control: 'select',
controlData: {
items: {
1: 'debug',
2: 'info',
3: 'warning',
4: 'error'
}
}
},
'debug.enabled': {
editable: true,
reload: false
},
'debug.hideDebug': {
editable: true,
reload: false
},
'logger.messageLevels': {
editable: false,
reload: true
},
windowWidth: {
editable: false,
reload: false
},
windowHeight: {
editable: false,
reload: false
},
componentMapping: {
editable: false,
reload: true
},
theme: {
editable: true,
reload: false
},
currentLanguage: {
editable: true,
reload: false,
type: 'string',
control: 'select',
controlData: {
items: {
'en-US': 'English',
'sr-Latn-RS': 'Srpski',
'sr-Cyrl-RS': 'Српски',
}
}
},
currentLocale: {
editable: true,
reload: false,
type: 'string',
control: 'select',
controlData: {
items: {
'en-US': 'English',
'sr-Latn': 'Srpski',
'sr-Cyrl': 'Српски',
}
}
},
'debug.messagesExpanded': {
editable: true,
reload: false
},
'userMessages.messagesExpanded': {
editable: true,
reload: false
},
'debug.displayTimestamps': {
editable: true,
reload: false
},
'userMessages.displayTimestamps': {
editable: true,
reload: false
},
'debug.forceDebug': {
editable: false,
reload: true
},
'userMessages.forceUserMessages': {
editable: false,
reload: false
},
compileCss: {
editable: true,
reload: false
},
liveCss: {
editable: true,
reload: false
},
}
},
varDir: './app/var',
logDir: './app/var/log',
currentLanguageName: 'English',
currentLanguage: 'en-US',
currentLocale: 'en',
allowLanguageChange: true,
autoAddLabels: true,
themeModules: [],
theme: 'dark',
allowThemeChange: true,
liveCss: false,
compileCss: false,
appNotifications: {
userMessageDuration: 3000,
duration: 5000,
},
logger: {
messageLevels: {
'debug': 1,
'info': 2,
'warning': 3,
'error': 4
},
},
userMessages: {
animateMessages: true,
hideUserMessages: false,
userMessageLevel: 3,
maxVisibleUserMessages: 200,
maxUserMessages: 5000,
userMessagesToFile: true,
saveStacksToFile: true,
userMessagesToFileAppend: false,
userMessagesFilename: './app/var/log/user-messages.log',
messagesExpanded: false,
displayTimestamps: true,
forceUserMessages: {
AppConfig: false,
AppNotificationsHelper: false,
AppOperationHelper: false,
AppTemplates: false,
AppTranslations: false,
AppWrapper: false,
ClipboardHelper: false,
ComponentHelper: false,
DebugHelper: false,
FileManager: false,
FormatHelper: false,
HtmlHelper: false,
KeyboardHelper: false,
MenuHelper: false,
ModalHelper: false,
StaticFilesHelper: false,
StorageHelper: false,
StyleHelper: false,
ThemeHelper: false,
UserDataHelper: false,
UserMessageHelper: false,
UtilHelper: false,
WindowManager: false,
WrapperApp: false
}
},
debug: {
animateMessages: true,
hideDebug: false,
enabled: true,
usage: false,
usageInterval: 500,
usageGraphs: false,
usageHistoryCount: 1000,
debugToFile: true,
saveStacksToFile: true,
debugToFileAppend: false,
debugMessagesFilename: './app/var/log/debug-messages.log',
messagesExpanded: false,
displayTimestamps: true,
devTools: true,
alwaysTrace: false,
debugLevel: 3,
maxVisibleDebugMessages: 200,
maxDebugMessages: 5000,
debugGroupsCollapsed: false,
passToMain: false,
debugWindowFile: './node_modules/nw-skeleton/app-wrapper/template/debug.html',
forceDebug: {
AppConfig: false,
AppNotificationsHelper: false,
AppOperationHelper: false,
AppTemplates: false,
AppTranslations: false,
AppWrapper: false,
ClipboardHelper: false,
ComponentHelper: false,
DebugHelper: false,
FileManager: false,
FormatHelper: false,
HtmlHelper: false,
KeyboardHelper: false,
MenuHelper: false,
ModalHelper: false,
StaticFilesHelper: false,
StorageHelper: false,
StyleHelper: false,
ThemeHelper: false,
UserDataHelper: false,
UserMessageHelper: false,
UtilHelper: false,
WindowManager: false,
WrapperApp: false
},
},
windowCloseTimeoutDuration: 15000,
windowReloadTimeoutDuration: 15000,
windowWidth: null,
windowHeight: null,
};
```
Configuration values can be easily changed by overriding them your app `config.js` file.
## Resetting configuration and / or data ##
There are three built-in command line parameters for cleaning up saved data:
* `resetConfig` - resets (deletes) saved Configuration
* Command line
* `nw . resetConfig` (Mac/Linux)
* `nw.exe . resetConfig` (Windows)
* `resetData` - resets (deletes) saved user data
* Command line
* `nw . resetData` (Mac/Linux)
* `nw.exe . resetData` (Windows)
* `resetAll` - resets (deletes) both user data _and_ saved configuration
* Command line
* `nw . resetAll` (Mac/Linux)
* `nw.exe . resetAll` (Windows)