XFramework

Getting started

What is XFramework?

Version 0.9.1

XFramework (next XF) is a small yet powerful Javascript framework for quick development of cross-device web applications. Honestly saying, XF is a high-level framework based on Backbone.js that implements its own architecture paradigm, based on MV* on the component level.

XFramework makes it easy to reuse the application logic and provide various layouts or widgets for different devices based on the criteria that you define.

XFramework is designed to be extremely modular, flexible, fast, and easy to use. To develop an app in X-Framework a developer should be familiar with common web technologies such as HTML/CSS/JS, LESS for editing styles, Handlebars-style templating and have an understanding of how MV* architecture works. Experience using Backbone.js, Angular.js, Ember.js, jQuery Mobile or other framework will be helpful.

XFramework currently features:

• TOTALLY CROSS-PLATFORM. XF supports all the popular devices and platroms. It is built in the way that allows you easily to change templates for each of the platforms without huge effort.
• SCALABLE ARCHITECTURE. Component-based modular event-driven architecture provides a possibility to build scalable and maintainable web apps with high-reusability of components.
• CUTE & CUSTOMIZABLE. XF uses LESS as preprocessor for CSS. It goes with a default theme that could be easily customized changing some lines of CSS code.
• LIBRARY OF COMPONENTS. Reusability is a king! XF is flexible and extandable to the roots: it goes with a library of predefined components but feel free to write your own components and submit it to us!
• POWERFUL RICH UI-ELEMENTS. Set of powerful rich UI-elements (e.g. form elements, buttons, lists) for different platforms gives a ability to provide the best user experience for each device type. And the number of UI-elements s growing!
• FLEXIBILITY TO FEEL THE FREEDOM. Build process allows you to create a custom build of XFramework and use it together with your favorite UI-library like jQuery Mobile or Ratchet.

Supported Platforms and Browsers

Desktop:

• Internet Explorer 8+
• Firefox 4+
• Safari 5+
• Opera 11+
• Chrome 18+

Mobile phones and tablets:

• iOS 5+: Mobile Safari, Chrome for Mobile, UC Browser on iPad 2 (iOS 5.1), iPhone 4S (iOS 5.1), iPhone 5 (iOS 5.1), iPad 3 (iOS 5.1)
• Android 2.3.3+: Android Browser, Opera Mobile, Chrome for Mobile, Firefox Mobile on Motorola Droid 3 (Android 2.3.4), HTC Inspire 4G (Android 2.3.3), ASUS Nexus 7 (Android 4.1), Samsung Nexus S (Android 2.3.4), Sony Ericsson Xperia X10 (Android 2.3.3)
• BlackBerry OS 6+: BlackBerry Browser on BlackBerry Torch 9800 (BlackBerry OS 6.0)
• Windows Phone 7.5+

It doesn't mean that another browsers or platforms are not supported. We just don't have a possibility to test XF across all existing platforms and browsers.

The roadmap for the next versions can be found on GitHub.

The idea behind

There are some rules behind the XFramework:

• Component-based event-driven architecture
• Components easily customizable with options
• Lazy loading of components
• Different templates for each of device types

Installing XFramework Generator

You don't need to download the source code from the repo, create all the necessary files for the web app, writing two thousands line of code just to create a Hello world! app. XFramework Generator can make everything for you.

XF Generator has a number of dependencies such as:

• node.js
• NPM
• [Yeoman] (http://yeoman.io)

To install first two of them on Mac OS X or Windows computers you just need to download a package from nodejs.org/download/. For other platforms see the readme.

After installing node.js and npm go to terminal and install Yeoman writing npm install -g yo (with sudo if necessary).

Almost there! After these steps you need to install XF Generator with npm install -g generator-xf.

Your first XF web app

To create the first XF application the simplest way is to use XF Generator through yo xf:application init [appName].

For now it scaffolds an app in the way you can see by example: XF Hello World App.

Building your XF app for testing and production

yo xf:application build [appName]

Creation of custom XFramework build

Custom xf.js and xf.min js build:

• yo xf:build — create build with all UI elements and source modules
• yo xf:build [srcModule1:srcModule2] — create build with all UI elements and source modules

Full list of available elements can be found at xf/ui and xf/src directory of XFramework repository.

Updating XF and dependencies

XF Generator allows you to update sources and dependencies:

• yo xf:update [all] — update less and js files of XFramework, check latest versions of jQuery, Backbone, Underscore
• yo xf:update scripts — update js files (inluding thirdparty libraries) of XFramework, check latest versions of jQuery, Backbone, Underscore
• yo xf:update styles — update less files of XFramework

XFramework internals

XF source modules

XFramework has its own building blocks that drive it on. Some blocks are mandatory to include in the build of XFramework, other ones are not required.

Mandatory XF src modules are:

• xf.jquery.hooks.js
• xf.core.js
• xf.settings.js
• xf.app.js
• xf.router.js
• xf.pages.js
• xf.model.js
• xf.collection.js
• xf.view.js
• xf.component.js

Optional XF src modules are:

• xf.ui.js
• xf.ui.*.js
• xf.touch.js
• xf.utils.js
• xf.storage.js
• xf.zepto.support.js

XF.App

XF.App is a 'class' that you able to extend with your own methods and properties needed in the application. In this case an instance of this class is something like a main controller of the whole app.

// if the app boilerplate was created via XF Generator
// these lines can be found in `app.js` file
var MyApp = XF.App.extend({
    initialize: function () {
    	// this code will be executed before XF will be started
			// but you can put the preparation code here
			// …
			this.myAwesomeMethod();
    },
		myAwesomeMethod: function () {

		}
});

XF.device

XF.device contains the information about current user device app was launched:

• XF.device.supports.touchEvents
• XF.device.supports.pointerEvents
• XF.device.supports.cssAnimations
• XF.device.isMobile. It was a necessary trick to detect mobile OS's using navigator.userAgent.
• XF.device.type is a selected type of devices from specified in options passed on the start of application. Based on this selected device type the necessary template for the component will be loaded.

var app = new MyApp({
		// …
		// other settings for the application
    device: {
				types : [{
            name : 'tablet',
            range : {
                max : 1024,
                min : 569
            },
            templatePath : 'tablet/' // template path for tablet devices (by default it will be tmpl/tablet/componentName.tmpl)
        }, {
            name : 'phone',
            range : {
                max : 568,
                min : null
            },
            templatePath : 'phone/' // path to templates for phones (by default it	 will be tmpl/phone/componentName.tmpl)
        }]
    }
});

XF.Router

XF.Router is an extended [Backbone.Router]. XF cares about creation of router instance, its starting, binding handlers and so on. Everything you just need to do is to pass your routes and handlers with starting options for the application:

	// if the app boilerplate was created via XF Generator
	// these lines cab be found in `index.js` file
	var app = new MyApp({
		// …
		// other settings for the application
    router: {
        routes: {
            '': 										'home',
            'search/:q':	  						'searchByQuery',
            'item:id':  							'showItemById',
						'books/:cat(/:subcat)':	'showBooksCategory',
						'news/*any':							'showNews'
        },

        home: function () {

        },

        searchByQuery: function (query) {

        },

        showItemById: function (id) {

        },

				showBooksCategory: function (cat, subcat) {

				},

				showNews: function (param) {

				}
    }
});

In the example above the handler home for empty route was created. In case you want to define the starting route for the application or turn off HTML5 pushState (using pushState support is turned on by default) you should pass the necessary starting parameters to XF.history which actually is a link to Backbone.history.

var app = new MyApp({
		// …
		// other settings for the application
    history: {
				pushState: false,
				root: 'books/fiction'
    }
});

To force navigation to another url fragment a number of ways is available:

• XF.router.navigate('books/fiction', {trigger: true})
• XF.navigate('books/fiction') is the syntax sugar for the first approach. {trigger: true} set by default
• XF.trigger('navigate', 'books/fiction') is much more preferable for consistency and integrity of the application

All elements with the attribute data-href or href will work on changing url fragment.

<a data-href="books/fiction">Books</a>

XF.pages

XF.pages drives the appearance of the pages sticking together with the router. It has some basic animations for switching pages such like slideleft, slideright, fade and none. Not so much for now but keep in mind that it is possible to define your own animation to use it together with XF.pages.

To create a page you just need to make a <div> with necessary classes):

<div class="xf-page" id="books"></div>

id is used to make page switching work together with the router. It should be equal to first url fragment of the route (e.g. books/:cat(/:subcat)) or the name of the handler (e.g. showBooksCategory). In this case the page with such id attribute will be shown automatically when the route (e.g. books/fiction) will be triggered.

To show the page without changing the url or using route binding:

XF.trigger('pages:show', 'books', 'fade');

// …directly
XF.pages.show('books', 'fade');

To define the default animation type for all device types it's needed to set up the necessary properties on the start of app:

var app = new MyApp({
		// …
		// other settings for the application
		animations: {
			standardAnimation: 'slideleft' // 'slideleft' is default
		}
});

If you want to create your own animation type and use it for page switching you (please care about necessary CSS animations in xf.animations.less file):

var app = new MyApp({
		// …
		// other settings for the application
		animations: {
			types: {
				'myOwnAnimation': {
					fallback: function (fromPage, toPage) {
						// fallback to JS animation for old legacy browsers
						/// …
					}
				}
			}
		}
});

To define the default animation for each of device types it's needed to pass such parameters together with device options on the start of application or set it in the runtime:

var app = new MyApp({
		// …
		// other settings for the application
    device: {
				types : [{
            name : 'tablet',
            range : {
                max : 1024,
                min : 569
            },
            templatePath : 'tablet/',
						defaultAnimation: 'fade' // 'fade' for tablet devices
        }, {
            name : 'phone',