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

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 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 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 and start with a fresh SPA environment including some examples and documentation.

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

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

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

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, 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 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