nw-app-example
v1.0.7
Published
Example app for nw-skeleton framework
Downloads
3
Readme
nw-app-example
Example app for node-webkit (nwjs) framework nwfw/nw-skeleton
| Top | Usage | |:---:|:---:| | Features | Documentation | | Components | App state | | App data | User data | | Mixed context | Clipboard | Base classes | CSS config files | | Easy extending | Internationalization | Logging | | Themes | Controlled initialization / shutdown | Menus / tray | Configuration | Resetting configuration and / or data |
Basic info
For more info, help and howto refer to 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 module. It has two 'main' components:
- nw-app-test - A test component that allows you to experiment with built-in framework functionailties
- nw-canvas-playground - An example async component that renders a drawing in
<canvas>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, node.js and nwjs.io if you don't have those already installed
- Clone this repository -
git clone https://github.com/nwfw/nw-app-example.git - Execute
npm install - Run with
nw .(Mac/Linux) ornw.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 keyboard shortcuts
- Desktop notifications
- Application notifications
- Cancellable application operations functionality with optional progress bar indicator
- Configurable application tray icon and menus
- Configurable application (window) menus
- Configurable command-line parameters
- User data saving in localStorage
- Persistent window position/width/height between sessions
- Custom icons/app info with 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 through config file 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 Vue.js mixins, filters, directives etc.
- Theme support with live theme switching and optional themes as node modules
- Configurable 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 message levels and grouping in console)
- Per-class configurable debug output
- User messages (with stack traces and configurable message levels)
- Per-class configurable 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 and online generated documentation for nw-app-example here
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 - 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 - base class for application classes (i.e. ones that run in node/browser context)
- 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 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 <head> 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 variables hasAppMenu and menuData.
| 
|
|:---:|
| Tray icon and menu example |
Tray support w/icons is also available and fully configurable through configuration file variables hasTrayIcon and trayData.
Modal dialogs
| 
|
|:---:|
| Modal language editor |
Easily extendable and highly configurable, 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. Default configuration file looks like:
{
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)
- Command line
resetData- resets (deletes) saved user data- Command line
nw . resetData(Mac/Linux)nw.exe . resetData(Windows)
- Command line
resetAll- resets (deletes) both user data and saved configuration- Command line
nw . resetAll(Mac/Linux)nw.exe . resetAll(Windows)
- Command line