Welcome to Cappuccino!

Cappuccino is an open source framework that makes it easy to build desktop-caliber applications that run in a web browser.

Cappuccino is built on top of standard web technologies like Javascript while implementing the familiar API's of Apple's Cocoa framework. When working with Cappuccino, Cocoa programmers don't need to concern themselves with the complexities of traditional web technologies like the DOM or cross browser concerns. Conversely, developers and designers coming from a traditional web background can focus on what makes their app work while utilizing the powerful interface and application concepts exposed by Cappuccino.

Cappuccino is predominantly a front-end technology. Most of the time, your application will execute entirely in the users browser. You can communicate with your back-end using standard Ajax requests, which Cappuccino provides a wrapper class for. This means Cappuccino is "back-end agnostic"; it will work with any type of back-end you have (Rails, Django, Node, etc.), as long as it provides an API you can access via standard Ajax requests.

For more information, see the Cappuccino website.

Getting Started

This starter package contains three main components:

Sample Application - A simple application for you to build from, containing the full Cappuccino framework.
Documentation - A reference and overview of the entire Cappuccino framework.
Bootstrap Script - Guides you through installing a number of tools helpful for building Cappuccino apps.

The sample application contains a simple "Hello World" example as well as the full Cappuccino framework. You can use this as a test bed or a starting point for your application. You can get started by editing the AppController.j file, or try following along with a tutorial.

Bootstrapping the Toolchain

The Cappuccino toolchain is based on a number of build tools. The bootstrap starts by installing them, and then the following Cappuccino-specific packages:

capp - A simple utility for generating new Cappuccino applications. Read More
nib2cib - You can use Apple's Interface Builder to visually design the UI for your application. The nib2cib tool allows you to convert a nib or xib file to a cib, a format Cappuccino can understand. Read More
XcodeCapp - a utility which builds on top of nib2cib to automate the nib2cib process while preparing the necessary Xcode 4.0 compatible project files. By default, it is installed in /usr/local/narwhal/packages/cappuccino/support/XcodeCapp.app. It comes with its own documentation.
Jake - Similar to the Rake utility in Ruby, Jake is the main mechanism used to build both the Cappuccino framework and your own applications. Read More
Press - Another build tool, Press strips unused files from your application. In other words, if your application never uses CPTableView, Press will strip CPTableView.j out of your application before deployment, thereby reducing the download size. Read More
Flatten - The final build tool, Flatten merges your compiled code into a single .js files. This reduces the number of server requests required to load your application and speeds up loading your application. Read More

Jake also performs a very unique image spriting process, which you can read about on the Cappuccino blog.

If you want to install the Cappuccino toolchain, which is not necessary for the basic starter application, you can enter the following into your Terminal: cd CappuccinoStarter-0.9.5 ./bootstrap.sh

Building a New Application

Writing a Cappuccino application may be a different experience than what you are used to if you come from a traditional web background. The starter package includes a sample application, but what if you want to start from scratch?

To create a brand new Cappuccino application, you can use the capp utility installed by the bootstrap script. You will need to decide if you want to layout your application UI in Interface Builder or programatically.

If you want to lay out your application in code, enter the following command into your Terminal: capp gen MyApplication

If you want to use Interface Builder, enter the following command into your Terminal: capp gen -t NibApplication MyApplication

Note that you are free to mix and match both methods within the same application, these steps simply determine which template will be used to create the skeleton for your new application.

You can run your newly created application by opening index.html or index-debug.html in your web browser. (Note: Chrome users should read this article about developing locally with Chrome).

Why do you have two index files though? The reason is that index-debug.html uses a debug version of the frameworks which makes it much easier to spot bugs and run traces in your code. However this version of the frameworks is not meant for production use.

You can learn more about putting together a Cappuccino application by following along with the starter tutorial.

When you are ready to deploy your application, we supply a few different ways to build your code. The main build tool is jake, which will compile all of your Objective-J code into raw Javascript; while Objective-J is a strict Javascript superset, performing this step ahead of runtime increases the load speed for your application. Jake contains a few tasks for your application by default. jake debug builds a debug version of your application while jake release builds a fully compiled version. jake deploy will build your application in release mode and finally run the press utility on it.

Editors

Getting Help

If you need help with Cappuccino, you can get help from the following sources:

FAQ
Documentation
Wiki
Mailing Lists:
- Objective-J Group
- Objective-J Dev Group
IRC: irc.freenode.net #cappuccino

If you discover any bugs, please file a ticket on our Issue Tracker.

Notes:

Chrome users: http://cappuccino.org/learn/tutorials/getting-setup.php#chrome

How To Read The API Documentation

The documentation is broken down into Modules, Classes, Files.

Modules

Cappuccino has two major frameworks: "AppKit" and "Foundation". AppKit contains all the classes that help you build the interface for your application. Views, buttons, the event system, etc. are all part of AppKit.

AppKit also includes a library called CoreGraphics. This is listed as its own module in the docs. CoreGraphics gives you a Javascript API for doing pixel-level drawing. This API renders to both the HTML5 canvas element and the IE VML element.

Foundation contains various primitive object classes like CPObject (from which all Cappuccino classes are derived), CPArray, CPDictionary, and many others.

When you click on any of the modules on the Modules page you will see a full list of classes inside that framework. Once you select the class you would like to view, you will see a list of all the public methods for that class. Go to the "Navigating the Class Page" section for details on how to read the API.

Classes

The Classes section gives you a list of all the classes found in Cappuccino. To the right of that is sometimes a short description of what the class does. This includes classes from both AppKit and Foundation. Clicking on any of the class names will give you a method listing, which you can read about in the "Navigating the Class Page" section.

Files

Finally, the "Files" section will give you a list of the files that compose Cappuccino. Clicking on a file will give you an list of all the variables defined in that file. Many times you will use these as enumerated values which you can pass to methods, however, in most places, we have listed the values you can use for a method inline in the method listing.

Navigating the Class Page

Each method has its own line. In parenthesis on the left you will see the return type for that method. If you see "id" instead of something specific like "CPArray" or "BOOL", it means the method is polymorphic and could return any object type. Most of the time this is because you set a specific property on an object that can be of any type. Below the first list of methods may be another section called "Static Public Member Functions". Notice the "+" in front of the method name. This indicates they are class methods. That is, methods you call on a class instead of an instance of a class.

Below the method listing is usually a longer description of what a class does and how to use it.

Next, you will find specific documentation for the methods of the class. The first line will me the method declaration; something like:
- (BOOL)autoscroll:(CPEvent)anEvent

This is your standard Objective-J method signature. Below each method will be the documentation for that method, a line or more about what the method actually does, followed by a list of the parameters and return value.

Finally, there will be a line number where the method is implemented in its class file. Clicking on that line number will take you to the method implementation code itself.

Searching

Performing a search in the documentation will search through all three of the aforementioned sections. If the search result has a ".j" at the end of it you can assume it will take you to the file page instead of the class page. If you see a small file name below a link that is a good indication that the link will take you to a variable (for example, for an enumerated value).

Enjoy Cappuccino

Thanks for using Cappuccino. You can always find more information at http://cappuccino.org.