Documentation – Building ChocolateChip-UI

No Building Needed

You do not need to build ChocolateChip-UI to begin using it. There are pre-compiled versions in the dist folder in the downloaded source files. However, if you want working examples or want to customize ChocolateChip-UI, you’ll need to know how to build it.

NPM Module: Chui

If you want, you can install the NPM module chui. This enables you to run a command in the terminal to create a project with the resources for the type of app you wish to make. Installation is easy:

sudo npm install chui -g

Once installed, you can customize the results with different arguments:

// Create a plain file in a folder named Fruits in ~/Documents/Dev // with the Android theme, default libarary will be jQuery:
chui --name Fruits--path ~/Documents/Dev/--os android
// or create a tabbar interface in a folder Fruits on the desktop // for iOS using the library ChocolateChipJS:
chui --name Fruits--lib chocolatechip --os ios --type tabbar
// or create a slide out menu for Windows Phone in Fruits on the desktop, // default libarary will be jQuery:
chui --name Fruits--os win --type slideout

Please read the documentation to learn about all the features and options.

Setup with Gulp

ChocolateChip-UI uses the Gulp Node module to enable building the framework. ChocolateChip-UI has no dependency on Nodejs or Gulpjs for running, so you do not need them in your project. As of version 3.6.0, Gulp is the default way of building ChocolateChip-UI.

Install Nodejs & Gulpjs

First go to the Node site. You’ll see an install button on the page. This will install the correct version of Node for you 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 Gulp command line interface, which is a node module for task management. On the Mac, open your terminal and run this command:

sudo npm install -g gulp

On Windows, open the command prompt and run this:

npm install -g gulp

When you hit Return (Mac), the terminal will ask you for your 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. If there are no errors, you’re ready to build. Using the terminal, change to the folder where ChocolateChip-UI is. You can do that by typing cd 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 build scripts. Before you can build, you need to install a number of Node modules that Gulp will use to do the work.

Install the Build Modules

First you need to install the modules that the Gulp script uses to build. You do this by running the following command in your terminal:

npm install

You’ll see a really long list of things being installed. And, if you have the folder open, you’ll see a directory named “node_modules” appear. Once the install is finished you’re ready to build.

Building ChUI

Building is really simple. Just type “gulp” in the terminal and hit return. This will cause a complete version of ChocolateChip-UI to be built into the folder. This will include the ChocolateChipJS library, themes for iOS, Android and Windows, examples for iOS, Android and Windows, and unit tests for ChocolateChipJS.

// Build everything, including examples:
gulp

You can also build only ChUI.js and the three themes:

// Build the ChUI without examples:
gulp chui

You can also build just the CSS themes. This is useful if you are modifying the LESS files to create a custom theme for branding.

// Build the three themes:
gulp less

If you intend to edit the ChUI LESS files to customize the look and feel for branding, you can tell gulp to watch those for any changes you make. When you save a LESS file after making changes, watch will automatically regenerate the CSS for you. Use the following command:

// Build ChUI.js:
gulp watch

If you’ve made changes to the ChUI.js source files and want to regenerate it, or you just want to create the ChUI.js file, use this command:

// Build ChUI.js:
gulp js

Right-to-left Examples

If you are supporting a right-to-left alphabet, such as Arabic, Farsi, Urdu or Hebrew, you can build right-top-left examples to see how they work. Note these are mostly in Standard Arabic. To build them, use the following command:

// Build right-to-left examples:
gulp --dir rtl

Custom Project

So far we’ve been building everything directly inside the folder of the repository. This is not very practical. You can build your project outside this folder by providing a path to where you want your project to be. This could be on your desktop, or any other place. To do this, open the package.json file and look for the property “projectPath”. Currently the value is empty. By providing a path, your project will be built in the place indicated. This will give you a clean install of ChocolateChip-UI without node modules, source files, etc. You can then add any other resources you need into this folder and begin development of your app.

Here is an example of a possible path for a Mac and Windows project path using the username “joe”. Please change “joe” to your own username on your Mac or Windows PC.

// For a custom Mac project:"projectPath":"/Users/joe/Desktop/MyProject/"

Please note, for Windows you need to escape the backslashes with another backslash.

// For a custom Windows project:"projectPath":"C:\\Users\\joe\\Desktop\\MyProject\\"

ChocolateChipJS

ChocolateChip-UI is built to run on jQuery, the widespread and well-know JavaScript library. However, ChocolateChip-UI can optionally run on ChocolateChipJS. This is a mobile-first JavaScript library written to be small and fast, as much as 30% faster than jQuery. If you find that with jQuery your app’s interactions feel sluggish, you might want to try using ChocolateChipJS. You can learn more about ChocolateChipJS from the documentation. You can build the ChocolateChip-UI examples as follows:

LESS

ChocolateChip-UI uses LESS to create all of its styles. This makes it easy for you to customize the look and feel of ChocolateChip-UI if you want. LESS is a powerful CSS preprocessor. If you make changes to the LESS source files, you can rebuild the themes by running gulp less or gulp themes. This will create new copies of the CSS themes for all three operating systems.