Permalink
Browse files

README update

  • Loading branch information...
1 parent f4fcaae commit 9f24895bb91ddae48b73363cc428f52621a173bb Evan Miller committed Jul 2, 2011
Showing with 134 additions and 2 deletions.
  1. +134 −2 README.md
View
136 README.md
@@ -5,7 +5,7 @@ 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 doesn't suck.
+from other Erlang frameworks is that it is easy to set up and use.
60-second Quickstart
@@ -52,9 +52,141 @@ By default CB uses an in-memory database that needs no configuration. To start
working with an actual database, See README_DATABASE
-Developer Documentation
+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 slowing 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:
+
+ 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
+
+ {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
+
+ {{ 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
+alwas 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 routes.config file.
+
+*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 prouction 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:
+
+ 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 number of 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
<http://www.chicagoboss.org/>

0 comments on commit 9f24895

Please sign in to comment.