Yii 1.1: haml-and-sass

Haml and Sass
24 followers

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

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.

Total 10 comments

#15785 report it
Artem Frolov at 2013/12/17 02:23am
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

#9445 report it
nomar at 2012/08/11 08:11am
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.

#5973 report it
paddy at 2011/12/01 05:11pm
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 :(

#2586 report it
payne at 2011/01/19 11:13pm
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.

#2581 report it
Yeti at 2011/01/19 05:13am
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.

#2580 report it
payne at 2011/01/19 04:29am
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?

#2491 report it
ajsharma at 2011/01/10 02:40am
Doc fix

Small doc fix, but the Sass config:

'class' => 'PBMAssetManager',

should be:

'class' => 'ext.phamlp.PBMAssetManager',
#241 report it
Yeti at 2010/07/29 05:08am
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.

#242 report it
jackiesun at 2010/07/28 11:49pm
Charm But Slow

hello, if use haml , the website become slow.

#520 report it
imehesz at 2010/05/05 10:18pm
Charm

hello,

thanks for this extension - HAML part works like a charm :) (haven't tried SASS yet)

--iM

Leave a comment

Please to leave your comment.

Create extension
  • Yii Version: 1.1
  • License: New BSD License
  • Developed by: Yeti
  • Category: Others
  • Votes: +22 / -2
  • Downloaded: 1,920 times
  • Created on: Mar 21, 2010
  • Last updated: Sep 21, 2010