https://github.com/msg-systems/uica-stack
User interface component architecture (UICA) - Stack composition
https://github.com/msg-systems/uica-stack
Last synced: 5 months ago
JSON representation
User interface component architecture (UICA) - Stack composition
- Host: GitHub
- URL: https://github.com/msg-systems/uica-stack
- Owner: msg-systems
- License: mit
- Created: 2016-01-21T15:52:32.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2018-04-13T12:11:21.000Z (over 7 years ago)
- Last Synced: 2024-11-01T19:39:37.542Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 2.8 MB
- Stars: 4
- Watchers: 5
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# uica-stack
User Interface Component Architecture (UICA) Stack is a stack that can be used for lightweight building HTML5/JavaScript Single Page Application.
## Purpose
The `uica-stack` 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 `uica-stack` should therefor minimize the configuration time of the SPA library building in concrete SPA projects
## Getting started
To build an SPA project based on `uica-stack` you have to install it via npm (shell or package.json):
```shell
npm install uica-stack --save-dev
```
Once it is installed, add a `delivery.yaml` to the SPA's root folder. `uica-stack` is based upon [delivery-packer](https://github.com/msg-systems/delivery-packer) which handles the library artifact creation. Based on `delivery.yaml` files the delivery artifact can be assembled.
So basically `uica-stack` only assembles the proper JavaScript frameworks to a delivery artifact. And due to the fact that [delivery-packer](https://github.com/msg-systems/delivery-packer) is modular - concrete SPA projects can take advantage of `uica-stack` by simply importing it into their `delivery.yaml`.
To shorten the ramp-up time you can fork [uica-skeleton](https://github.com/msg-systems/uica-skeleton) and start with a fresh SPA environment including some examples and documentation.
```yaml
import:
# use the uica-stack as base
- uica-stack
# you might add new delivery parts needed by the SPA project
- {path_to_project_deliverables}/**/*.yaml
build:
# you might exclude deliverables from uica-stack if you want/have to (note they all start with uica.)
- "!uica.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](https://github.com/msg-systems/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](https://angularjs.org/) or [ExtJS](https://www.sencha.com/products/extjs/#overview) 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
`uica-stack` cherry picks the best frameworks to cover most of the layers. Some layers will not be handled by `uica-stack` 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 [uica-widgets](https://github.com/msg-systems/uica-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.3.0
JS
Browser incompatibilities
4.5.10
JS
1.1.2
JS
1.0.1
JS
7.0.0
CSS
3.5.0
JS
Browser feature detection
4.17.5
JS
Array handling
0.3.0
JS
HTML Encoding/Decoding
3.5.1
JS
Promises
Framework
Version
Relevance
Layer
1.6.1
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.38
JS
6. Mask Rendering
2.5.13
JS
6. Mask Rendering
7. Data Binding (programmatic)
4.0.11
JS
6. Mask Rendering - Template engine
2.20.1
JS - Date
6. Mask Rendering - Internationalization / Localization
2.0.6
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.6.1
JS
8. Presentation Model
9. Dialog Control
10. Dialog Structure
1.3.2
JS
11. Business Model
4.5.0
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 `uica-stack` 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 `uica-stack` provides some helpful traits. Some of them are already mixed in in the components of the `uica-stack`, 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 `uica-stack` 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](https://github.com/pyrsmk/qwest)**, as **[qwest](https://github.com/pyrsmk/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 `uica-stack` includes some useful mixins for styling as well. This can be used through importing the file *uica.less* in your .less-files:
@import "../../../../node_modules/uica-stack/src/app/uica";
Mockdata Registry
A mockdata registry is also delivered by the `uica-stack`. To use it, it needs to be required:
require('uica-stack/mockdata-registry')
Migration guide to 1.0.0
Major changes need to be done in your application if you used versions < 1.0.0. Here is a list of steps that should help you migrating to >=1.0.0:
* delivery parts have been renamed from spa-fw to uica. If your delivery build fails take a look at the output list of available delivery parts.
* delivery parts holding a polyfill library have earned the prefix uica.polyfill (and maybe lost their old -polyfill suffix). If your delivery build fails take a look at the output list of available delivery parts.
* Security leaks in jQuery 2.x forced an upgrade to 3.x. This might bring erros to jquery plugins and code in your application. Ensure that all your jQuery related code is working with jQuery >3.0.0
* library 'numeral' has changed its API. Instead of numeral.language() use numeral.locale() now.