Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ChicagoBoss/ChicagoBoss

Erlang web MVC, now featuring Comet
https://github.com/ChicagoBoss/ChicagoBoss

erlang framework web-framework

Last synced: 3 months ago
JSON representation

Erlang web MVC, now featuring Comet

Awesome Lists containing this project

README 

        
Chicago Boss: Start small, dream big

====================================

[![Build Status](https://travis-ci.org/ChicagoBoss/ChicagoBoss.svg?branch=master)](https://travis-ci.org/ChicagoBoss/ChicagoBoss)



Attention! This is a master branch supporting Erlang 18. For older Erlang versions use legacy branch.



Chicago Boss is a server framework inspired by Rails and written in Erlang. It

offers all the conveniences of modern web development, including Comet. What sets

Chicago Boss apart from other non-Erlang frameworks is that it can handle large

amounts of traffic without any drop in performance. What sets Chicago Boss apart

from other Erlang frameworks is that it is easy to set up and use.



WARNING: Chicago Boss does not work with Erlang R16B03 due to an error in erl_syntax



60-second Quickstart

--------------------



After downloading and extracting, type



```console

make

make app PROJECT=mynewproject

cd ../mynewproject

./init-dev.sh

```



For Windows, type



```console

windows-make.bat

windows-make.bat app PROJECT=mynewproject

cd ..\mynewproject

start-server.bat

```



Then visit http://localhost:8001/ in your browser. Congratulations, you have

a web server. There will be a lot of PROGRESS REPORTs on your console but

everything should be running smoothly.



The project name should be a legal Erlang atom, i.e. start with a lowercase

letter and contain only letters, digits, and underscores (for easy compatibility is recommended name the project dir and app name the same).



Dependencies

------------



* Erlang 19.0 or later -



    



  * Check with `erlang:system_info(otp_release)`.



* On Windows Vista or Windows 7 -



  * Erlang bin directory must be in PATH.



Admin Interface

---------------



You probably want to install the CB admin interface. Download it from



    



Upgrades

--------



Uprading used to be a pain but now it is easy. See README_UPGRADE



Database Setup

--------------



By default CB uses an in-memory database that needs no configuration. To start

working with an actual database, See README_DATABASE



Philosophy and Features

-----------------------



Why another web framework? Because Rails apps are slow and Node apps are messy.

Chicago Boss takes advantage of functional programming and under-the-hood

compiler magic to provide clean, understandable controller logic, Django-style

templates, and an ORM based on Erlang's parameterized modules. The best part is

that the network I/O is 100% asynchronous so you can seamlessly integrate Comet

endpoints into your app, and you never have to worry about a slow database

query dragging down unrelated requests.



CB ships with all the tools you need to build a feature-ful website, including

sessions, URL routing, filtering requests and post-processing responses,

frameworks for sending and receiving email, JSON generation, Comet via

long-poll and message queues, and internationalization (i18n). Read on for

details.



*Databases*. Chicago Boss currently supports MySQL, PostgreSQL, Tokyo Tyrant,

Mnesia, MongoDB, and Riak. In CB 0.5.4 and later, you can mix and match

databases by configuring Boss to use vertical shards. For SQL databases, the

conventions are similar to Rails (plural nouns for the table names, object_id

for foreign keys, etc.).



*BossRecords*. Boss's take on ActiveRecord is called a BossRecord, which is

an Erlang parameterized module on steroids. You instantiate a BossRecord like

a regular parameterized module:



```erlang

Article = article:new('id', "This is a title", "This is a body")

```



But then CB generates functions and attaches them to BossRecords, so you can

write code like



```erlang

{ok, SavedArticle} = Article:save()

```



Before saving to the database, the save() function will call a function called

validation_tests(), where you can perform custom validation logic.



CB also generates getter functions which can be invoked directly in templates,

so in your template you can write things like



```erlang

{{ article.title }}

```



Speaking of which...



*Templates*. Chicago Boss uses ErlyDTL, an Erlang implentation of Django template

language. In fact, Chicago Boss originated with a rewrite of ErlyDTL, and the same

person maintains both projects so you always get the latest ErlyDTL features. Templates

can access and loop over values stored in proplists, dictionaries, and BossRecords,

so you can move data from the database to your templates with a minimum of massaging.



In addition, templates are tightly integrated with Boss's i18n machinery. The admin

interface automatically parses templates for translatable strings, and Boss can

choose which language to serve based on the request's Accept-Languages header and

the calculated translation coverage for a particular page. Multi-language websites

are easy to develop with Chicago Boss.



*Controllers*. Erlang's pattern-matching is a perfect fit for writing

controller logic. Your controllers are passed the URL method (GET, POST) and a list

of URL tokens, and just need to return a tuple telling Boss what to do, for example:



* `{ok, Variables}` - render the default template with Variables

* `{render_other, Variables}` - render another template

* `{redirect, URL}` - redirect the request

* `{json, Proplist}` - encode the Proplist as JSON and send to the client

* `{output, Data}` - send Data to the client



If you come from Rails, you'll instantly notice the benefit of Erlang's

language design: you don't need an ugly `case request.method` statement inside

every action, you never have atrocities like `render and return`, and you can

always see every variable that is in scope. In CB apps, controller logic is

always concise and usually a pleasure to read.



*Sessions*. You can configure sessions to be stored in memory (ETS) or in an

Mnesia database.  The `boss_session` and `boss_flash` modules provide functions

for storing and retrieving session information.



*Routes*. By default, Chicago Boss uses the same routing conventions as Ruby on

Rails (`/controller/action/id`). You can customize the routes and provide

a base URL in the priv/application.routes file. Of course, most routing occurs

with the pattern-matching controller logic, e.g.

```erlang

posts('GET', ["category", Category]) ->

```



You can then generate URLs to match controller patterns in your templates like

so:



    {% url action="posts" category="some category" %}



*Email*. Chicago Boss ships with a miniature MVC for sending multipart emails.

Emails can be templated with ErlyDTL, and it is easy to provide plain-text and

HTML versions of the same email. In testing environments, email can be sent

directly to the recipient, or in production can be relayed to an SMTP server.



A Chicago Boss server can also receive email over SMTP. Each email address maps

to a function in your incoming mail controller, so it is easy to write

well-organized email applications. Your email controller has access to the

exact same resources as your web controllers, including database requests,

BossRecord instantiation, and the message queue; web and email are fully

integrated.



*Comet*. It's simple to write a Comet endpoint in Chicago Boss. Unlike any

other language, Erlang gives you the benefits of asynchronous network

communcation without using callbacks. Here is a trivial example of a long-poll

controller:



```erlang

longpoll('GET', [Channel]) ->

    {ok, Timestamp, Messages} = boss_mq:pull(Channel, last),

    {json, [{timestamp, Timestamp}, {messages, Messages}]}.

```



The call to `pull` blocks until a message is received. Because processes are

cheap in Erlang, the overhead of keeping alive a blocking request is very small

(just a few kilobytes of memory, compared to megabytes in Rails). You can

thus keep alive thousands of Comet request with just a few megabytes of memory.

Also notice that the controller logic remains nice and clean (no callbacks). We

can perform an arbitrary sequence of asynchronous network requests without

increasing the scope level.



*Events*. An interesting feature of Chicago Boss is the events API called

BossNews. With it, you can watch a record or a set of records for changes,

then execute a callback when a change is witnessed. Combined with long-polling,

you can provide a real-time view of your database on your website. Events can

also be used to provide a clean separation of business logic and notification

logic.



*Tests*. Chicago Boss has a kick-ass testing framework. Once you try it you

won't go back. That's all I'll say for now.



Future Work

-----------



Most of Chicago Boss's planned features have been implemented at this point. It

hasn't really been tested in a distributed environment, but it's already

running on a few public-facing websites, and many more internal websites (or so

I am told). It would be nice to add more databases (such as CouchDB and Oracle)

and support horizontal sharding. The last main feature before 1.0 will be

the ability to distribute apps written in Chicago Boss as standalone OTP

applications.



Further Reading

---------------



See the FAQ and API files located at



If you need help getting started, check the new pdf tutorial:



Be sure to also check the wiki



There's also the mailing list:



If you want to contribute to CB



[CODING_STANDARDS.md](https://github.com/ChicagoBoss/ChicagoBoss/blob/master/CODING_STANDARDS.md)



View the CHANGELOG.md



[CHANGELOG.md](https://github.com/ChicagoBoss/ChicagoBoss/blob/master/CHANGELOG.md)