Clone this wiki locally

If you’ve got a question, please don’t add it here, please join the Google Group and have a discussion with the community developers and users!

Why do you use <ol> and <li> tags?

I want more markup in my forms — I want wrappers, containers, classes and ids on everything. I want standardised, flexible markup that can be used to achieve all kinds of visual treatments and solve all kinds of design problems. Minimalist markup (the bare essentials required to achieve the visual effect) may be preferred by some, but not by me, and I’m (mostly) building this for me.

One of the things I want in my markup is a wrapper around the elements that make up one of the inputs on the page (the label, the input, the hints, the inline error messages, etc). I used to use divs to achieve this, other well respected people have recommended the use paragraphs, spans, definition lists and much more for the same goal.

After seeing Aaron’s Learning to Love Forms presentation at Web Directions, ordered lists started to grow on me. I know a bunch of people are using ordered lists for all kinds of content that really isn’t a list so that it can be “semantically rich”, but compared to a div or a paragraph or a table or a definition list, an ordered list seemed like a great candidate.

After hearing what a screen reader actually sounded like when it announced “a form with a list of five items”, ordered lists really made sense to me. A div, a paragraph and a list item are all just block elements that can be styled to look identical in visual browsers, but the accessibility pay-offs of choosing something that can assist non-visual browsers are huge.

Thinking about it a bit later on, I was completing a paper-based form that said things like “if you answered no, proceed to question 11”, which seals the deal for me — a list of questions to be completed in a form is a valid way to approach the markup of a form.

We don’t all have to agree, but that’s why Formtastic uses ordered lists, and that’s how it’s going to be for the 1.0 release (soon, soon).

However…

This has been the hottest topic and absolutely the most frequently asked question since I published the code. Inexperienced HTML/CSS authors freak out when they have to override the browser’s default presentation of a list, and experienced authors freak out because they have a different opinion on what tags and markup should be used.

Both of these have been huge barriers to entry. There are forks where people have moved the ol and li tags into preferences that can be changed by the author. There are forks where people have changed the markup to suit their needs (you can too). But the most impressive fork I’ve seen so far will be the inspiration for Formtastic 2.0.

We’re going to try to move the markup logic out of Ruby, shifting it into partials which can use regular HTML and ERB to define what sort of markup is used for any given input. The best bit is that we’ll be able to have default partials in the Formtastic plugin folder, and anyone will be able to override some of all of those partials in their app/views/ directory to suit their own needs, thanks to the way Rails handles plugins and view load paths with “engines”.

I haven’t really decided if I’ll stick with the ordered lists or go for something more generic with a lower barrier to entry (like divs), but it’ll take just a few minutes to shape the markup around your needs either way, and I imagine we’ll be able to figure out themes and all sorts of stuff like that down the road.

Sometimes I get an orphaned <li>, what’s up with that?

All <%= f.input(...) %> calls need to be inside an <% f.inputs do %>...<% end %> block, which sets up a <fieldset> and <ol> wrapping around the inputs it contains.

What about custom inputs?

This will be part of 2.0 when we (hopefully) move to partials-based input markup. In the meantime, you can fork the code and add in whatever you want!

What about Javascript?

There’s plenty of element, class and id hooks in the markup (and you can add more) for you to write your own event-driven Javascript, but there’ll be nothing in 1.0, mainly because I want to actually ship a polished 1.0, and partly because there’s a bunch of decisions to be made about Javascript libraries, etc.

What about pretty buttons?

Working on it.

The supplied stylesheet is all wonky in my browser, what’s up with that?

Right now, that stylesheet uses on a common “clearfix” float clearing method that relies on an XHTMLHTML document layout (specifically, it relies on an xmlns attribute on the HTML tag). So, if the default stylesheet looks hideous, the first thing to try would be a well-formed XHTML document template that includes the xmlns attribute.

If you don’t want to use an XHTML doctype, you’ll have to try one of the many other clearing techniques which I’m sure Google can help you find, then edit or add to the CSS.

Since Rails 3 (and everyone else) is moving away from XHTML towards HTML5 (or even HTML4), Formtastic will move this way soon too.

How do I fix “Undefined Method `semantic_form_for’”?

In the event you get an “Undefined Method semantic_form_for” error, there’s usually four reasons for this happening:

1. You haven’t specified the gem in your environment.rb (config.gem 'formtastic', :source => 'http://gemcutter.org')
2. You haven’t restarted your server after adding the gem to your environment (or after installing as a plugin)
3. You’ve specified the order your plugins should load in environment.rb with config.plugins, but haven’t included Formtastic in the list
4. Your version of Formtastic may be incompatible with your version of Rails. Try upgrading to the latest Formtastic and restarting your server to see if that fixes it.

What’s up with the justinfrench-formtastic gem?

That’s from back when GitHub was building gems. Ignore it, you want the plain old formtastic gem.

Why aren’t my Date and Time inputs working with Mongoid?

Mondoid 2.0 supports multiparameter attributes like dates, but the support has to be enabled on a per-model basis. Example:

class YourModel
include Mongoid::Document
include Mongoid::MultiParameterAttributes
..
end

Older versions of Mongoid doesn’t handle multiparameter attributes. But there is an easy fix. All you have to do is include the little code snippet in this gist in your ApplicationController and everything will work. See this thread for more information.

Why isn’t my join-table working with nested attributes?

Formtastic automatically tries to use an id tag with nested forms. So if you created your join tables using :without => :id and have other attributes on this join table you’d like access to then you’ll need to add an id to the join table. You’ll likely get an error saying something like undefined method to_sym nil:NilClass when trying to update_attributes. So you need to create a migration that does: