First checking for book

01-preface.markdown

@@ -0,0 +1,10 @@
+#Preface
+
+ChocolateChip-UI was created to give developers the chance to create really good looking apps. There are so many frameworks, and they approach the problem of making mobile Web apps from many angles. Depending on your needs and your background, any one of them could be the perfect solution for your development needs. In this crowded scene of development options ChocolateChip-UI stands out for two reasons: it has a very simple and clean markup for defining an app's interface, and by default the UI will look really good, with the native look and feel of each supported mobile platform.
+
+If you want to create a great app that your users will love and will stand out from the crowd, you might want to take a look at how ChocolateChip-UI can help you achieve that goal. If you need to support several platforms and don't have the time or resources to pull it off well, you should take a look at how ChocolateChip-UI's themes handle this for you.
+
+
+This book is based on ChocolateChip-UI 3.6.1. If you are using a newer version, please check our website [http://chocolatechip-ui.com/documention](http://chocolatechip-ui.com/documention) to see if there are any differences from what is presented here.
+
+

02-introduction.markdown

@@ -0,0 +1,92 @@
+#ChocolateChip-UI
+
+##Introduction
+
+###What is ChocolateChip-UI?
+
+ChocolateChip-UI is a framework for building mobile Web apps using the popular jQuery JavaScript library. These can be run in mobile browsers, or delievered to app stores using Phonegap/Cordova. Specifically, ChocolateChip-UI is just the UI or interface of your app, what developers call the view. ChocolateChip-UI makes no assumptions about what your app's backend is. This means you can choose the backend you want for your app and what you need to implement the controllers and data models: Backbone, Knockout, Spine, Ember, Angularjs, JavaScriptMVC, CanJS, etc.
+
+ChocolateChip-UI gives you the tools to create a consistent and satisfying user experience on three mobile platforms: Android, iOS and Windows Phone 8. It does this through the use of themes. To support a mobile platform is just a matter of switching out the theme.
+
+####Clean, Semantic Markup
+
+While we were in the planning stage, one of the things we wanted to accomplish was to make the framework really easy to understand. For this end we decided to go with a very lean and clean approach to defining the markup. Layouts and widgets are defined by simple, uncluttered, semantic HTML5 markup. ChocolateChip-UI recreates the UI of Android, iOS and Windows Phone 8 using just the following tags:
+
+1. article
+2. nav
+3. section
+4. div
+5. aside
+6. ul
+7. li
+8. h1 - h5
+9. span
+10. a
+
+ChocolateChip-UI uses a small number of classes with these tags to define their styles and to identify their functionality to ChUI.js so that it can intialize them at load time.
+
+####CSS3 Themes
+
+The biggest challenge when trying to support more than one mobile platform is the differences between them in not only appearance, but also in user interaction. All platforms have ways of displaying data in organized structures and provide common patterns for user interaction through controls. However, each mobile platform strives to distinguish itself from its competitors by differenciating the visual appearance as much as possible. They also try to create quite different user experiences by making the interaction with the user interface unique to their platform. Although this is great for the users of the platforms, this is problematic for developers trying to build apps that work on them. 
+
+There are two approaches generally taken when trying to resolve this problem. Create a one size fits all framework, where the app looks and behaves identically on all platforms. Or create a framework with a very limitted set of layouts and widgets that sort of look like the target platform through the use of themes. Unfortunately this always results in interfaces that are unconvincing and sometimes awkward and quirky. Users will notice the non-standard look and behavior and they may conclude that there is something wrong with the app because its interface doesn't look or behave properly.
+
+We were not very happy with either of these approaches. We knew that having themes was the right approach, but we were not satisfied with anything we found. We therefore decided to take this approach a step further. We went over each platform, reading documentation, examining header files, really wrapping our heads around how they worked. We took to heart the UI/UX guidelines provided by each platform vendor and used these to determine what we needed to build. We compared our lists for each platform, we noted their similarities and differences, and came up with a master list that spanned all three platforms. Using the master list, we began creating diagrams of the markup needed to create the structures to represent them. We wanted the least amount of markup possible. We wanted the markup to represent data structures as faithfully as possible, eliminating markup that was purely a prop for a visual effect. We were fanatical about this. We wanted the DOM tree created by the markup to be as shallow as possible. This would allow for faster browser renderings. When this was completed, we moved on to the the next stage. 
+
+ChocolateChip-UI themes are built using LESS. Each layout type and widget has its own LESS file. Also all colors are defined in a separate colors.less file. This means you can open that file up and modify the colors of your app for branding, then simply reprocess the LESS to get the new CSS for your app. 
+
+The themes control everything regarding placement, animation, navigation and other visual user interactions. Imagine that you had started creating your app using the Android theme. Then later you realized you also wanted to make your app available to iPhone users. All you would have to do is change the reference of the link tag from Android to iOS. When the app loads, you will see your layouts and interactions change automatically to what an iPhone user would expect. The themes also support right-to-left languages, such as Arabic, Farsi, Urdu and Hebrew. Just add the attribute `dir="rtl"` to the HTML tag. When your app loads, everything will be switched around automatically.
+
+
+###Why Use It?
+
+There are many mobile Web app frameworks. Lots of them. Even so, we think ChocolateChip-UI offers something no other framework does. It enables you to create mobile Web apps with the look and feel of native apps. Other frameworks talk about having performance of native apps. We have that too. When you use ChocolateChip-UI for creating an app, your users will have no idea it is not native. Your apps will be snappy and responsive. You layouts and widgets will act the way users expect them to. And they will look fantastic. Your competitors will be wondering how you pulled it off. 
+
+####Speed
+
+ChocolateChip-UI achieves optimial performance in a number of ways. First of all, load times. The files for ChocolateChip-UI are just three: jQuery, ChUI.js and a theme. You can load jQuery from a CDN or use a minified version. ChUI.js minified is 42kb. The themes are: Android - 59kb, iOS - 49kb, Windows Phone 8 - 33kb. Another thing, the icons used by widgets on Android and iOS are in the CSS as SVG data urls, and for Windows Phone 8, we use the native icon font--Segoe UI Symbol--just as Microsoft does. This means for the framework you just have three files to load. If you lazy load your media data after the app loads, your app will be up and running quickly.
+
+All animation in ChocolateChip-UI is accomplished through hardware-accelerated CSS. This means your users get to enjoy smooth interactions on today's advanced mobile devices.
+
+Another problem that affects performance is the difference between mouse interaction and touch. ChocolateChip-UI has a gesture module that identifies when the user is on a desktop or mobile browser. ChocolateChip-UI abstracts these into a standard interface that works consistently for desktop, Android, iOS and Windows Phone 8. The following events are available:
+
+- $.eventStart: mousedown/touchstart/MSPointerDown/pointerdown
+- $.eventMove: mousemove/touchmove/MSPointerMove/pointermove
+- $.eventEnd: mouseup/touchend/MSPointerUP/pointerup
+- $.eventCancel: mousecancel/touchcancel/MSPointerCancel/pointercancel
+
+Besides these, it also provides the following events:
+
+- tap
+- singletap
+- doubletap
+- longtap
+- swipe
+- swipeleft
+- swiperight
+- swipeup
+- swipedown
+
+These events work on desktop and mobile. We recommed the use of the singletap event instead of click or touchstart events. The reason is, if your content needs to be scrollable and contains items that are interactive with mousedown/touchstart/pointerdown events, when the user attempts to scroll, they may immediately trigger unintended interactions. This can make scrolling a page of interactive content very frustating. When you use a singletap event to register your interactions, there is a slight delay of 130 milliseconds. This gives the user enough time to touch interactive content and scroll the page without accidentally triggering an unintended interaction.
+
+ChocolateChip-UI also has its own template engine. In performance tests, it is comparable to underscore or handlebars. You can use it to dynamically populate your views with data either local or through Ajax requests. 
+
+####Full Set of Layouts and Widgets
+
+Using standard HTML5 markup, ChocolateChip-UI provides a wide range of layout options to accomodate your needs. And because the layouts are created with HTML5 tags and CSS, you can easily add a class and define a new style to create the layout variation you need. 
+
+ChocolateChip-UI provides the typical data lists which can be made into navigable lists, lists that display a detail about the chosen item, selection lists, deletable lists, as well as composite lists for complex layouts with columnar data. It also has a module for grid layouts implemented with the CSS3 flexible box model. 
+
+ChocolateChip-UI offers navigation lists, tabbar interfaces, slide-out menus, slide-down sheets, toggle panels, paginated navigation, and carousels. For tablets, you can use the split-layout to create the popular master-detail layout. 
+
+Widgets include buttons, back buttons, segemented controls, modal popups, popovers/spinners, busy indicators, switches, range controls, steppers and search boxes. Form nputs get styled appropriately for each platform. 
+
+With ChocolateChip-UI you have everything you need to create a beautiful interface for your app without sweating the details. We do that for you so you can spend your precious time implementing the data services your app needs. 
+
+ChocolateChip-UI was designed from the start to be resolution independent. The UI will always be rendered at the highest resolution available on the device. Its layouts are also responsive, they will resize automatically with orientation change and will expanding to fill the available screen real estate of all mobile devices. 
+
+####Compatible with Other Libaries and Frameworks
+
+You can use ChocolateChip-UI with a wide variety of other libraries and frameworks. ChocolateChip-UI is built on top of jQuery, so anything that is jQuery compatible should work as is. Before attempting to use any jQuery plugins with ChocolateChip-UI do check the plugin documentation to make sure that it works on mobile. 
+
+There are many development frameworks that you can use to help you create organized and efficient code, such as Backbone, Knockout, Angularjs, Sammyjs, Ember, Somajs, Amplifyjs, Feathers, etc. 

03-getting started.markdown

@@ -0,0 +1,171 @@
+#ChocolateChip-UI
+
+##Getting Started
+
+###Setup
+
+ChocolateChip-UI is a Web app framework. As such it needs to run in a mobile browser. ChocolateChip-UI is an open source project available on Github: [https://github.com/sourcebitsllc/chocolatechip-ui](https://github.com/sourcebitsllc/chocolatechip-ui). You can download it in two ways: download a zip or clone it to your desktop. Cloning the repository gives you a duplicate of the original repository that you can work with. If you clone it, you can send us a pull request if you find a bug and fix it, improve a feature, or add a new one.
+
+If you do not want to have to build ChocolateChip-UI from source code, you can just open the folder `dist`. This contains pre-compiled versions of the JavaScript and themes you need to make an app with ChocolateChip-UI. Otherwise, please continue ahead to learn how to build ChocolateChip-UI from scratch.
+
+ChocolateChip-UI uses Node modules to enable building the framework. ChocolateChip-UI has no dependency on Nodejs for running, so you do not need the modules in your project.
+
+####Installing Nodejs
+
+First go to the [Node](http://nodejs.org) site. You'll see an install button on the page. This will install the correct version of Node if you are on a Mac or Windows PC. Please note that if you are on a Windows 8 device, this will not work with WinRT. Furthermore, for Windows 8, you must use the browser on the desktop, not in the Modern UI Start Screen.
+
+After Node is finished installing, you need to install the modules that Node will need to build the framework. Using the terminal, change to the folder where ChocolateChip-UI is. You can do that by typing <code>cd</code> into the terminal, leaving a space after it, then dragging the folder to the terminal. When you see the path to the folder appear after the cd command, hit return. You will now be inside that folder. That is where you need to be to run the install scripts.
+
+On the Mac, in same terminal window where you used the cd command to get to your ChocolateChip-UI folder, run the following command:
+
+```
+sudo npm install
+```
+
+On Windows, open the command prompt and run this:
+
+```
+npm install
+```
+
+When you hit Return (Mac), the terminal will ask you for your user password. Enter it and hit return. On Windows, enter the command and hit Enter. In both cases you will see a list of messages output to the terminal. This install reads ChocolateChip-UI's package.json file to see what version of modules the framework needs. These  dependencies are put in a folder labeled "node_modules". If there are no errors, you're ready to setup a task manager for building ChocolateChip-UI.
+
+ChocolateChip-UI uses [Gulpjs](http://gulpjs.com) as its task manager. If you are familiar with Gruntjs, this is very similar. Although Grunt has been around longer and more developers are familiar with it, we like Gulp because of its fast build times and minimalistic code. Although we used to support Gruntjs, since Gulp was easier to maintain and faster, we decided to drop support for Gruntjs.
+
+####Install and Run Gulp
+
+To use Gulp, you need to first install it globally so that it is available from the terminal/command prompt. On the Mac, run this:
+
+```
+sudo npm install -g gulp
+```
+
+On windows, run this:
+
+```
+npm install -g gulp
+```
+
+
+Once this install is done, you're ready to build ChocolateChip-UI. The simplest way to build ChocolateChip-UI is to just runt `gulp` in the terminal. That will output the framework along with examples and demos for Android, iOS and Windows Phone 8. The Android examples can be tested in the Chrome desktop browser, the iOS examples, in the Safari desktop browser, and the Windows Phone 8 examples in IE 10 or 11.
+
+After running the Gulp script, you will find the following new folders in your ChocolateChip-UI folder:
+
+- chui/
+- data/
+- demo/
+- examples-android/
+- examples-ios/
+- examples-win/
+- images/
+- node_modules/
+
+
+If you're starting a new project, you only need the files in the **chui** folder. To create a custom build with just those files, you can run any of these tasks:
+
+
+``` 
+// Build only ChUI.js and the Android theme:
+gulp js android
+
+```
+
+```
+// Build only ChUI.js and the iOS theme:
+gulp js ios
+```
+
+```
+// Build only ChUI.js and the Windows Phone 8 theme:
+gulp js win
+```
+
+
+Or if you want all three themes with ChUI.js:
+
+
+```
+gulp chui
+```
+
+Running these commands will give you the normal and mininfied version of the framework. While in development, you probably want to use the unminified version so you can troubleshoot errors. Please do use the minified versions in production.
+
+You can also create a platform-specific version with examples. Run one of the following commands:
+
+
+```
+// Build only ChUI.js and the Android examples:
+gulp android_examples
+```
+
+```
+// Build only ChUI.js and the iOS examples:
+gulp ios_examples
+```
+
+```
+// Build only ChUI.js and the Windows Phone 8 examples:
+gulp win_examples
+```
+
+ChocolateChip-UI supports right-to-left alphabets, such as Arabic, Farsi, Urdu and Hebrew. To enable it all you have to do is put the property `dir="rtl"` in the document's html tag. ChocolateChip-UI will automatically render your documents for correct right-to-left interfaces. In the source code there are examples of right-to-left layouts and widgets using Arabic. You pass Gulp a flag `--dir rtl` so that it builds out these examples. Run this in your terminal:
+
+```
+gulp --dir rtl
+```
+
+This will produce the following folders:
+
+- chui
+- data
+- images
+- rtl-demo
+- rtl-examples-android
+- rtl-examples-ios
+- rtl-examples-win
+- rtl-images
+
+You can also use the rtl flag on any of the OS-specific builds:
+
+
+```
+gulp android_examples --dir rtl
+```
+
+
+
+```
+gulp ios_examples --dir rtl
+```
+
+
+
+```
+gulp win_examples --dir rtl
+```
+
+
+
+###Watching Changes
+
+If you want to customize a theme for branding purposes, you can ask Gulp to watch the files for changes. As soon as you save a change to the LESS files, Gulp will rebuild the theme. Similarly, if you make a change to the source files for ChUI.js and save, Gulp will rebuild the ChUI.js file for you as well. The easiest way to enable this is to just run the Gulp watch task:
+
+
+```
+gulp watch
+```
+
+If you want, you can run the build and watch scripts at the same time. These will watch only the designated theme source files:
+
+
+```
+gulp js android && gulp watch_android
+```
+
+```
+gulp js ios && gulp watch_ios
+```
+
+```
+gulp js win && gulp watch_win
+```