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. These do not change the version of the project. When you install chui it also pulls down ChocolateChip-UI from Github. This is a one time event. Therefore, if you want to make sure you always have the latest version of ChocolateChip-UI for chui to use, don't use npm update. Instead, reinstall it as described above. That will pull the lastest version of ChocolateChip-UI from Github. You could reinstall chui every two weeks.

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 --examples
// or
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 --refapps
// or
chui -r

You can get a version of the reference apps with support for TypeScript JavaScript intellisense by include the flag --ts. This add a folder callded typeings and a jsconfig.json file to each project. Editors and IDEs that understand TypeScript declaration files can give you code completion, lookups and hints as you type ChocolateChip-UI specific code. This is great when you are new to ChocolateChip-UI and are not familiar with the APIs.

// Get reference apps with JavaScript intellisense:
chui -r --ts

Changing the Theme of the Examples

This will out a folder call Chui Referene Apps to your desktop. Inside you'll find two folders: basic and jspm. Inside these you will find four apps:

  • Fragranž
  • SFCoffee
  • TodoMVC
  • Vino

Why two vesions? The apps in the basic folder are plain JavaScript. Double click the index.html file and it will open in the browser and work, no need for a server instance. The apps in the jspm folder are written in ES6 and use ES6 modeuls to organize the code. As such they require some installation and a build and run step to see them in action.

ChocolateChip-UI is not going to force you to take either approach. If you want to keep things simple, then write your JavaScript like you always have and load it in your html app. And if you want to take advantage of all the great features in ES6 and be able to separate out the functions of your app as modules, and then bundle them into one file, then go with the JSPM versions. We take this same approach to creating new projects, which will be explained below. To learn more about install, building and running the JSPM version of the reference apps, please read the documentation for demos.

The above command will output working examples of ChocolateChip-UI layouts and widgets to the desktop in a folder called "ChUI Examples".

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

  • name or 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.
  • path or 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.
  • os or o The operating system you wish to target. If none is provided it defaults to iOS. The expected values are: "ios" or "android".
  • type or t The type of app that will be created. The default is a page with a simple list, no specific functionality. You can choose any of the following types: "navigation": a dynamic navigation list, "tabbar": a tabbar interface, "slideout": a dynamic slideout menu system.

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 --name Fruits --path ~/Documents/Dev/ --os android 

// or create iOS tabbar interface in Fruits on the desktop:
chui --name Fruits --os ios --type tabbar

// or create a slide out menu for Android in 
// Fruits on the desktop:
chui --name Fruits --os android --type slideout

You can also use shortened versions of the command flags: n for name, p for path, o for os, and t for type. When using these, you can also use just a single hyphen:

// 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

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.

ES6 with JSPM & Browsersync

You can also create a project that uses JSPM, Babel and Browsersync. This allows you to write your app's code using ES6 that gets transpiled to ES5. You can also 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 if you want to. We do. The source code for ChocolateChip-UI is written in ES6 and uses JSPM and Babel to parse the module dependencies. The result is that your final output has only the parts of ChocolateChip-UI that you need. ES6 modules give you that automatically.

Important Note: To use JSPM in your project, first make sure you have JSPM installed globally. You do this by using NPM:

npm i -g jspm

This will install the JSPM commandline tool.

To build a project with these ES6 features, just use the --jspm or -j flags with your command:

//Create a project named "Fruits" for iOS of type "slideout" using JSPM:
chui -n Fruits -o ios -t slideout --jspm

// or
// Create a project named "Fruits" for Android of type "navigation" using JSPM:
chui -n Fruits -o android -t navigation -j

This will create the following directory structure:


+ css
  - app.css
  - chui-android.css
  - chui-ios.css
+ images
+ js
  + dev
    - app.js
  - chui.min.js
  - chui.min.js.map
- config.js
- gulpfile.js
- index.html
- package.json

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

npm install

When this is done, you can run:

jspm install

After the installation is done, you can open the project folder in your editor of choice. Although you'll need to modify some markup in the index.html file, you'll spend most of your time working in the dev folder, where you'll find the app.js file.

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 or serve command, this file gets transpiled to ES5.

When the install is done, you have two options. You can run a build script or a serve script. When you run the build script, it takes the app.js file and converts it to valid ES5 and outputs it to the js folder as app.js. 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.

To build your project, run the following command in your project folder:

gulp

When you run gulp to build your project, it passes your code to Babel to transpile it to browser-safe ES6. Then it launches a server instance using Browsersync. It also spawns watchers to watch your code. When you edit and save your code files in the dev folder, the watchers will rebuild your project and reload the browser for you.

Please be aware that if you do something that throws an exception in either the browser or the server instance, you will need to kill the server in the terminal (control C) to stop the server, then run gulp again.

Custom Builds

When you create a new project, by default you get everything, whether you'll be using it or not. That comes to 133kb of JavaScript. Since the goal is a hybrid app running on devices, this is not bad. This will load really quickly as a local resource. However, if size is a concern for you, you can create a custom build of ChocolateChip-UI for you project if you are using ES6 with JSPM in your project. To do this, just use the flag -c when you create your project. This will give you a minimal version of ChocolateChip-UI that is only 77kb, almost half the size. It also creates a src folder in your dev folder with importable modules. You can import only the ones you need into your app.

To create a custom project, build a JSPM project using the -j flag, and also include the -c flag:

//Create a custom project for JSPM with double hyphen options:
chui --name Fruits --os ios --type slideout --jspm --custom

// Same project with single hyphens options:
chui -n Fruits -o ios -t slideout -j -c

The minimal build lacks support for forms, validation, data formatters, fetch, promises, local data persistence (Box) and widgets. It does support navigation lists out of the box. As such, if you need any of these, you'll need to import them into your app. Below are all in the modules available in your project's src folder.

  • android-ripple
  • box
  • color-contrast
  • editable
  • fetch
  • form
  • multi-select-list
  • paging
  • popover
  • popup
  • promises
  • range
  • segmented
  • select-list
  • serialize
  • sheets
  • slideout
  • stepper
  • switches
  • tabbar
  • validators

Four of the above modules have dependencies on other modules, but they import them automatically. They are:

  • box imports promises
  • fetch imports promises
  • form imports validators
  • android-ripple imports color-contrast

Note: If you are targeting Android as the platform for your app, you will need to import android-ripple. This will implement the Material Design ripple effect in your app, no setup or configuration needed. Import it in your app.js file.

To import a module, use the following format. Be aware the the path need to work for where you are importing the file from. The following would work if you were importing them into your app.js file:

import './src/android-ripple';
import './src/form';
import './src/segmented';
import './switches';

Box - Local Data Persistence

If you need local data persistence, you can take advantage of the mobile browser's support for IndexedDB, WebSQl or localStorage using ChocolateChip-UI's Box. This is an abstraction layer to these three datastores, providing you with a convenience and easy to use interface for local data persistence.

Box is not in the default build of ChocolateChip-UI. Instead Box is a separate module. You can create a project with support for Box using the flags --box or -b when you create your project. This will give you the following files in your js folder:

  • chui-box.js
  • chui-box.min.js
  • chui-box.min.js.map

Your app's index.html file will automatically point to these. To learn how to use Box, please read its documentation.

Project Options

Below are a number of possible ways to create a project:

// Create a basic project for iOS:
chui -n myapp 

// Create a basic navigation project for Android:
chui -n myapp -o android -t navigation

// Create a basic slide out app for Android Phone:
chui -n myapp -o android -t slideout

// Create a basic tab bar app for iOS:
chui -n myapp -o ios -t tabbar

// Using JSPM and Babel (--jspm or -j)
// Create a basic list app for iOS using JSPM:
chui -n myapp -j

// Create a basic list app for Android using JSPM:
chui -n myapp -o android -j

// Create a basic list app for iOS phone using JSPM:
chui -n myapp -o ios -j

// Create a navigation list app for iOS using JSPM:
chui -n myapp -o ios -t navigation -j

// Create a slide out app for Android using JSPM:
chui -n myapp -o android -t slideout -j

// Create a tab bar app for Android phone using JSPM:
chui -n myapp -o android -t tabbar -j

// Using Box (--box or -b)
// Create an app with support for JSPM and Box:
chui -n myapp -t slideout -j --box

// Create an Android app with JSPM and Box:
chui -n myapp -o android -t tabbar -j -b 

Using Template Literals

Because this setup is using Babel, you can use ES6 template literals in your app.js file. By default all templates in the app.js use ES6 template literals. These simplify how to write view templates. Just enclose the template between an opening and closing back tick, no need to escape new lines or quotes:

var MusicView = $.View({
  element: '#musicList',
  variable: "song",
  // Use template literal:
  template: 
  `<li>
    <img src='{= song.image }'>
    <div>
      <h3>{= song.title }</h3>
      <h4>{= song.album }</h4>
      <p>{= song.description }</p>
    </div>
  </li>`
});

JSPM Examples

To get examples of ChocolateChip-UI projects using JSPM, run:

chui -r

This will output four reference apps to your desktop in the folder "Chui Reference Apps". Open the folder, open the JSPM folder and look at how the project's code is organized in the dev folder. You can learn more about the reference apps in documentation.

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.

If you are trying to create an app for Android and you keep getting iOS, check the os flag. It needs two hyphens for the long form: chui --os ios, or chui --os android. It needs one hyphen if you are using the single letter version: chui -o ios, or chui -o android.

If after running a command you get this error:

throw new TypeError('Arguments to path.join must be strings');

Check your hyphens. You're missing a double hyphen for an argument that needs them somewhere. Only single letter flags can use one hyphen. Two hyphens are required in all other cases.

Build Speed

Because we are using both JSPM and Babel, 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 outways 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.

JavaScript Intellisense

You can get JavaScript intellisense in editors or IDEs that have proper support of TypeScript. To make this posible we provide a TypeScript declaration file for ChocolateChip-UI's types and call signatures. To get these use the flag --ts when you create your project. Notice that this requires two hyphens with the flag. A single hyphen with ts will throw and exception:

// Create a project with TypeScript support:
chui -n MyProject -t navigation -o android --ts

When you create a project with this flag, it outputs the folder typings at the root of your project, along with a file called jsconfig.json. Editors that understand TypeScript declaration files can use these to provide code completion, hints and code signatures as you type or hover over ChocolateChip-UI code.

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.