Newton's Preposterous Miscalculation

    nw-app-example

    1.0.7 • Public • Published

    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
    Easy extending Internationalization
    Themes Controlled initialization / shutdown

    Example app screenshot

    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) 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 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
    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
    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 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
    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)
    • 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)

    Keywords

    none

    Install

    npm i nw-app-example

    DownloadsWeekly Downloads

    2

    Version

    1.0.7

    License

    MIT

    Last publish

    Collaborators

    • avatar