All source files are created and managed by type in src/.

There three output directories:

  • local/ - Development and testing
  • build/ - Intermediate directory prior to optimizations and/or concatentation
  • dist/ - Final output for release purposes. This carries over to the master branch to be copied in the root of the repo.

Each Grunt task has a task named local which performs copying, compiling or symlinking in the local/ directory for development. Additional tasks may be defined for build or dist depending on the requirements.

Shared options for a task should be defined first, followed by each task entry. Each task can define it's own set of options to override the shared ones defined for the task.

CoffeeScript

There are two primary components: models and ui. Models and collections act as the data containers and interact with the server via the Serrano REST API. Views, regions, and layouts provide the HTML representation and behavior of that data to the user.

The general directory structure looks like this:

cilantro.coffee
cilantro/
    |.. ui.coffee
    |.. ui/
        |.. core.coffee
        |.. *
    |.. models.coffee
    |.. models/
        |.. base.coffee
        |.. *
    |.. *
plugins/
    |.. *

SCSS

TBA

Nothing is better than being able to easily preview and interact with a UI component by itself. This confirms the desired look and feel, but more importantly how the component behaves in the simplest environment.

Cilantro comes with a gallery page that is intended to preview views, regions and layouts in isolation. This helps the development process (reduces the time and steps needed to get to the state of testing the component) and provides a great way to see what Cilantro provides out-of-the-box.

Run the included Node server grunt connect and go to http://localhost:8125/gallery/index.html to view and start using the gallery.

View Boilerplate

The boilerplate steps include:

  • Create a CoffeeScript file somewhere in the src/coffee/cilantro/ui/ directory
    • Use your judgement to where it should exist
  • Add the import to the parent file, e.g. views.coffee that bubbles down the ui.coffee file
  • For views that require complex HTML, create a template for the view in src/templates/, e.g. src/templates/concept/item.html
  • Create a SCSS partial in the src/scss/ directory, e.g. src/scss/views/_something.scss
  • Add the @import statement to src/scss/style.scss
  • Create a JavaScript file in gallery/, e.g. gallery/views/path.js that initializes a view (optionally with some data) and return it:
define(['cilantro'], function(c) {
    var view = new c.ui.SomeView;
    return function(dom, navigator) {
        c.data.fields.when(function() {
            view.model = c.data.fields.get(1);
            view.render();
        });
        dom.html(view.el);
    }
});
  • Add a navigation entry to gallery/index.html
    • Something like <li><a data-module="./views/path.js">NameOfView</a></li>
  • Create a Jasmine spec file in spect/SomeViewSpec.js