Copyright (c) 2004-2006 Fabien Potencier
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
sfHamlView plugin
Overview
This plugin gives you the ability to use the Haml template engine (originally in Ruby)
with your symfony project. http://haml.hamptoncatlin.com/docs/haml
Installation
To install sfHamlView:
$ php symfony plugin-install http://plugins.symfony-project.com/sfHamlViewPlugin
Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory.
Or you can use the SVN repository http://svn.symfony-project.com/plugins/sfHamlViewPlugin
branches/1.0 is to be used with symfony 1.0.x
trunk/ will be for symfony 1.1.x
Clear the cache to enable the autoloading to find the new classes:
$ php symfony cc
Usage
There has been for quite some time now Haml for Ruby (ROR) and I was impressed by the fact that it can solve my problems of badly formated and erroneous HTML code and also I could not get the designers write XHTML code and make easy to maintain.
I know about the project http://phphaml.sf.net but when I took a look at the source code I was not impressed by the quality and also it did not fit well with making it symfony template view. In the beginning I tried to fix it but when into a big vicious circle and decided to port Haml by myself.
So the Haml parser used in sfHamlViewPlugin is not a project by itself (although it is simple one class file) but rather available only in this plugin. I plan to make its own project and just include it with sfHamlView.
Now about the usage :) The official Haml documentation is at http://haml.hamptoncatlin.com/docs/haml
I will only point here what are the differences/limitations of the PHP port of the parser.
To install the plugin, create a file called "module.yml" in your application's config directory and enter
all:
view_class: sfHaml
From then on all template files ending with .haml will be processed with sfHamlView.
sfHamlView is compatible with the sfPHPView which means that if there is not templateSuccess.haml file, it will default to tempalteSuccess.php and render it as usual. This means that you can mix template types and also you can convert your current *.php templates to Haml one by one.
There are two configuration options which can be set from app.yml (these are the defaults):
all:
sfHamlView:
template_extension: ".haml"
doctype: "XHTML 1.0 Strict"
If you want to change the default doctype you must set the same one in both app.yml and your layout.haml file. This is because symfony processes the template files before the layout file and we cannot determine the template doctype from the setting in layout.haml
Additional note:
If you use this Plugin under Windows, make sure to convert the line delimiters of your template-file into Unix-style (Linefeed = LF, ASCII-sign 10). Windows' default line delimiters are CR+LF by default - took me hours to get behind this...
Differences
- All Ruby specific features are not available for obvious reasons.
- The "[]" (square brackets syntax) is not implemented yet.
- Filters are not implemented yet.
- The "==" syntax is not implemented as it makes sense only in Ruby
Limitations
- When you define tag attributes you MUST use single quotes. For example:
%div{:id => 'collection'}
%div{:class => 'item'}
%div{:class => 'description'} What a cool item!
and not
%div{:id => "collection"}
%div{:class => "item"}
%div{:class => "description"} What a cool item!
- There is no support from XML doctype (!!! XML)
- When you use blocks like if, foreach, for, etc, you need to close the block explicitly. For example:
* if ($foo)
%div.bar Hello Here
* else
%div.baz Hello There
* endif
Example Usage
!!!
%html
%head
= include_http_metas()
= include_metas()
= include_title()
%link{:rel => 'shortcut icon', :href => '/favicon.ico'}
* if (@$autodiscovery)
= auto_discovery_link_tag('rss', $autodiscovery[array("type" => 'application/atom+xml', 'title' => $autodiscovery["title"]("link"],))
* endif
/
[lt IE 7](if)>
<link rel="stylesheet" type="text/css" href="/css/ie6fix.css" />
<![endif]
%javascript
function antispam(ext,domain,name) {
document.write('<a href=\"mailto:' + name + '@' + domain + '.' + ext + '\">');
document.write(name + '@' + domain + '.' + ext + '</a>');
}
%body
#doc.yui-t7
#hd{:style => 'background: url(/pics/top-orange-band.gif) left top #EE9933; width: 780px'}
#header{:style => 'width: 780px;'}
#branding
= link_to(image_tag("/pics/logo.gif"), "/")
* if (@$trivia)
%br
%br
%span
%font{:size => 3} Did you know...
%br
%font{:size => 2}
= $trivia->getContent()
* endif
#bd
.yui-g{:style => 'background: #E9B26E; width: 780px'}
= include_partial('global/main_navigation')
.yui-g{:style => 'background: #fff'}
= $sf_data->getRaw('sf_content')
%br
%br
#ft
= include_partial('global/main_footer')
License
For the full copyright and license information, please view the LICENSE
file that was distributed with this source code.
Kiril Angov 
