Skip to content
Browse files

change window name, readme

  • Loading branch information...
1 parent cf8d667 commit 8e7d7fddb7b6f36b866000b95d040cf0b3ac872c @thegorgon committed Nov 20, 2011
Showing with 50 additions and 1 deletion.
  1. +49 −0 README.md
  2. +1 −1 lib/hamlbars/template.rb
View
49 README.md
@@ -0,0 +1,49 @@
+Hamlbars
+========
+
+Hamlbars is a gem for using HAML with Handlebars JavaScript templates.
+
+Usage
+------
+
+Define files with the `.hamlbars` extension. Write your Handlebar JS templates using HAML in these files. Hamlbars will compile them into HTML and register the compiled templates into a `TEMPLATES` JavaScript object for use client side.
+
+Let's use an example. Imagine I'm working on a rich internet application that has a homepage, about page, contact page and allows for viewing and creation of accounts. I might have the following directory structure (assuming Rails 3.1 asset pipeline):
+
+ app
+ -> assets
+ -> app
+ -> models
+ -> controllers
+ -> views
+ -> home
+ -> index
+ -> about
+ -> contact
+ -> accounts
+ -> new
+ -> edit
+ -> show
+
+In my JavaScript controllers, I'm going to need to reference my views. I want to use Handlebars (because it's awesome) client side, but I also want to use HAML (because it is similarly awesome) server side. I also want to take advantage of any helpers I define and any Rails helpers, because they make my code easier to read.
+
+Hamlbars was designed for you to do exactly this. Fill your view files with HAML, just like any normal server side view and use the extension `.hamlbars`. Then, in your JavaScript, access the compiled templates with : `window.TEMPLATES[sprockets logical path]`. For example, to access the "about" page view in the above example you would use :
+
+ window.TEMPLATES["app/views/home/about"]
+
+Caveat
+-------
+
+Many helpers require a request object to work properly. Although these all ActionView helpers are included in the scope of the HAML renderer, certain helpers will not work without access to this request object. As Sprockets does not have access to this, and most production templates will be compiled outside of a request cycle, there is no reasonable way to make all these helpers work universally. They are included so that the individual programmer can take steps to make these helpers work on a case by case basis as needed.
+
+I have taken efforts to enable usage of rails routing helpers, however. If you define `Rails.application.config.default_url_options`, these options will be extended to the HAML scope context, allowing for usage of all `{path}_url` methods.
+
+For example, I have the following in my `development.rb` file :
+
+ config.action_controller.default_url_options = {:host => "www.rails.loc:3000"}
+
+Questions? Comments?
+--------------------
+
+Find me, Jesse Reiss, at [the gorgon lab](http://www.thegorgonlab.com)
+
View
2 lib/hamlbars/template.rb
@@ -14,7 +14,7 @@ def self.default_mime_type
end
def self.default_namespace
- 'this.JST'
+ 'this.TEMPLATES'
end
def self.engine_initialized?

0 comments on commit 8e7d7fd

Please sign in to comment.
Something went wrong with that request. Please try again.