Iceberg (Pre-Alpha)

Iceberg is a full-stack web framework in crystal-lang. It aims to serve as a MVC framework for developers to quickly create a functional website or software.

NOTE: It is in its very earlier stage and should not be used in production environment. However, feel free to try it out, request features, or report bugs.

Requirement

At least Crystal 0.8.0 installed.

Installation

1. Create a Crystal project

$ crystal init app project_name

2. Add to shard.yml

dependencies:
  iceberg:
    github: adlerhsieh/iceberg

3. Run shards command.

4. Run ./libs/iceberg/iceberg/bin/setup command.

It creates the necessary config files for you.

My First App

Check src/controllers/app_controller.cr. There should be an index action.

# This is default.
class AppController < Iceberg::Controller
  def index
    view :index
  end
end

And the same in src/views/app/index.cr.

# This is default.
class AppIndexView < Iceberg::View
  def process
  end
  html :app, :index
end

No need to change anything above for our first app.

Now, go to src/routes.cr and route root to AppController:

Iceberg::Router.draw do
  # Add this
  get "/", :app
end

And add the following to src/views/app/html/index.ecr.

Hello World!

Finally:

1. Run ./server command in root directory.
2. Go to http://localhost:2000.
3. You will see Hello World.
4. Yay!

Configuration

Routing

Route mapping is in src/routes.cr file. Available syntax:

Iceberg::Router.draw do
  get "/", :app              #=> route "/" to AppController#index
  get "/app", "app#index"    #=> ditto
  get "/new_app", "app#new"  #=> route "/new_app" to AppController#new action
  post "/new_app", "app#new" #=> ditto, but with POST request
end

Controller

Controller receives http request and decides what to process. It is designed to handle only http requests so don't put any business logic here. Leave it to view classes.

Current functionality:

Render HTML

The controller passes the action to View and handles all operations there. A View returns a string of HTML that will respond to the browser.

The syntax is view :action, where Iceberg looks for a view class name contains both Controller name and Action name. For example:

class MyController < Iceberg::Controller
  def index
    # this action looks for MyIndexView in `views` directory 
    view :index 
  end
end

You can either specify another view file.

class MyController < Iceberg::Controller
  def index
    # this action looks for MyAppView in `views` directory 
    view :app
  end
end

However, it is recommended to pair the names of a view and controller action together.

View

View is where your logic is. It uses ECR library to embed Crystal into HTML text. The most important part is that it brings instance variables into HTML, like ERB in Ruby. Check ECR library usage in Crystal official repo.

One view class renders one file. This is a little different from Rails in which view is defined in a controller action. The process action is necessary since Iceberg takes it as the main function in this class, like func main in Golang.

It works like this:

class AppIndexView < Iceberg::View
  def process
    @name = "John"
  end
  html :app, :index
end

And in your index.ecr file:

Hello, <%= @name %>

You will see Hello, John in browser.

In addition, it is recommended to organize your view folder structure like:

src
|--views
  |--app
    |--index.cr
    |--html
      |--index.ecr

Under the views directory, app is the name of a controller class, and index is its action. The html folder contains all ecr files.

Stay Tuned

Everything is still in progress. It will be officially released once it's ready!

Contributing

1. Fork it ( https://github.com/adlerhsieh/iceberg/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request