node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

msg-js-spa-framework

msg-js-spa-framework

JavaScript SinglePageApp(SPA) Framework is a lightweight framework for building SPA libraries.

Purpose

The msg-js-spa-framework is the optional large HTML5 Rich-Client framework for providing common functionality to the applications, either by itself or through embedded third-party libraries and frameworks.

Major goals are:

  • Definition of a standard set of third-party libraries and frameworks used for SPA development
  • Using the msg-js-spa-framework should therefor minimize the configuration time of the SPA library building in concrete SPA projects

Getting started

To build an SPA project based on msg-js-spa-framework you have to install it via npm (shell or package.json):

npm install msg-js-spa-framework --save-dev

Once it is installed, add a delivery.yaml to the SPA's root folder. msg-js-spa-framework is based upon delivery-packer which handles the library artifact creation. Based on delivery.yaml files the delivery artifact can be assembled.

So basically msg-js-spa-framework only assembles the proper JavaScript frameworks to a delivery artifact. And due to the fact that delivery-packer is modular - concrete SPA projects can take advantage of msg-js-spa-framework by simply importing it into their delivery.yaml.

To shorten the ramp-up time you can fork msg-js-spa-skeleton and start with a fresh SPA environment including some examples and documentation.

import:
# use the msg-js-spa-framework as base 
- msg-js-spa-framework
# you might add new delivery parts needed by the SPA project 
- {path_to_project_deliverables}/**/*.yaml
 
build:
# you might exclude deliverables from the msg-js-spa-framwork if you want/have to (note they all start with spa-fw.) 
- "!spa-fw.componentjs"
# and add proper replacements on your own - just ensure that those alias names are registered 
- {yournamespace}.angularjs

If that delivery.yaml is fully configured - run the delivery-packer either with the grunt plugin or with the command line interface (see delivery-packer).

Include the artifact output of the delivery-packer into your SPA HTML file.

Behind the scene

Creating an UI Application typically considers all functional requirements and tries to map those to an technical - developable - view.

Typical functional requirements and a possible layer concept as a technical view will be detailed further below.

Functional requirements

Single page applications face alot of functional requirements like:

  • DOM-Manipulation
  • HTML Markups
  • HTML Styling using CSS
  • Responsive Design
  • Browser navigation
  • Drag & Drop
  • Browser differences and incompatibilities
  • Internationalization / Localization
    • Dates
    • Numbers
    • Texts
  • Error handling
  • Keyboard control
  • Touch and gesture control
  • Symbols, icons and images
  • UI Widgets
  • and many more

12 layers of an UI application

Coming from the users point of view and going thru the UI application until the backend takes over we face different layers of concern:

  1. Interaction Concept:
    e.g. Mouse, Keyboard, Touchscreen, Gesture, Dialog Flow

  2. Optical Theme:
    e.g. Shape, Color, Gradient, Shadow, Font, Icon

  3. Interface States:
    e.g. Rendered, Enabled, Visible, Focused, Animated, Warning, Error

  4. Interface Elements:
    e.g. Icon, Label, Text Paragraph, Image, Form, Text-Field, Text-Area, Date Picker, Toggle, Radio Button, Checkbox, Select List, Slider, Progress Bar, Hyperlink, Popup Menu, Dropdown Menu, Toolbar, Tab, Pill, Breadcrumb, Pagination, Badge, Alert

  5. Interface Layouting:
    e.g. Responsive Design, Media Query, Panel, Modal, Frame, Grid, Table, Padding, Border, Margin, Alignment, Force, Magnetism

  6. Mask Rendering:
    e.g. Markup Generation, Value Formatting, Virtual DOM

  7. Data Binding:
    e.g. Reactive, Observer, Value Converting, Unidirectional, Bidirectional, Incremental

  8. Presentation Model:
    e.g. Parameter, Command, State, Data, Event

  9. Dialog Control:
    e.g. Service, Event, Model, Socket

  10. Dialog Structure:
    e.g. Model, View, Controller, Hierarchical Composition

  11. Business Model:
    e.g. Entity, Field, Relationship

  12. Backend Communication:
    e.g. Request/Response, Synchronization, Push, Pull, Pulled-Push

Using a single framework like AngularJS or ExtJS often does not address all layers of the UI application and you end up in taking third party libraries into your application.

Standard set of frameworks

msg-js-spa-framework cherry picks the best frameworks to cover most of the layers. Some layers will not be handled by msg-js-spa-framework since they are too application specific and should not be handled globally like 'Interface Elements' or 'Optical Theme'.

Each concrete SPA must fill this layers with proper libraries or frameworks on its own. Take a look at msg-js-spa-widgets if you need assistance for layer 'Interface Elements' and 'Optical Theme'.

The following table lists all frameworks and libraries mapped to the 12 UI layers (technical view). Some libraries could not be mapped to a specific UI layer since they cover a global purpose needed by web applications like browser incompatibilities or JavaScript language basics.

Framework Version Relevance global purpose
0.2.3 JS Browser incompatibilities
4.5.9 JS
1.1.2 JS
1.0.0 JS
5.0.0 CSS
3.3.1 JS Browser feature detection
4.16.5 JS Array handling
0.2.0 JS HTML Encoding/Decoding
3.4.6 JS Promises
Framework Version Relevance Layer
1.6.0 JS 1. Interaction Concept - Keyboard
2.0.8 JS 1. Interaction Concept - Touch, Gesture
3.5.2 CSS 3. Interface States
6. Mask Rendering
2.2.4 JS 3. Interface States
6. Mask Rendering
7. Data Binding (manual)
1.0.36 JS 6. Mask Rendering
2.0.3 JS 6. Mask Rendering
7. Data Binding (programmatic)
4.0.5 JS 6. Mask Rendering - Template engine
2.15.2 JS - Date 6. Mask Rendering - Internationalization / Localization
1.5.3 JS - Number 6. Mask Rendering - Internationalization / Localization
3.4.4 JS - String 6. Mask Rendering - Internationalization / Localization
1.2.0 JS - String 12. Backend Communication - Internationalization / Localization
1.1.0 HTML DOM 6. Mask Rendering - Internationalization / Localization

Additionally abstract classes and traits for ComponentJS are provided.
See Standard set of abstract classes, traits and components for detailed information.
1.4.3 JS 8. Presentation Model
9. Dialog Control
10. Dialog Structure
1.3.2 JS 11. Business Model
4.4.5 JS 12. Backend Communication - AJAX
1.5.1 JS 12. Backend Communication - WebSockets

Standard set of abstract classes, traits and components

Next to the libraries and frameworks the msg-js-spa-framework provides abstract classes, traits (mixins) and components.

abstract classes

For each part of a component (controller, model and view) a abstract class is provided. They represent an abstract layer to work with ComponentJS. Every component must extend from this abstract class.

  • controller: app.fw.abstract.ctrl
  • model: app.fw.abstract.model
  • view: app.fw.abstract.view

traits

The msg-js-spa-framework provides some helpful traits. Some of them are already mixed in in the components of the msg-js-spa-framework, some can be mixed in to your specific components, if needed.

i18next

This trait handles the loading of the i18next-keys from the backend. By default this trait is included by the root-component.

The default value for the resourcePath is 'app/{{lng}}-translation.json', but can be overwritten from the specific root component of your application.

The specific root component must implement the function 'userLanguage' to return the current language of the application.

  • controller: app.fw.trait.root.i18next.ctrl

serviceError

The default error handling callback for service methods is available through mixing in this trait. It is already mixed in the abstract component. So of the error handling is taking care due extending from this component.

  • controller: app.fw.trait.abstract.serviceError.ctrl

When the result object is an error object, this method takes care of the error analysis and it creates the proper messages and throws it to the top level error handler with publish("fw:handleError"). To react to the error, the event "fw:handleError" must be subscribed.

registerAPI

Sometimes it is neccassary that the controller can asked its view about a markup. If that is needed, this trait must be mixed in, to the specific view. Generally a Controller should only call a registered method of the view to get a views markup.

  • view: app.fw.trait.abstract.registerAPI.view

components

Each application needs a service and a root component. The msg-js-spa-framework provides a service and a root component with some basic functionalities that can be extended.

The service component only should recieve events fromt the root component. For this purpose it provides an wrapper function 'registerService'. For the communication between the service and the root component, the root component provides the counterpart of this wrapper function - 'subscribeDataService'.

service

The service component, is the only component that is not devided into controller, model and view, because it does not need a own model and a user interface. It is neccassary to extend from this service component to use its provided function.

  • app.fw.sv

Its major task is the communictaion with the backend. Therefore the method registerService (methodName, serviceName, serviceFunction, callbackFunction[optional]) is provided.

// EXAMPLE for calling registerService:
// the variable self.serviceRoot was defined before

self.registerService('GET', 'readClaimPositions', function (client, claimNumber, callback) {
	return {
    	options: {{object: options}},
        serviceURL: {{string: URL resolved with given parameters "client" and "claimNumber"}},
        callback: callback
    };
});

The available options you can find at the documentation from qwest, as qwest is used internal for the service-calls. For default service options, the variable defaultServiceOptions is defined and set to {dataType: 'json'} by default. It is possible to overwrite this variable.

Furthermore it provides functions to set and get the service-root-URL and to get the service-URL of a given service.

root

A specific root component is responsible for a lot of tasks.

This basic root component provides the handling of window resizing. It provides a function for all components to read the service-URL from a specific service from the service component. Furthermore it includes the traits app.fw.trait.root.i18next.ctrl and app.fw.trait.abstract.serviceError.ctrl.

  • controller: app.fw.root.ctrl
  • model: app.fw.root.model
  • view: app.fw.root.view

Style Mixins

The `msg-js-spa-framework` includes some useful mixins for styling as well. This can be used through importing the file *spa-fw.less* in your .less-files:
	@import "../../../../node_modules/msg-js-spa-framework/src/app/spa-fw";

Mockdata Registry

A mockdata registry is also delivered by the `msg-js-spa-framework`. To use it, it needs to be required:
	require('msg-js-spa-framework/mockdata-registry')