Release 0.0.3

Correct some types, implemented help file, and started documentation

.npmignore

@@ -1,2 +1,3 @@
 .DS_Store
-.git*
+.git*
+*.log

History.md

@@ -10,4 +10,11 @@
   * Major refactoring as we develop our examples
   * Reworked areas towards convention over configuration
   * Uses the CoffeeKup view engine by default
-  * Created Story timbit to be used as a real world prototype
+  * Created Story timbit to be used as a real world prototype
+
+0.0.3 / 2011-07-05
+==================
+
+  * Fix some typos
+  * Started documentation
+  * Implement default help.coffee file

README.md

@@ -7,11 +7,41 @@ Timbits is an attempt to build an easy and reusable widget framework on top of E
 
 It's primarily meant to serve internal purposes as Postmedia Network Inc, however it is being open sourced under the MIT License.  Others may find some use for what we are doing, and still others may be able to help turn this into a more generic and useful solution by contributing and/or correcting our ignorant ways.
 
-Be kind.  We're coming from years of .NET experience and some Ruby on Rails.  This is our first foray into Node.js development and we're still figuring things out.  Constructive criticism is encouraged.  If you see something odd and think to yourself "WTF?" then by all means, let us know.
+Be kind.  We're coming from years of .NET experience and some Ruby on Rails.  This is our first foray into Node.js development and we're still figuring things out.  Constructive criticism is encouraged.  If you see something odd and think to yourself "WTF?" then by all means, let us know.  We are eager and willing to learn.
 
-## Usage
+## Installing
 
-Yea, we're not even close to having useful documentation yet.  Stay tuned.
+Just grab [node.js](http://nodejs.org/#download) and [npm](http://github.com/isaacs/npm) and you're set:
+
+	npm install timbits
+
+Timbits is simplistic and finds most of it's power by running on top of some very cool node libraries such as [express](http://expressjs.com/), [CoffeeScript](http://coffeescript.org) and [CoffeeKup](http://coffeekup.org/).  As such don't forget to install dependencies.
+
+	npm install -d
+
+## Using
+
+Yea, we're not even close to having useful documentation yet.  Stay tuned.  In the mean time, review the example.
+
+The structure of a timbits application is fairly simple.  To start, you need a two lines in your main app.coffee file.  (If you really hate typing, this could easily be converted to one, but far less flexible)
+
+	timbits = require 'timbits'
+	timbits.serve()
+
+Also ensure (at least for now, due to lack of error handling) that you create the following subfolders:
+
+* /public - images, javascript, stylesheets etc.
+* /timbits - this is where we place the individual timbit (widget) files
+* /views - views for a particular timbit are placed in a subfolder of the same name
+
+When you start the server, it will automatically load all the timbits loaded in the /timbits folder.  The name of the timbit is determined by the name of the file, and that name in term determines the default route (/name/:view?) and the default view (/views/name/default.coffee).  Aside from the location and name of the timbits, the rest is customizable as shown in the examples.
+
+The simplest of timbits takes the following form:
+
+	timbits = require 'timbits'
+	timbit = module.exports = new timbits.Timbit()
+
+That's it.  If you created this as /timbits/test.coffee and placed a default view at /views/test/default.coffee, you could "eat" this timbit by going to /test in a browser.  See the "plain" timbit for an example of this.
 
 ## Outstanding Issues
 
@@ -20,11 +50,13 @@ Way too much at this time.  On the short list (and mostly in progress):
 * Integrated testing framework
 * Integrated benchmarks
 * Command line server with ability to automatically restart
-* Documentation
+* Command line code generator to scaffold a new project or timbit
+* Security considerations
+* Error handling of any sort
 * Refactor and expand data retrieval, including caching, conditional GETs, XML support
 * Support for alternate server configurations
-* More examples
-* Deployment and monitoring process
+* More/Better examples
+* Documentation, Documentation, Documentation
 
 ## Created by
 

examples/timbits/plain.coffee

@@ -1,8 +1,8 @@
 # Plain Timbit
-# Example of the simplist timbit that could possibly be created.  
+# Example of the simplest timbit that could possibly be created.  
 # This timbit will simply render a view using data from the query string
-# pass in 'item' via the querystring
-# e.g. /plain?item=World
+# pass in 'who' via the querystring
+# e.g. /plain?who=World
 
 # load the timbits module
 timbits = require '../../src/timbits'

examples/views/help.coffee

@@ -0,0 +1,56 @@
+doctype 5
+html ->
+	head ->
+		title 'Timbits - Examples'
+	body ->
+		h1 'Timbits - Examples'
+
+		h2 'Plain Timbit'
+
+		p 'Example of the simplest timbit that could possibly be created.  
+			 This timbit will simply render a view using data from the querystring.'
+
+		ul ->
+			(li -> a href: '/plain', -> '/plain')
+			(li -> a href: '/plain?who=World', -> '/plain?who=World')
+
+		h2 'Cherry Timbit'
+
+		p 'Example of a timbit which actually does something.
+			 This timbit will display the current server time.'
+
+		ul ->
+			(li -> a href: '/cherry', -> '/cherry')
+
+		h2 'Chocolate Timbit'
+
+		p 'Example of a timbit which transforms remote data.
+			 This timbit will query twitter and display the results.
+			 There are two views available, the default and the alternate.'
+
+		ul ->
+			(li -> a href: '/chocolate', -> '/chocolate')
+			(li -> a href: '/chocolate?q=coffeescript', -> '/chocolate?q=coffeescript')
+			(li -> a href: '/chocolate/alternate?q=coffeescript', -> '/chocolate/alternate?q=coffeescript')
+
+		h2 'Dutchie Timbit'
+
+		p 'Similar (in function, not taste) to the chocolate timbit
+			 This timbit displays some more advanced features such as 
+			 specifing a custom route and overiding the render implementation
+			 with custom code (just because)'
+
+		ul ->
+			(li -> a href: '/dutchie', -> '/dutchie')
+			(li -> a href: '/dutchie/nodejs', -> '/dutchie/nodejs')
+			(li -> a href: '/dutchie/nodejs/alternate', -> '/dutchie/nodejs/alternate')
+
+		h2 'Story Timbit'
+
+		p 'Our prototype of a "real world" widget.
+			This one will retrieve and display a story from our CMS (SouthPARC)'
+
+		ul ->
+			(li -> a href: '/story/5102148', -> '/story/5102148')
+			(li -> a href: '/story/5089233', -> '/story/5089233')
+

package.json

@@ -1,7 +1,7 @@
 {
   "name": "timbits",
   "description": "Widget framework based on Express and CoffeeScript",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "author": "Postmedia Network Inc.",
   "contributors": [ 
     { "name": "Edward de Groot", "email": "edegroot@postmedia.com" }, 
@@ -18,7 +18,6 @@
   "keywords": ["framework", "widgets", "express", "coffeescript", "coffeekup"],
   "repository": "git://github.com/postmedia/timbits",
   "main": "./lib/timbits",
-  "bin": { "timbits": "./bin/timbits" },
   "scripts": {
     "build": "cake build"
   },

src/timbits.coffee

@@ -3,10 +3,10 @@ http = require 'http'
 fs = require 'fs'
 
 # creates, configures, and returns a standard express server instance
-@serve = (engine = 'coffee', port = 5678) ->
+@serve = (@appName = 'Timbits', engine = 'coffee', port = 5678) ->
 	@server = express.createServer()
 
-	# optionally support coffekup
+	# support coffekup
 	@server.register '.coffee', require('coffeekup')
 
 	# configure server (still needs some thought) 	
@@ -24,6 +24,10 @@ fs = require 'fs'
 
 	@server.configure 'production', =>
 		@server.use express.errorHandler()
+
+	# route help page
+	@server.get '/', (req, res) ->
+		res.render 'help'
 
 	#automagically load timbits found in the ./timbits folder	
 	path = "#{process.cwd()}/timbits"