componentjs-mvc

ComponentJS MVC =============== Model-View-Controller Component Roles. <img src="https://nodei.co/npm/componentjs-mvc.png?downloads=true&stars=true" alt=""/> <img src="https://david-dm.org/rse/componentjs-mvc.png" alt=""/> About ----- [ComponentJS](https://componentjs.com/) is a generic hierarchical component orchestration library. It has no direct notion of any component roles, although it was designed with the roles of Ralf S. Engelschall's Model-View-Controller/Component-Tree (MVC/CT) pattern in mind. ComponentJS MVC is an opinionated companion library to [ComponentJS](https://componentjs.com/), providing ECMAScript 6 abstract classes for implementing the classes of ComponentJS backing objects by using the distinct Model, View or Controller roles of the MVC/CT pattern. The abstract classes map the major and essential parts of the ComponentJS API onto local methods which then provide the ComponentJS functionality in a way which is slightly adjusted for convenience reasons and their distinct usage under MVC/CT. ComponentJS MVC is intended to simplify the programming of HTML5 Single-Page-Apps (SPA) in an Object-Oriented Programming (OOP) manner. Installation ------------ ```shell # with the help of the NPM package manager (primary approach) $ npm install componentjs-mvc # with the help of the YARN package manager (alternative approach) $ yarn add componentjs-mvc # with the help of the Bower package manager (obsolete approach) $ bower install componentjs-mvc ``` Usage ----- ### Main Procedure: ```js import $ from "jquery" import cs from "componentjs" import "componentjs/component.plugin.vue.js" import mvc from "componentjs-mvc" import SV from "./service" class App { static main () { /* fire up ComponentJS */ cs.bootstrap() cs("/").property("sv", new SV()) /* fire up ComponentJS MVC */ mvc.jQuery = $ mvc.ComponentJS = cs mvc.Plugin() mvc.latch("mask:vue-options", ({ id, options }) => { /* example: provide id to Vue-I18Next Vue plugin */ options.i18nextNamespace = id }) mvc.latch("mask:vue-result", ({ id, mask }) => { /* example: integrate Perfect-Scroll-Bar jQuery plugin */ $(".perfect-scroll-bar", mask.$el).perfectScrollbar({}) }) } } ``` ### Dialog Component: ```js import mvc from "componentjs-mvc" class View extends mvc.View { ... } class Model extends mvc.Model { ... } class Controller extends mvc.Controller { ... } ``` Application Programming Interface (API) --------------------------------------- ### Globals: - `import mvc from "componentjs-mvc"`: Load the ComponentJS-MVC library. - `mvc.ComponentJS = ...`: Configure ComponentJS-MVC to use a particular instance of the mandatory ComponentJS framework. By default ComponentJS-MVC uses the global symbol `ComponentJS`. - `mvc.jQuery = ...`: Configure ComponentJS-MVC to use a particular instance of the optional jQuery library. By default ComponentJS-MVC uses the global symbol `jQuery`. jQuery is necessary only if the `mvc.View::$()` method should be used. jQuery and jQuery-Markup are necessary only if the `mvc.View::mask()` method should be used with neither `template` nor `render` options. - `mvc.Plugin()`: Hook into ComponentJS as an `mvc` plugin to automatically mark dynamically created ComponentJS-MVC-based components with the proper marker for the ComponentJS debugger without having to override the `create()` method and this way cause a `super.create()` burden on the users of the ComponentJS-MVC classes. Call this once in your main procedure if you want proper colors in the ComponentJS debugger for ComponentJS-MVC-based components. ### Hooks: - `mvc.latch("mask:vue-options", (({ id, options }) => { ... })`: Hook into the `mvc.View::mask()` method just before `mask = ComponentJS::vue(options)` is called internally. Use this to set particular options for VueJS. For instance, use `mvc.latch("mask:vue-options", ({ id, options }) => { options.i18nextNamespace = id })` to set the I18N namespace when using VueJS and the Vue-I18Next plugin together. - `mvc.latch("mask:vue-result", (({ id, result }) => { ... })`: Hook into the `mvc.View::mask()` method just after `mask = ComponentJS::vue(options)` is called internally. Use this to post-process the VueJS instance. For instance, use `mvc.latch("mask:vue-result", (({ id, result }) => { $(".perfect-scroll-bar", mask.$el).perfectScrollbar({ ... }) })` to apply the jQuery Perfect-Scrollbar plugin. - `mvc.latch("establish:post-create", ({ id, comp, obj }) => { ... })`: Hook into the `mvc.Component::establish()` method after each component was created. Use this to post-adjust created components. The `comp` is the created component, `obj` the attached backing object derived from the arguments to `mvc.Component::establish()`. - `mvc.latch("establish:pre-destroy", ({ id, comp, obj }) => { ... })`: Hook into the `mvc.Component::demolish()` method before each component will be destroyed. Use this to pre-process components. The `comp` is the created component, `obj` the attached backing object derived from the arguments to `mvc.Component::establish()`. ### Classes: - `class Component extends mvc.Component { ... }`: Define an application Component class based on ComponentJS-MVC's Component class (usually not directly used in regular applications, but exposed for completeness reasons). - `class View extends mvc.View { ... }`: Define an application View class based on ComponentJS-MVC's View class. The `mvc.View` class inherits from the `mvc.Component` class. - `class Model extends mvc.Model { ... }`: Define an application Model class based on ComponentJS-MVC's Model class. The `mvc.Model` class inherits from the `mvc.Component` class. - `class Controller extends mvc.Controller`: Define an application Controller class based on ComponentJS-MVC's Controller class. The `mvc.Controller` class inherits from the `mvc.Component` class. ### Methods (Component/View/Model/Controller Classes): - `mvc.Component::cs(...): ComponentJS`: Use the configured ComponentJS by just passing-through execution to ComponentJS. Use this in case you want to directly access the ComponentJS API from within a ComponentJS-MVC component. - `mvc.Component::establish(anchor?: Component, tree: String, classes: Object|Object[], autoincrease?: Boolean = true, autodecrease?: Boolean = false): mvc.Component`: This is a convenience wrapper around `ComponentJS::create()`. It internally basically calls `mvc.ComponentJS(this[, anchor]).create(tree, classes.map((Clz) => typeof Clz === "function" ? new Clz() : Clz))` and remembers the created components by their id for forthcoming use via `mvc.Component::my()`. It also calls `ComponentJS::state_auto_increase(autoincrease)` and `ComponentJS::state_auto_decrease(autodecrease)` on all created components. - `mvc.Component::demolish(id?: String): mvc.Component`: This is a convenience wrapper around `ComponentJS::destroy()`. It either destroys just the specified component (by id) or all components previously created with `mvc.Component::establish()`. - `mvc.Component::my(id: String): ComponentJS`: This fetches (by id) a particular component previously created with `mvc.Component::establish()`. - `mvc.Component::exists(id: String): ComponentJS`: This checks (by id) whether a particular component previously was created with `mvc.Component::establish()` and was still not destroyed with `mvc.Component::demolish()`. - `mvc.Component::state(...args: any[]): ComponentJS`: This is a convenience wrapper around `ComponentJS::state()`. The `args` positional arguments are just passed-through. The return value is the value of `ComponentJS::state()`. - `mvc.Component::guard(...args: any[]): ComponentJS`: This is a convenience wrapper around `ComponentJS::guard()`. The `args` positional arguments are just passed-through. The return value is the value of `ComponentJS::guard()`. - `mvc.Component::await(...args: any[]): ComponentJS`: This is a convenience wrapper around `ComponentJS::await()`. The `args` positional arguments are just passed-through. The return value is the value of `ComponentJS::await()`. - `mvc.Component::spool(func: Function, options?: Object): mvc.Component`: This is a convenience wrapper around `ComponentJS::spool()`. It internally basically calls `mvc.ComponentJS(this).spool({ name: mvc.ComponentJS(this).state(), ctx: this, func: func, ...options })`. The twist of this wrapper is that it automatically uses the component state based spool. - `mvc.Component::observe(name: String|String[], func: Function, options?: Object): mvc.Component`: This is a convenience wrapper around `ComponentJS::observe()`. It internally basically calls `mvc.ComponentJS(this[, "model"]) .observe({ name, func, spool: mvc.ComponentJS(this).state(), noevent: true, ...options })`. The twists of this wrapper are: it performs automatical spooling, uses no event argument in the `func` callback and automatically steps down to a `model` child if `this` is a `mvc.Controller`. Additionally, instead of a single `name`, it allows you to pass an array of names. - `mvc.Component::value(...args: any[]): any`: This is a convenience wrapper around `ComponentJS::value()`. It internally basically calls `mvc.ComponentJS(this[, "model"]) .value(...args)`. The main twist of this wrapper is: it automatically steps down to a `model` child if `this` is a `mvc.Controller`. - `mvc.Component::touch(...args: any[]): mvc.Component`: This is a convenience wrapper around `ComponentJS::touch()`. It internally basically calls `mvc.ComponentJS(this[, "model"]) .touch(...args)`. The main twist of this wrapper is: it automatically steps down to a `model` child if `this` is a `mvc.Controller`. - `mvc.Component::subscribe(name: String|String[], func: Function, options?: Object): mvc.Component`: This is a convenience wrapper around `ComponentJS::subscribe()`. It internally basically calls `mvc.ComponentJS(this).subscribe({ name, func, spool: mvc.ComponentJS(this).state(), noevent: true, capturing: false, spreading: false, bubbling: true, ...options })`. The twists of this wrapper are: it performs automatical spooling, uses no event argument in the `func` callback, disables capturing and spreading, and enables bubbling. Additionally, instead of a single `name`, it allows you to pass an array of names. - `mvc.Component::publish(name: String, args: any[], options?: Object): any`: This is a convenience wrapper around `ComponentJS::publish()`. It internally basically calls `mvc.ComponentJS(this).publish({ name, args, directresult: true, capturing: true, spreading: false, bubbling: true, ...options })`. The twists of this wrapper are: enables direct results, enables capturing and bubbling and disables spreading. - `mvc.Component::register(name: String|String[], func: Function, options?: Object): mvc.Component`: This is a convenience wrapper around `ComponentJS::register()`. It internally basically calls `mvc.ComponentJS(this).register({ name, func, spool: mvc.ComponentJS(this).state(), capturing: false, spreading: false, bubbling: true, ...options })`. The twists of this wrapper are: it performs automatical spooling, disables capturing and spreading, and enables bubbling. Additionally, instead of a single `name`, it allows you to pass an array of names. - `mvc.Component::call(name: String, args: any[], options?: Object): any`: This is a convenience wrapper around `ComponentJS::call()`. It internally basically calls `mvc.ComponentJS(this).call({ name, args, capturing: true, spreading: false, bubbling: true, ...options })`. The twists of this wrapper are: it enables capturing, disabled spreading and enables bubbling. ### Methods (View Class): - `mvc.View::$(selector: String, baseElement?: DOMElement): jQuery`: Use the configured jQuery by just passing-through execution to jQuery. Use this in case you want to directly manipulate the DOM via jQuery from within a View component. Use with caution, as jQuery and VueJS can conflict. - `mvc.View::mask(id: String, options?: any): VueJS`: Create a UI Mask with the help of VueJS. The `id` has to be unique within the UI, although it is not directly used by ComponentJS-MVC itself. It is intended to be passed through to the `mask:vue-options` hook and used there accordingly. The `options` are just passed-through to the `ComponentJS::vue()` method. Hence, this method requires the ComponentJS `vue` plugin to be loaded first. - `mvc.View::socket(ctx: Object, plug: Function, unplug: Function): Number`: `mvc.View::socket(options: { ctx: Object, plug?: Function, unplug?: Function, ... }): Number`: This is a convenience wrapper around `ComponentJS::socket()`. The `ctx`, `plug` and `unplug` positional arguments are just converted to the `options` form of method calling. If the `options` argument has no `spool` field, it is automatically created with the value of `mvc.ComponentJS(this).state()`. The return value is the value of `ComponentJS::socket()`. - `mvc.View::link(target: Object, socket: String): Number`: `mvc.View::link(options: { target: Object, socket: String, ... }): Number`: This is a convenience wrapper around `ComponentJS::link()`. The `target` and `socket` positional arguments are just converted to the `options` form of method calling. If the `options` argument has no `spool` field, it is automatically created with the value of `mvc.ComponentJS(this).state()`. The return value is the value of `ComponentJS::link()`. - `mvc.View::plug(object: Object): Number`: `mvc.View::plug(options: { object: Object, ... }): Number`: This is a convenience wrapper around `ComponentJS::plug()`. The `object` positional argument is just converted to the `options` form of method calling. If the `options` argument has no `spool` field, it is automatically created with the value of `mvc.ComponentJS(this).state()`. The return value is the value of `ComponentJS::plug()`. ### Methods (Model Class): - `mvc.Model::model(spec: Object): Void`: This just passes-through `spec` to the `ComponentJS::model()` method. ### Methods (Controller Class): - `mvc.Controller::sv(): Object`: This is a short-hand for `mvc.ComponentJS(this).property("sv")` and simplifys the fetching of the underlying Service API, which beforehand should be placed into a property on the root component via `mvc.ComponentJS("/").property("sv", value)`. License ------- Copyright (c) 2016-2018 Ralf S. Engelschall (http://engelschall.com/) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.