haml-and-sass

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 ¶

• Home page
• See a site using the extension
• Join discussion
• Report a bug

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.