Install

Chui Creates Your Projects

Source Code

ChocolateChip-UI is available on Gitub. You can check out the source code there. Although you can download the source code, it isn't practical for creating a new project. For that we use a special command line tool that helps you create new projects, etc. It's available on NPM. How to install the command line tool and get started are explained below.

NPM

ChocolateChip-UI has an NPM module called chui that you can install and use to make new ChocolateChip-UI apps quickly.

Install NPM Module

To install the NPM module, you use the following command. Depending on how you have NPM setup on your machine, you may need to use the sudo command before it.

npm i -g chui

Chui on NPM

Keeping Chui Up-To-Date

We make lots of small updates to ChocolateChip-UI all the time, things like typos, code cleanup and minor improvement to examples, etc. The best way to make sure you are up-to-date is to update. Simple, right? It's a good idea to update your chui command line tool at least once a month. To update it, run the following in the terminal:

npm update -g chui

If you're on a Mac or Linux, you'll need to use sudo with that, which will ask you for your password:

sudo npm update -g chui

Get All the ChocolateChip-UI Examples

Once the command line tool is installed, you can get all the examples of layouts and widgets that ChocolateChip-UI offers with a simple command:

chui -e

By default all of these are using the iOS theme. To see the Android theme, open the html file and change chui-ios.min.css to chui-android.min.css.

Get the ChocolateChip-UI Reference Apps

You can output all the ChocolateChip-UI reference apps to your desktop.

chui -r

This will output a folder call Chui Referene Apps to your desktop. Inside you'll find these four apps:

  • Fragranž
  • SFCoffee
  • TodoMVC
  • Vino

To run these, you'll first need to open the terminal and cd to the app you want to run. First install its dependencies with npm i. When that is done, run npm run build. This will compile the code. After that you can double click the index.html file to launch it in the browser. Or you could run http-server in the folder to run a server instance. Or use any other means of running a server instance in the folder.

Starting a New Project

You can also use this command line tool to create a new project. Below are the various parameters you can use to customize what kind of project ChocolateChip-UI makes for you.

Parameters

  • n The name for your app. This is required. This will create a folder with this name, and, depending on the type of app, may also update app info to display it.
  • p The path where you want your project to be. If none is provided, it will be output to your desktop in a folder with your project's name.
  • o The operating system you wish to target. If none is provided it defaults to iOS. The expected values are: "ios" or "android".
  • t The type of project you wish to create. There are four choices: "basic", "navigation", "slideout" and "tabbar". If no type is provide it will default to basic. Once you're more familiar with how things work in ChocolateChip-UI, you'll probably prefer to make all your new projects basic and go from there.

When using names or paths that have spaces, you will need to quote those to get the correct result.

Usage

// Create a simple Android app in 
// the folder Fruits in ~/Documents/Dev:
chui -n Fruits -p ~/Documents/Dev/ -o android

// or create iOS tabbar interface in Fruits on the desktop:
chui -n Fruits -o ios -t tabbar

// or create a slide out menu for Android in 
// Fruits on the desktop:
chui -n Fruits -o android -t slideout

This will create the following directory structure:


+ css
  - app.css
  - chui-android.css
  - chui-android.css.map
  - chui-ios.css
  - chui-ios.css.map
+ data
+ dev
  + components
  + data
  + src
    + utils
    + widgets
  - app.js
+ images
+ js
  - chui.min.js
  - chui.min.js.map
- .bablerc.js
- .editorconfig
- gulpfile.js
- index.html
- package.json

Changing Your Project's Theme

To change the theme that you set when you created your project, open the index.html file and change the line for chui-(OS_THEME).min.css to whichever theme you want. For example, if you set up your app to target iOS and now want to target Android, change the link href from chui-ios.min.css to chui-android.min.css. When you make a new project, we include all three themes so you can easily switch to a different theme. If you have made custom styles in your app's app.css file, and you change the theme, you may need to also update the app.css styles to override the new theme. Please see documentation for themes for more information about overriding the themes.

Rollup, Babel & Browsersync

When you create a project, it automatically adds support for Rollup, Babel and Browsersync. This allows you to write your app's code using ES6 that gets transpiled to ES5. You can organize your project code using ES6 modules. You can also use comprehensions, classes and arrow functions, const, let and other ES6 features supported by Babel in your code. The probject includes to "dot" files - .babelrc for Babel and .editorconfig.js. This file sets up defaults for your editor and controls line endings, indent size, whether to use tabs or spaces, etc. You can edit it to suit your preferences. You can learn more about EditorConfig at their site.

After creating your app, cd to the folder and run:

npm i

Building and Running Your App

Once you've created a project and run npm i, you can build it and run it. There are two commands using gulp:

// Build and serve the app:
gulp

This will build the code, launch a watchers for index.html, dev/app.js and css, and launch the app in the default browser.

If your app is already built and you want to run in in the browser, you can just execute the following in your project's folder:

// If the app is already built,
// you can serve it with:
gulp serve

App.js, The Core of Your App

The dev folder holds a file called app.js. This is the development version of your app's JavaScript. Because this project also has Babel, when you run a build, this file gets transpiled to ES5.

When you edit code in app.js or other files in the dev folder, you can run gulp to compile and reload the new version in the browser. Your index.html already references it from the js folder. When you run the server script, it first runs the build script and then starts up a server instance and opens your default browser. You can change which browser it opens by editing the browserSynch browser property in the gulpfile. It uses your default browser. If you are on Windows and have either IE or Microsoft Edge as your default browser, you will need to change that to Chrome. Simply change the "serve" task in your gulpfile to:

// Static Server & watching files:
gulp.task('serve', ['build'], function () {
  browserSync({
    server: './',
    port: 4040,
    browser: ['google chrome'],
    server: {
      open: false
    }
  }).reload;
});

If you're on a Mac and want to see your iOS theme load in Safari, change the value to safari.app. The file extension is required to launch Safari.

Troubleshooting

If for some reason the path for where you want your project isn't working, check that you are using the correct path delimiters for your platform (Mac, Windows or Linux). Also check to see if a name in the path has a space. If it has any spaces, enclose the whole path in quotes, single or double. The terminal can be picky about spaces.

Build Speed

Because we are using both Rollup, Babel and Uglify, there can be some delay in how quickly your saved changes are compiled. This is mostly due to the need to parse all dependencies before bundling them together into one output file. We think the convenience of a custom output file based on the features you actually use in your app outweighs the time to complete a build.

Troubleshooting Babel, etc.

If you are having trouble installing the Babel module, this is probably due to node-gyp. Please read the installation requirements in the documentation for this module dependency.

Platform Support

Android

ChocolateChip-UI supports Android Jellybean (4.1) to the Nougat (7.0).

The preferred browser for developing for Android is Google Chrome. You can use it on Mac, Windows or Linux. The Chui command line tool can convert your web app into an Android Studio project ready to build and run in the emulator on on a tethered Android device. Android Studio is available for Mac, Windows and Linux.

For device testing you can either load your web app in the Android device's browser from a server, or you can side load your Android apk on a tethered Android device.

iOS

ChocolateChip-UI supports iOS 8 to 10.

If you are want to target iOS, it is best to have a Mac. Use Safari to test in. The Chui command line tool can convert your web app into a hybrid app ready to open and run in Xcode. Currently Xcode is only available on the Mac. Since Swift is now open source, it may be possible to create binaries without Xcode an on platforms other than the Mac in the future, though there are no know projects at the moment.

For device testing you can either load your web app in the iOS device's browser from a server, or you can side load your iOS app on a tethered iPhone, iPod or iPad.

Development Platforms

Windows

If you're on a Windows machine, you should use Chrome to test for Android and iOS. If you want to use ChocolateChip-UI's command line tool to create an iOS app on Windows, you will not be able to build and compile it. For iOS ChocolateChip-UI creates and Xcode project, which only runs on a Mac. However, there are other hybrid app solutions for Windows that you can look into that will build the iOS app online, such as Cordova/Phonegap. Support for Android on Windows merely requires that you download and install Android Studio and the Android SDK.

Mac

If you're on a Mac, you can use Chrome or Safari to test for Android and iOS. If you want to support Android on your Mac, you'll need to download the Android Studio for Mac and the Android SDK. This will let you open your hybrid app and compile it for loading on a tethered Android device. For iOS you need to have Xcode installed. You can download it from the App store.

Linux

If you're on a Linux computer, you can use Chrome to test for Android and iOS. You can install Android Studio and Android SDK to open and build your apk for side loading on a tethered Android device. There is currently no way to open and build hybrid apps for iOS on Linux other than using an online build tool like Cordova/Phonegap.