Mobile-optimized, composable UI components that support a rich HTML5 user experience.
The goal is to have, by v1.0, a suite of composable objects inspired by the Spark/Flex 4 component architecture:
- Viewport: Clipping container that supports touch and mouse interactions to pan, zoom, and swipe content.
- Scroller: Decorator for Viewport that adds scroll bars to the container.
- Lists: Memory-efficient, fast-performing virtualized lists for rendering any number of items.
- Layouts: Vertical, horizontal, tiled and carousel layouts.
- Renderers: Pluggable item renderers for rendering any type of content.
- Transitions: Customizable transitions between states.
The AwesomeMap defines a viewport that supports direct interactions via touch and mouse, and simulated interactions via its public API. Available interactions include panning, swiping and zooming.
An AwesomeMap is also highly extensible through the use of interceptors. Interceptors subscribe to events in the AwesomeMap and modify transformations before they are executed, making it easy to encapsulate transformation behavior. There are three interceptors provided out of the box:
- BoundaryInterceptor: Restricts panning of content to the viewport boundaries.
- ScaleInterceptor: Restricts zooming of content to specified scale limits.
- SwipeInterceptor: Animates a swipe when swipe events are transformed.
The ScrollList renders a virtualized list of items in its host element. The list can be scrolled and zoomed using both touch and mouse interactions or via methods on instances of the object.
- Distribution is through bower. Don't forget to add the version to the end of the URL (or you can do #master)!
# install bower if you haven't already
$ npm install -g bower
# install this package
$ bower install git@github.com:Workiva/wf-uicomponents.git#{version}
- In your requirejs configuration, ensure the following config exists for both wf-uicomponents and its dependencies:
requirejs.config({
paths: {
'wf-uicomponents': 'path-to-bower_components/wf-uicomponents/src/',
'wf-common': 'path-to-bower_components/wf-common/src/',
hammerjs: 'path-to-bower_components/hammerjs/dist/hammer',
lodash: 'path-to-bower_components/lodash/dist/lodash',
modernizr: 'path-to-bower_components/modernizr/modernizr'
},
shim: {
hammerjs: {
exports: 'Hammer'
},
modernizr: {
exports: 'Modernizr'
}
}
});
# clone the repo
$ git clone git@github.com:Workiva/wf-uicomponents.git
$ cd wf-uicomponents
# install global tools if you haven't already
$ npm install -g bower
$ npm install -g grunt-cli
# run init script
$ ./init.sh
The init script will initialize your local environment and ensure that you have all global and local dependencies installed.
To get started developing:
# ensure everything is working when checking out a new branch:
$ grunt qa
# setup lint and test watches and serve as you develop:
$ grunt dev
There's a special grunt task for you! It will:
- lint the code
- run the tests
- report on code coverage
- generate the API docs
- open the project web site so you can get going fast!
$ grunt qa
You should run this every time you checkout a branch. It will do everything to get you going.
bower_components
libraries distributed by Bowerdocs
project design and API documentationexamples
sample applications and suchnode_modules
libraries distributed by NPMout
output from build taskssrc
source filestest
test filestools
supporting tools for code quality, builds, etc.
Familiarize yourself with the package managers we use:
This project uses wf-grunt. Please see that repo for more information.
Many variables reference places on a page or scroll list:
- Positions should usually be positive numbers.
- Translations should usually be negative numbers. They are negative because they refer to how far a page should move off-screen.