Docs

Everything You Need to Know

Tutorials

Getting Started

Creating a Simple Project, or Advanced Project Setup

You could create a project by copying all the files you need from the Github sources files, but then why would you want to do that? There are better ways.

NPM Module

ChocolateChip-UI has an NPM module for quickly creating ChocolateChip-UI projects. Just install the module globally on your machine and you're ready to start cranking out ChocolateChip-UI apps. When you use this module to create a project, it gives you both development and minified versions, a basic app structure and a TypeScript declaration file which you can use with your Text Editor or IDE for tooling (Intellisense, code completion, etc.).

Before you can do anything, of course, you've got to install the NPM module:

npm i -g chui

On a Mac or Linux you will need to run this with sudo, which will ask you for your password.

Creating a Browser-based App

These command are all about create a simple html file that loads the theme you chose and the supporting JavaScript. At this stage you can double click your app to launch it in a browser. There is no build step. This makes it easy to get going. If you are looking for a more advanced setup with support for ES6 modules, etc., please see the section on advanced setup.

Create Your Project

Using the chui command line tool, you can use the following options:

  • --name or -n A name for your project
  • --path or -p A path to where you want your project put
  • --os or -o The operating system you want to target
  • --type or -t The type of app shell you want

Let's break these down. Notice that each option has two versions of the flag - a long form with double hyphens and a short for with one hyphen and one letter. You can choose which you prefer.

To successfully create a project, ChocolateChipJS needs at least two values: a name for the project and an OS to target. The name can be whatever you want. Please note if there is already a folder in that location with the same name as the project you are creating, it will be replaced with your new project. If you want to replace an existing project, not a problem, but you do need to be aware of this. The other value you must provide is an OS: android, ios or win. These must be lower case. This will provide the correct theme for the target operating system.

// Create an iOS app:
chui -n myApp -o ios
// Create and Android app:
chui -n myApp -o android
// Create a Windows Phone app:
chui -n myApp -o win

Running any of the above commands will create a base app shell for the designated operating system. Because a path was not provided, it will be created on the user's desktop. If you want to create the project at a specific location, you'll need to provide the path flag:

// Create an iOS app:
// Path is for Mac OS X:
chui -n myApp -o ios -p ~/Documents/Dev
// Create and Android app:
chui -n myApp -o android ~/Documents/Dev
// Create a Windows Phone app:
// Path is for Windows file system:
chui -n myApp -o win ~\Documents\Dev

You can also tell ChocolateChipJS to create a particular type of app shell. The default is a single screen with a static list. Using the type flag you can create a navigation list with routing, simple tab bar or a slide out menu app. These will have working code included, giving you a clear idea how to customize them and make them work for your needs. The type flag can handle four values: default, navigation, tabbar and slideout. If no type flag is provided, then the default type will be created:

// Create a default app:
chui -n myApp -o ios -t default
// Create a navigation list:
chui -n myApp -o android -t navigation
// Create a tab bar interface:
chui -n myApp -o win -t tabbar
// Create a slide out menu app:
chui -n myApp -o ios -t slideout

Advanced Development Setup

So far we have seen how to set up a very simple working project to get you going. However, you can also use ChocolateChipJS to setup a more advanced development environment for you. This differs from the pervious build process in that it requires a build step to run the app. An advanced project is create using the --jspm or -j flags with your project command. This will give you a project that includes JSPM as the package manager, as well as Babel and Browsersync. This allows you to write your project's code using ES6, including ES6 module syntax to import only the modules and widget you need for your project. JSPM with use Babel to transpile and bundle all the files and their dependencies into on file that your app loads. Here are some possible project examples:

// Create an app:
chui -n myApp -o ios -t default -j
// Create a navigation list:
chui -n myApp -o android -t navigation -j
// Create a tab bar interface:
chui -n myApp -o win -t tabbar -j
// Create a slide out menu app:
chui -n myApp -o ios -t slideout -j

Custom Build

Besides the above options, you can also create a project that has a minimal build of ChocolateChip-UI. Then you can import just the widgets you need. This gives you a substantially smaller final file size. To do this, just include the -c flag in your commands:

// Create an app with minimal build:
chui -n myApp -o ios -t default -j -c
// Create a navigation list:
chui -n myApp -o android -t navigation -j -c
// Create a tab bar interface:
chui -n myApp -o win -t tabbar -j -c
// Create a slide out menu app:
chui -n myApp -o ios -t slideout -j -c

By default the minimal build supports navigation lists. As such, the first two projects do not need to import anything. However for the tabbar and the slideout, you would need to import them into your project. Actually, the command does this for you, so you don't have to do anything. If you look at the resulting files in your app's dev folder and examine the app.js file. You'll see how the modules for the widgets get loaded. Of course, if you want to use other widgets, you will need to import them as well. For a better example of how widgets get loaded where they are needed, take a look at the JSPM version of the reference apps. Run chui -r in the terminal, then open the jspm folder. Each project has a dev folder. Check out how each project imports widgets where they are needed in either the app.js file, or in other modules that it is importing.

Below is a list of all the importable modules:

  • 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';

Building your Custom Project

In order to build and run your custom app, cd to the project and run:

npm i

When the install finishes, run:

jspm i

After that you can just run:

gulp

This will build your app, importing dependencies and modules, start watchers and launch a server and browser instance to load your app. From then on when you edit and save app.js or index.html, JSPM will recompile your project and load it in the browser.

Importing Modules and Widgets

At the top of the app.js file in the dev folder you will see how modules are imported. Each project type has a different organization of dev files to show you possible ways to organize your code. To learn more about how to use ES6 modules to organize your project, take a look at the demos.

Troubleshooting

Sometimes, due to latency in gulp streams, one or more files might not copy over properly. If after running both npm and jspm installs on your project and gulp to start a browser instance, you see that your project is not loading properly, such as missing styles or data, try runing your exact same command you used to create the project again. Then restart the server with gulp. You should see the complete project load.