Haml and Sass have been used in Ruby for sometime to simplify templates (Haml) and make CSS more intelligent, flexible and manageable (Sass). This extension brings Haml and Sass to Yii.
It's kind of two extensions in one as you can use Haml and Sass independently of each other.
Included is PHamlP, a port of Haml and Sass to PHP. This is Haml/Sass V3.x compliant.
Haml ¶
Haml is based on one primary principle. Markup should be beautiful.
Haml is a markup language that’s used to cleanly and simply describe the XHTML of any web document, without the use of inline code. It avoids the need for explicitly coding XHTML into the template, because it is actually an abstract description of the XHTML, with some code to generate dynamic content.
PHamlP comes with a rich set of filters that allow inclusion of javaScript, CSS, Sass, PHP, parsing with Markdown, and more.
PHamlP also provides some [helper methods][http://code.google.com/p/phamlp/wiki/HelperMethods] that can be used from your template, and you can extend the class and define your own.
PHamlP supports for, if, elseif, else, foreach, do, and while blocks.
Read the Haml tutorial then try it for yourself; you probably won't want to go back;
See http://haml-lang.com for details on Haml.
Sass ¶
Sass is a meta-language on top of CSS that’s used to describe the style of a document cleanly and structurally, with more power than flat CSS allows.
It features include nested rules, variables, mixins, and more to make CSS powerful, manageable and DRY.
The extension supports SASS and SCSS syntaxes.
The extension includes Compass.
See http://sass-lang.com/ for details on Sass.
See http://compass-style.orgm/ for details on Compass.
NOTE: Sass is primarily a development tool and is not intended for production use. You should link to the compiled stylesheets in production for performance.
Resources ¶
Documentation ¶
Requirements ¶
- Yii 1.0 or above
Installation ¶
- Extract the release file under
protected/extensions
Usage ¶
The PHamlP Wiki has detailed description of options for Haml and Sass.
Haml ¶
Declare PHamlP's Haml as your the viewRender component in your configuration. ~~~ 'viewRenderer'=>array( 'class'=>'ext.phamlp.Haml', // delete options below in production 'ugly' => false, 'style' => 'nested', 'debug' => 0, 'cache' => false, ), ~~~ In the demo folder there are Haml templates for a new Yii project. Copy them into the appropriate locations in the views directory.
As of R0014 and greater the extension supports the use of both Haml and PHP view files and layouts in the same application.
Yii 1.1.2 and 1.0.13 support this feature natively.
For use with earlier versions of Yii the extension contains the AppController file in the Yii directory. This has a new resolveViewFile() method that must override CCcontroller::resolveViewFile(). This is done either by extending your application's controllers from AppController (Yii must be able to find it, so either move it from the extension into application.components or edit your configuration file to import it), or copy AppCcontroller::resolveViewFile() method into your application's own base controller.
Note: Prior to R0014 all views must be Haml
Sass ¶
In order to make the handling of Sass files as transparent as possible the extension has an enhanced asset manager. This must be declared as the assetManager component in your configuration file. ~~~ 'assetManager' => array( 'class' => 'PBMAssetManager', 'parsers' => array(
'sass' => array( // key == the type of file to parse
'class' => 'ext.phamlp.Sass', // path alias to the parser
'output' => 'css', // the file type it is parsed to
'options' => array(<Parser specific options>)
),
) ), ~~~
Publishing a Sass file is the same as publishing any other asset, i.e.: ~~~ $publishedAsset = Yii::app()->getAssetMananger()->publish(Yii::getPathOfAlias('allias.to.asset.directory'). DIRECTORY_SEPARATOR . 'asset.sass'); ~~~
Change Log ¶
21 Sep 2010 ¶
- V3.2
- Added Compass as a Sass extension
- Fixed SassScript parsing errors in SCSS
- HamlHelpers now accept arrays as arguments
01 Sep 2010 ¶
- V3.1
- Added support for SassNumbers with complex units
- @import directive can import multiple files
- @import now looks for files with the current syntax, then the other syntax, if the extension is not given. e.g. @import foo; in a .scss file will look for foo.scss first, then foo.sass; in a .sass file it will look for foo.sass first, then foo.scss
29 Aug 2010 ¶
- V3.0 Haml/Sass V3.x implementation Please read the forum post for details.
21 May 2010 ¶
- R0022 Upgraded to PHamlP_2.2_r0094.
Haml ¶
- Added helper methods
- Support for HTML 5 Custom Data Attributes
- Support for class and id arrays
3 May 2010 ¶
- R0021 Upgraded to PHamlP_2.2_r0076.
Haml ¶
- Support for attributes on more than one line
- Support for multi-line content
Sass ¶
- Fixed incorrect line number for indentation error reporting
- Fixed some undefined indices
Both ¶
- Files with no indentation supported
15 April 2010 ¶
- R0019 Upgraded to PHamlP_2.2_r0060.
Fixes issues 9 - 12
- Output file extension set using the 'viewFileExtension' property (set in the configuration). Default = '.php'
- Location of output file controlled by 'useRuntimePath' property (also set in the configuration; defined in CViewRenderer). True to output to protected.runtime.views.nnnnnnnn; false to output to source directory. Default is true.
- Haml parser now recognises // as the start of a Haml comment - it behaves the same as -#
- Haml parser now supports single line filters, e.g. :php $x=1; will parse to <?php $x=1; ?>
- Haml parser now honours empty attributes; it previously removed them
14 April 2010 ¶
- R0018 R0017 used an old version of the Haml view renderer - R0018 uses the correct version.
14 April 2010 ¶
- R0017 Upgraded to PHamlP_2.2_r0051. Fixes issues 3 - 7
04 April 2010 ¶
- R0016 Upgraded to PHamlP_2.2_r0049 - improved Haml filter handling.
- Added Markdown and Textile (requires Textile to be installed) filters for Yii.
If you are using the Markdown filter you must now provide the path alias in your configuration to the directory containing the Yii specific version. The Yii specific version is included in the extension.
'viewRenderer'=>array(
'class'=>'ext.haml.Haml',
'filterPathAlias'=>'ext.haml.filters'
},
02 April 2010 ¶
- R0015 Documentation change to note that AppController is not needed with Yii >= 1.1.2 and >= 1.0.13.
31 March 2010 ¶
- R0014 Change to support fallback to PHP view files if Haml file not present.
29 March 2010 ¶
- R0013 New version of PHamlP that fixes rendering of MSIE conditional comments.
21 March 2010 ¶
- R0012 Initial release.
Re Charm But Slow
Do make sure you have caching enabled.
If caching is turned off the Haml source is parsed every time, which can be slow.
With caching turned on the Haml source is only parsed on the first page access or if the source changes; after that the resulting PHP file is used so there is no performance impact from Haml.
Charm But Slow
hello,
if use haml , the website become slow.
Charm
hello,
thanks for this extension - HAML part works like a charm :) (haven't tried SASS yet)
--iM
Doc fix
Small doc fix, but the Sass config:
'class' => 'PBMAssetManager',should be:
'class' => 'ext.phamlp.PBMAssetManager',Any more tips on Sass?
Specifically, how to publish? I put a main.sass in the /css directory, but it is not automatically published to asset directory? Do I need to run something each time I want to update the assets?
Re: Any more tips on Sass?
Your Sass files shouldn't be in the /css directory as they are not files that need to be or should be publicly accessible.
I like the SCSS syntax, so the following uses that; swap sccs for sass if you use the SASS syntax.
My structure is to have a /protected/assets/scss directory. Under that I have my main.scss files then other Sass files and directories to be imported.
To compile your Sass files then publish the resulting Css file you need use the extension's asset manager (Yii's asset manager won't deal with anything other than Css and Js) by declaring it your config with something like:
~~~
'assetManager' => array(
'class' => 'ext.phamlp.PBMAssetManager',
'parsers' => array(
'scss' => array( 'class' => 'ext.phamlp.Sass', 'output' => 'css', 'options' => array( 'style' => 'nested', 'cache' => false, 'extensions' => array( 'compass' => array( 'project_path' => realpath(dirname(__FILE__).DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.'..'), 'relative_assets' => false, ) ) ) ),)
),
~~~
Then in your layout you put something like:
~~~
Yii::app()->getClientScript()->registerCssFile(Yii::app()->getAssetMamanger()->publish(Yii::getPathOfAlias('application.assets.scss') . DIRECTORY_SEPARATOR . 'main.scss'));
~~~
Please note that Sass is a development tool. It is not intended for use in production. In production put an ordinary link to the complied Css files.
Thanks!
Works beautifully. I think I'll write an environment-aware helper to make specifying these stylesheets easier. But the sass extension is working great.
Multiple lines of PHP
The HAML reference (http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html) shows that "A line of Ruby code can be stretched over multiple lines as long as each line but the last ends with a comma".
I've been struggling to get this to work with PHP - it doesn't seem to want to run. Any thoughts as to why this is? I can't find any PHP or Yii specific examples :(
Is this extension still maintained?
I get errors because of typos and wrong configuration examples.
Plus the extension is based on an old version of Yii and does not run out of the box anymore.
Please update your Yii installation and fix the bugs or state somewhere that this extension is not longer maintained.
Sorry, would really be cool to see this extension working.
Another Sass and Compass extension
Here is another extension which allows you to use Sass and Compass:
Sass (SCSS) and Compass support for the Yii framework
If you have any questions, please ask in the forum instead.
Signup or Login in order to comment.