Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

textilized the README so that it looks pretty pretty on GitHub

  • Loading branch information...
commit 09d957d090ce4ad2f451dbfd08ab50d0afa5fb32 1 parent 0c03ff9
Justin French authored
Showing with 72 additions and 65 deletions.
  1. +72 −65 README → README.textile
View
137 README → README.textile
@@ -1,51 +1,54 @@
-=Formtastic Sneaky Preview
+h1. Formtastic Sneaky Preview
Formtastic is a Rails FormBuilder DSL (with some other goodies) to make it far easier to create beautiful, semantically rich, syntactically awesome, readily stylable and wonderfully accessible HTML forms in your Rails applications.
-==The Story
+h2. The Story
Hacked together forms were easy, but awesome forms with decent semantics, rich mark-up and plenty of CSS hooks were incredibly painful. I was discouraged from doing things properly because it was do much mark-up and code to write. One day, I finally had enough, so I opened up my text editor, and wrote a DSL for how I'd like to author forms:
- <% semantic_form_for @article do |form| %>
-
- <%= form.error_messages %>
-
- <% form.input_field_set "Basic" do %>
- <%= form.input :title %>
- <%= form.input :body, :rows => 20 %>
- <%= form.input :section_id, :include_blank => true %>
- <%= form.input :publication_state_id, :as => :radio %>
- <%= form.input :author_id, :as => :select %>
- <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
- <% end %>
-
- <% form.input_field_set "Extra" do %>
- <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
- <%= form.input :extract, :required => false, :rows => 5 %>
- <%= form.input :description, :required => false, :rows => 5 %>
- <%= form.input :url_title, :required => false %>
- <% end %>
-
- <% form.button_field_set do %>
- <%= form.cancel_button -%>
- <%= form.commit_button -%>
- <% end %>
-
+<pre>
+<% semantic_form_for @article do |form| %>
+
+ <%= form.error_messages %>
+
+ <% form.input_field_set "Basic" do %>
+ <%= form.input :title %>
+ <%= form.input :body, :rows => 20 %>
+ <%= form.input :section_id, :include_blank => true %>
+ <%= form.input :publication_state_id, :as => :radio %>
+ <%= form.input :author_id, :as => :select %>
+ <%= form.input :allow_comments, :label => "Allow commenting on this article" %>
+ <% end %>
+
+ <% form.input_field_set "Extra" do %>
+ <%= form.input :keywords, :required => false, :hint => "Example: ruby, rails, forms" %>
+ <%= form.input :extract, :required => false, :rows => 5 %>
+ <%= form.input :description, :required => false, :rows => 5 %>
+ <%= form.input :url_title, :required => false %>
+ <% end %>
+
+ <% form.button_field_set do %>
+ <%= form.cancel_button %>
+ <%= form.commit_button %>
<% end %>
+<% end %>
+</pre>
+
I also wrote the accompanying HTML output I expected, favoring something very similar to the fieldsets, lists and other semantic elements Aaron Gustafson presented in <i>Learning to Love Forms</i> <http://www.slideshare.net/AaronGustafson/learning-to-love-forms-web-directions-south-07>, and then hacked together enough Ruby to prove it could be done.
-==Configuration
+h2. Configuration
If you wish, put something like this in config/initializers/formtastic_config.rb:
- JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
- JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
- JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
+<pre>
+JustinFrench::Formtastic::SemanticFormBuilder.all_fields_required_by_default = false
+JustinFrench::Formtastic::SemanticFormBuilder.required_string = "(required)"
+JustinFrench::Formtastic::SemanticFormBuilder.optional_string = "(optional)"
+</pre>
-
-==Guiding Principals
+h2. Guiding Principals
* great forms are at the heart of most web applications
* semantically rich (and far more accessible) HTML forms really are possible with the use of appropriate elements like fieldsets & lists
@@ -59,9 +62,9 @@ If you wish, put something like this in config/initializers/formtastic_config.rb
-==Status
+h2. Status
-THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.
+*THIS IS DEFINITELY NOT PRODUCTION-READY. THINGS ARE GOING TO CHANGE A LOT.*
It's incredibly opinionated, incomplete, a work in progress, messy around the edges, messy in the middle too, tightly coupled to the database, tightly coupled to "my way" of doing things and also incredibly lacking in unit tests so far, but I hope you try it and offer some suggestions and improvements any way.
@@ -69,7 +72,7 @@ It's incredibly opinionated, incomplete, a work in progress, messy around the ed
* Github: http://github.com/justinfrench/formtastic/
-==Roadmap
+h2. Roadmap
* There's plenty of TODOs in the code
* get the basic form_for implementation complete, proven and *well tested* (did I mention how laborious testing form builders is?)
@@ -78,39 +81,42 @@ It's incredibly opinionated, incomplete, a work in progress, messy around the ed
* probably do a shortcut like <%= form.inputs :name, :login, :email, :bio %> for those that want the form with zero configuration
-==Usage
+h2. Usage
The smallest example:
- <% semantic_form_for @user do |form| %>
- <% form.input_field_set do %>
- <%= form.input :name %>
- <%= form.input :email %>
- <% end %>
+<pre>
+<% semantic_form_for @user do |form| %>
+ <% form.input_field_set do %>
+ <%= form.input :name %>
+ <%= form.input :email %>
<% end %>
+<% end %>
+</pre>
With an output something like:
- <form id="new-article-form" action="#" method="post">
- <fieldset>
- <legend><span>Create a new User</span></legend>
- <fieldset class="inputs">
- <ol>
- <li id="user_name_input" class="required string">
- <label for="user_name">Name <abbr title="required">*</abbr></label>
- <input type="text" id="user_name" name="user[name]" size="50" />
- </li>
- <li id="user_email_input" class="required string">
- <label for="user_email">Email <abbr title="required">*</abbr></label>
- <input type="text" id="user_email" name="user[email]" size="50" />
- </li>
- </ol>
- </fieldset>
+<pre>
+<form id="new-article-form" action="#" method="post">
+ <fieldset>
+ <legend><span>Create a new User</span></legend>
+ <fieldset class="inputs">
+ <ol>
+ <li id="user_name_input" class="required string">
+ <label for="user_name">Name <abbr title="required">*</abbr></label>
+ <input type="text" id="user_name" name="user[name]" size="50" />
+ </li>
+ <li id="user_email_input" class="required string">
+ <label for="user_email">Email <abbr title="required">*</abbr></label>
+ <input type="text" id="user_email" name="user[email]" size="50" />
+ </li>
+ </ol>
</fieldset>
- </form>
-
+ </fieldset>
+</form>
+</pre>
-==What about Stylesheets?
+h2. What about Stylesheets?
The plan is that a CSS file similar to this will be generated or otherwise made available to your app to give you basic vertical (labels above inputs) and horizontal (labels to the left of inputs), and then if needed, you would write new styles on top to customise the presentation to suit you.
@@ -121,16 +127,17 @@ You can use a proof-of-concept file however:
2. Add both YUI's reset.css and formtastic.css to your layout:
-<%= stylesheet_link_tag "http://yui.yahooapis.com/2.5.1/build/reset/reset-min.css" -%>
-<%= stylesheet_link_tag "formtastic" -%>
-
+<pre>
+<%= stylesheet_link_tag "http://yui.yahooapis.com/2.5.1/build/reset/reset-min.css" %>
+<%= stylesheet_link_tag "formtastic" %>
+</pre>
-==Compatibility
+h2. Compatibility
I'm only testing Formtastic with the latest Rails stable release.
-==But it doesn't do that thing I really need!
+h2. But it doesn't do that thing I really need!
Oh noes! It might not ever do it either. We'll see. This is not a silver bullet. I want to make the usual stuff easy, and the unusual stuff possible. That might mean that some of the inputs on your form still have to be hard-coded, but some is better than all, right?
Please sign in to comment.
Something went wrong with that request. Please try again.