Docs

Everything You Need to Know

Tutorials

Getting Started

Creating a Project

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.

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

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

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 -t tabbar
// Create a slide out menu app:
chui -n myApp -o ios -t slideout

Importing Widgets

After creating a project, you can import the widgets or utiltiies you need. This gives you a substantially smaller final file size.

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 widgets:

  • android-ripple
  • color-contrast
  • ui-editable
  • ui-form
  • ui-multi-select-list
  • ui-paging
  • ui-popover
  • ui-popup
  • ui-range
  • ui-segmented
  • ui-select-list
  • ui-sheets
  • ui-slideout
  • ui-stepper
  • ui-switch
  • ui-tabbar

Some widgets have dependencies on other modules, but they import them automatically. They are:

  • ui-navigation imports ui-router
  • ui-paging imports ui-navigation and ui-router
  • ui-paging imports ui-navigation and ui-router
  • ui-popover imports ui-block
  • ui-popup imports ui-block
  • ui-slideout imports ui-block and ui-router
  • ui-tabbar imports ui-router
  • ui-form imports validators
  • android-ripple imports color-contrast

Note: If you want to use a navigation list with either a ui-slideout or ui-tabbar widget, you'll need to also import the ui-navigation widget.

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/widgets/android-ripple';
import './src/widgets/ui-form';
import './src/widgets/ui-segmented';
import './src/widgets/ui-switch';

You can also import any of the various utility functions into your app. They're in the dev/src/utils folder:

import './src/utils/array_flatten';
import './src/utils/array_intersection';
import './src/utils/compare';
import './src/utils/throttle';

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:

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, the gulp will recompile your project and load it in the browser.

Organizing Your Project

Before writing code, you might want to have some idea about the best way to organize your project's code. To learn more about project organization, take a look at this tutorial.

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.