Gem: haml
This commit is contained in:
248
vendor/gems/haml-1.7.2/README
vendored
Normal file
248
vendor/gems/haml-1.7.2/README
vendored
Normal file
@@ -0,0 +1,248 @@
|
||||
= Haml and Sass
|
||||
|
||||
Haml and Sass are templating engines
|
||||
for the two most common types of documents on the web:
|
||||
HTML and CSS, respectively.
|
||||
They are designed to make it both easier and more pleasant
|
||||
to code HTML and CSS documents,
|
||||
by eliminating redundancy,
|
||||
reflecting the underlying structure that the document represents,
|
||||
and providing elegant, easily understandable, and powerful syntax.
|
||||
|
||||
== Using
|
||||
|
||||
There are several ways to use Haml and Sass.
|
||||
They can be used as a plugins for Rails or Merb,
|
||||
or embedded on their own in other applications.
|
||||
The first step of all of these is to install the Haml gem:
|
||||
|
||||
gem install haml
|
||||
|
||||
To install Haml and Sass as a Rails plugin,
|
||||
just run <tt>haml --rails path/to/rails/app</tt>
|
||||
and both Haml and Sass will be installed.
|
||||
Views with the <tt>.haml</tt> (or <tt>.html.haml</tt> for edge)
|
||||
extension will automatically use Haml.
|
||||
Sass is a little more complicated;
|
||||
<tt>.sass</tt> files should be placed in public/stylesheets/sass,
|
||||
where they'll be automatically compiled
|
||||
to corresponding CSS files in public/stylesheets when needed
|
||||
(the Sass template directory is customizable...
|
||||
see the Sass module docs for details).
|
||||
|
||||
For Merb, <tt>.html.haml</tt> views will work without any further modification.
|
||||
To enable Sass, you also need to add it add a dependency.
|
||||
To do so, just add
|
||||
|
||||
dependency "haml"
|
||||
|
||||
to config/dependencies.rb.
|
||||
Then it'll work just like it does in Rails.
|
||||
|
||||
To use Haml and Sass programatically,
|
||||
check out the RDocs for the Haml and Sass modules.
|
||||
|
||||
== Formatting
|
||||
|
||||
=== Haml
|
||||
|
||||
The most basic element of Haml
|
||||
is a shorthand for creating HTML tags:
|
||||
|
||||
%tagname{ :attr1 => 'value1', :attr2 => 'value2' } Contents
|
||||
|
||||
No end-tag is needed; Haml handles that automatically.
|
||||
Adding <tt>class</tt> and <tt>id</tt> attributes is even easier.
|
||||
Haml uses the same syntax as the CSS that styles the document:
|
||||
|
||||
%tagname#id.class
|
||||
|
||||
In fact, when you're using the <tt><div></tt> tag,
|
||||
it becomes <em>even easier</em>.
|
||||
Because <tt><div></tt> is such a common element,
|
||||
a tag without a name defaults to a div. So
|
||||
|
||||
#foo Hello!
|
||||
|
||||
becomes
|
||||
|
||||
<div id='foo'>Hello!</div>
|
||||
|
||||
Haml uses indentation
|
||||
to bring the individual elements to represent the HTML structure.
|
||||
A tag's children are indented two spaces more than the parent tag.
|
||||
Again, a closing tag is automatically added.
|
||||
For example:
|
||||
|
||||
%ul
|
||||
%li Salt
|
||||
%li Pepper
|
||||
|
||||
becomes:
|
||||
|
||||
<ul>
|
||||
<li>Salt</li>
|
||||
<li>Pepper</li>
|
||||
</ul>
|
||||
|
||||
You can also put plain text as a child of an element:
|
||||
|
||||
%p
|
||||
Hello,
|
||||
World!
|
||||
|
||||
It's even possible to embed Ruby code into Haml documents.
|
||||
An equals sign, <tt>=</tt>, will output the result of the code.
|
||||
A hyphen, <tt>-</tt>, will run the code but not output the result.
|
||||
You can even use control statements
|
||||
like <tt>if</tt> and <tt>while</tt>:
|
||||
|
||||
%p
|
||||
Date/Time:
|
||||
- now = DateTime.now
|
||||
%strong= now
|
||||
- if now > DateTime.parse("December 31, 2006")
|
||||
= "Happy new " + "year!"
|
||||
|
||||
Haml provides far more tools than those presented here.
|
||||
Check out the reference documentation in the Haml module.
|
||||
|
||||
=== Sass
|
||||
|
||||
At its most basic,
|
||||
Sass is just another way of writing CSS.
|
||||
Although it's very much like normal CSS,
|
||||
the basic syntax offers a few helpful features:
|
||||
tabulation (using *two spaces*)
|
||||
indicates the attributes in a rule,
|
||||
rather than non-DRY brackets;
|
||||
and newlines indicate the end of an attribute,
|
||||
rather than a semicolon.
|
||||
For example:
|
||||
|
||||
#main
|
||||
:background-color #f00
|
||||
:width 98%
|
||||
|
||||
becomes:
|
||||
|
||||
#main {
|
||||
background-color: #f00;
|
||||
width: 98% }
|
||||
|
||||
However, Sass provides much more than a way to make CSS look nice.
|
||||
In CSS, it's important to have accurate selectors,
|
||||
so your styles don't just apply to everything.
|
||||
However, in order to do this,
|
||||
you need to use nested element selectors.
|
||||
These get very ugly very quickly.
|
||||
I'm sure everyone's had to write something like
|
||||
"#main .sidebar .top p h1 a",
|
||||
followed by
|
||||
"#main .sidebar .top p h1 a:visited" and
|
||||
"#main .sidebar .top p h1 a:hover".
|
||||
Well, Sass gets rid of that.
|
||||
Like Haml, it uses indentation to indicate the structure of the document.
|
||||
So, what was:
|
||||
|
||||
#main {
|
||||
width: 90%;
|
||||
}
|
||||
#main p {
|
||||
border-style: solid;
|
||||
border-width: 1px;
|
||||
border-color: #00f;
|
||||
}
|
||||
#main p a {
|
||||
text-decoration: none;
|
||||
font-weight: bold;
|
||||
}
|
||||
#main p a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
becomes:
|
||||
|
||||
#main
|
||||
:width 90%
|
||||
p
|
||||
:border-style solid
|
||||
:border-width 1px
|
||||
:border-color #00f
|
||||
a
|
||||
:text-decoration none
|
||||
:font-weight bold
|
||||
a:hover
|
||||
:text-decoration underline
|
||||
|
||||
Pretty nice, no? Well, it gets better.
|
||||
One of the main complaints against CSS is that it doesn't allow constants.
|
||||
What if have a color or a width you re-use all the time?
|
||||
In CSS, you just have to re-type it each time,
|
||||
which is a nightmare when you decide to change it later.
|
||||
Not so for Sass!
|
||||
You can use the "!" character to set constants.
|
||||
Then, if you put "=" after your attribute name,
|
||||
you can set it to a constant.
|
||||
For example:
|
||||
|
||||
!note_bg= #55aaff
|
||||
|
||||
#main
|
||||
:width 70%
|
||||
.note
|
||||
:background-color= !note_bg
|
||||
p
|
||||
:width 5em
|
||||
:background-color= !note_bg
|
||||
|
||||
becomes:
|
||||
|
||||
#main {
|
||||
width: 70%; }
|
||||
#main .note {
|
||||
background-color: #55aaff; }
|
||||
#main p {
|
||||
width: 5em;
|
||||
background-color: #55aaff; }
|
||||
|
||||
You can even do simple arithmetic operations with constants,
|
||||
adding numbers and even colors together:
|
||||
|
||||
!main_bg= #46ar12
|
||||
!main_width= 40em
|
||||
|
||||
#main
|
||||
:background-color= !main_bg
|
||||
:width= !main_width
|
||||
.sidebar
|
||||
:background-color= !main_bg + #333333
|
||||
:width= !main_width - 25em
|
||||
|
||||
becomes:
|
||||
|
||||
#main {
|
||||
background-color: #46a312;
|
||||
width: 40em; }
|
||||
#main .sidebar {
|
||||
background-color: #79d645;
|
||||
width: 15em; }
|
||||
|
||||
A comprehensive list of features is in
|
||||
the documentation for the Sass module.
|
||||
|
||||
== Authors
|
||||
|
||||
Haml and Sass are designed by Hampton Catlin (hcatlin).
|
||||
Help with the Ruby On Rails implementation and much of the documentation
|
||||
by Jeff Hardy (packagethief).
|
||||
|
||||
Nathan Weizenbaum (Nex3) contributed the buffered-engine code to Haml,
|
||||
along with many other enhancements
|
||||
(including the silent-line syntax: "-").
|
||||
He continues to actively work on both Haml and Sass.
|
||||
|
||||
If you use this software, you must pay Hampton a compliment.
|
||||
Say something nice about it.
|
||||
Beyond that, the implementation is licensed under the MIT License.
|
||||
Ok, fine, I guess that means compliments aren't *required*.
|
||||
Reference in New Issue
Block a user