/scalate-jruby/src/main/resources/haml-3.0.25/doc-src/FAQ.md

  1# Frequently Asked Questions
  2
  3* Table of contents
  4{:toc}
  5
  6## Haml
  7
  8### Why is my markup indented properly in development mode, but not in production?
  9{#q-indentation-in-production}
 10
 11To improve performance, Haml defaults to {file:HAML_REFERENCE.md#ugly-option "ugly" mode} in Rails
 12apps running in production.
 13
 14
 15### How do I put a punctuation mark after an element, like "`I like <strong>cake</strong>!`"?
 16{#q-punctuation}
 17
 18Expressing the structure of a document
 19and expressing inline formatting are two very different problems.
 20Haml is mostly designed for structure,
 21so the best way to deal with formatting is to leave it to other languages
 22that are designed for it.
 23You could use Textile:
 24
 25    %p
 26      :textile
 27        I like *cake*!
 28
 29or Markdown:
 30
 31    %p
 32      :markdown
 33        I like **cake**!
 34
 35or plain old XHTML:
 36
 37    %p I like <strong>cake</strong>!
 38
 39If you're inserting something that's generated by a helper, like a link,
 40then it's even easier:
 41
 42    %p== I like #{link_to 'chocolate', 'http://franschocolates.com'}!
 43
 44### How do I stop Haml from indenting the contents of my `pre` and `textarea` tags?
 45{#q-preserve}
 46
 47Because Haml automatically indents the HTML source code,
 48the contents of whitespace-sensitive tags like `pre` and `textarea`
 49can get screwed up.
 50The solution is to replace the newlines inside these tags
 51with HTML newline entities (`&#x000A;`),
 52which Haml does using the {Haml::Helpers#preserve} and {Haml::Helpers#find_and_preserve} helpers.
 53
 54Normally, Haml will do this for you automatically
 55when you're using a tag that needs it
 56(this can be customized using the {file:HAML_REFERENCE.md#preserve-option `:preserve`} option.
 57For example,
 58
 59    %p
 60      %textarea= "Foo\nBar"
 61
 62will be compiled to
 63
 64    <p>
 65      <textarea>Foo&#x000A;Bar</textarea>
 66    </p>
 67
 68However, if a helper is generating the tag,
 69Haml can't detect that and so you'll have to call {Haml::Helpers#find_and_preserve} yourself.
 70You can also use `~`, which is the same as `=`
 71except that it automatically runs `find_and_preserve` on its input.
 72For example:
 73
 74    %p= find_and_preserve "<textarea>Foo\nBar</textarea>"
 75
 76is the same as
 77
 78    %p~ "<textarea>Foo\nBar</textarea>"
 79
 80and renders
 81
 82    <p><textarea>Foo&#x000A;Bar</textarea></p>
 83
 84### How do I make my long lines of Ruby code look nicer in my Haml document?
 85{#q-multiline}
 86
 87Put them in a helper or your model.
 88
 89Haml purposefully makes it annoying to put lots of Ruby code into your templates,
 90because lots of code doesn't belong in the view.
 91If you take that huge `link_to_remote` call
 92and move it to a `update_sidebar_link` helper,
 93it'll make your view both easier to read and more semantic.
 94
 95If you absolutely must put lots of code in your template,
 96Haml offers a somewhat awkward multiline-continuation tool.
 97Put a `|` (pipe character) at the end of each line you want to be merged into one
 98(including the last line!).
 99For example:
100
101    %p= @this.is(way.too.much). |
102        code("and I should").   |
103        really_move.it.into(    |
104          :a => @helper)        |
105
106Note that sometimes it is valid to include lots of Ruby in a template
107when that Ruby is a helper call that passes in a lot of template information.
108Thus when a function has lots of arguments,
109it's possible to wrap it across multiple lines
110as long as each line ends in a comma.
111For example:
112
113    = link_to_remote "Add to cart",
114        :url => { :action => "add", :id => product.id },
115        :update => { :success => "cart", :failure => "error" }
116
117### `form_for` is printing the form tag twice!
118
119Make sure you're calling it with `-`, not `=`.
120Just like in ERB, you have to do
121
122    <% form_for stuff do %>
123      ...
124    <% end %>
125
126in Haml, you have to do
127
128    - form_for stuff do
129      ...
130
131### I have Haml installed. Why is Rails (only looking for `.html.erb` files | rendering Haml files as plain text | rendering Haml files as blank pages)?
132{#q-blank-page}
133
134There are several reasons these things might be happening.
135First of all, make sure that Haml really is installed;
136either you've loaded the gem (via `config.gem` in Rails 2.3 or in the Gemfile in Rails 3),
137or `vendor/plugins/haml` exists and contains files.
138Then try restarting Mongrel or WEBrick or whatever you might be using.
139
140Finally, if none of these work,
141chances are you've got some localization plugin like Globalize installed.
142Such plugins often don't play nicely with Haml.
143Luckily, there's usually an easy fix.
144For Globalize, just edit `globalize/lib/globalize/rails/action_view.rb`
145and change
146
147    @@re_extension = /\.(rjs|rhtml|rxml)$/
148
149to
150
151    @@re_extension = /\.(rjs|rhtml|rxml|erb|builder|haml)$/
152
153For other plugins, a little searching will probably turn up a way to fix them as well.
154
155## Sass
156
157### Can I use a variable from my controller in my Sass file?
158{#q-ruby-code}
159
160No. Sass files aren't views.
161They're compiled once into static CSS files,
162then left along until they're changed and need to be compiled again.
163Not only don't you want to be running a full request cycle
164every time someone requests a stylesheet,
165but it's not a great idea to put much logic in there anyway
166due to how browsers handle them.
167
168If you really need some sort of dynamic CSS,
169you can define your own {Sass::Script::Functions Sass functions} using Ruby
170that can access the database or other configuration.
171*Be aware when doing this that Sass files are by default only compiled once
172and then served statically.*
173
174If you really, really need to compile Sass on each request,
175first make sure you have adequate caching set up.
176Then you can use {Sass::Engine} to render the code,
177using the {file:SASS_REFERENCE.md#custom-option `:custom` option}
178to pass in data that {Sass::Script::Functions::EvaluationContext#options can be accessed}
179from your Sass functions.
180
181## You still haven't answered my question!
182
183Sorry! Try looking at the [Haml](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html)
184or [Sass](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html) references,
185If you can't find an answer there,
186feel free to ask in `#haml` on irc.freenode.net
187or send an email to the [mailing list](http://groups.google.com/group/haml?hl=en).