ngCss :: Angular Binding in CSS (Don't Call It A CSS Preprocessor)

Options

Option values can be passed into ngCss in a number of locations:

<div style="color: color;" ng-css="{ scope: '#myCss', live: true }">...</div>

overrides:

<style type="text/css" id="myCss" ng-css="{ live: false }" />...</style>

<link rel="stylesheet" type="text/css" id="myCss" href="css/site.css" ng-css="{ live: false }" />

overrides:

When placed on the first line within the CSS,
```
/*ngcss({ live: true })*/
```
overrides:
The default values described below (which can be programmatically overridden).

In the example above,

options.live

will be set to

true

within the context of the

DIV

as the

DIV

tag's option values override the

STYLE

LINK

tags' option values.

options.live

will be set to

false

within the context of the

STYLE

LINK

tags' which overrides the CSS's inline option values.

options.live

was set to

true

within the CSS's inline option values which would have overriden the default value (

false

), but it never takes effect due to the

STYLE

LINK

tags' option values.

The use of the CSS's inline option values (#3) allows you to fully configure all aspects of ngCss within the CSS itself.

script

VARIANT (see valid values below) "isolated" The Javascript scope that the CSS embedded

SCRIPT

tags will be

eval

uated within:

```
false
```
- CSS embedded
```
SCRIPT
```
tags are not evaluated.
```
"isolated"
```
- a new
isolated
```
IFRAME
```
Javascript scope
.
```
"sandbox"
```
- a new
```
sandbox
```
ed
```
IFRAME
```
Javascript scope
. †
```
"global"
```
- the global Javascript scope.
```
"local"
```
- a new local (closure) Javascript scope.
```
"useStrict"
```
- a new "use strict" local (closure) Javascript scope.
```
"json"
```
- as JSON-style object definitions (both keys and values are "double quoted"); no Javascript scope applies.
```
"#ID"
```
- the Javascript scope in effect for the referenced HTML Element.id will be used. ‡
```
object
```
- Javascript Objects can be provided in a number of flavors:
- angular.element, jQuery or DOM element - the Javascript scope in effect for the referenced HTML Element will be used. ‡
- ```
{ script: variant
, context: object
 }
```
  -
```
script
```
  * resolves to either
```
"local"
```
  or
```
"useStrict"
```
  and
```
context
```
  is provided as
```
this
```
  within the evaluated Javascript.
- otherwise -
```
object
```
  is provided as
```
this
```
  within a new
```
"local"
```
  (closure) Javascript scope
```
function
```
- a function** that returns a
```
variant
```
representing any of the listed values.

callback

FUNCTION undefined Defines the function** that will be called each time the CSS is updated. You can disable the callback by returning

false

from the function.

scope

VARIANT (see valid values below) "" (e.g. a
null-string
) The Angular

$scope

that will be used by the directive:

```
"parent"
```
- the directive will operate in the context of the original Angular scope.
```
"#ID"
```
- the
```
$scope
```
in effect for the referenced HTML Element.id will be imported.
```
function
```
- a function** that returns a
```
string
```
representing one of the listed values.
otherwise - the directive will operate with its own
isolate
```
$scope
```
.

live

BOOLEAN false Specifies if changes made within the

$scope

are to be automatically reflected within the CSS. When set to

false

, the custom

$broadcast

event updateCss is configured (e.g.

$rootScope.$broadcast('updateCss');

) and can be triggered via the factory's

ngCss.updateCss()

or via

$rootScope.$broadcast('updateCss');

async

BOOLEAN true Specifies if

LINK

tags are to be processed asynchronously. If ordering matters in the execution of the embedded

SCRIPT

s, then this should be set to

false

† - There is no reason to use

sandbox

over

isolated

if your CSS embedded

SCRIPT

tags are from a trusted source, especially considering the limitations of postMessage.
‡ - Allows for the sharing of functionality and variables across invocations.
* -

object
.script

must create a new Javascript scope; it cannot link to an existing scope.
** -

function

s are passed 2 arguments:

```
domElement
```
- the directive's DOM element.
```
metadata
```
- an object representing the internal metadata pertaining to the element.

Each

ng-css

attributed

LINK

tag is replaced with a

STYLE

tag with only the

ng-css

attribute copied across. If you require additional attributes or processing to apply to these created

STYLE

tags, you can make any necessary modifications to the DOM element within a

function

Options settings can reference properties in the context of the original Angular scope, but not within the Angular scope created/imported via

options.scope

style

Attributes

Variable

s can be used within any tag's

style

attribute (but

SCRIPT

tags are not permitted). When applying ngCss to a

style

attribute, you have two options when setting the value of

ng-css

's in-line options:

<div ng-css-style="color: color;" style="font-style: italic;" ng-css="#myCss">...</div>

This will import the Angular

$scope

and option values from the referenced HTML Element with the ID myCss (e.g. "#myCss" overrides

options.scope

). This element should be a

ng-css

attributed

LINK

STYLE

tag, but any Angular element's

$scope

can be imported.

<div ng-css-style="color: color;" style="font-style: italic;" ng-css="{ scope: '#myCss', live: true }">...</div>

This will also import the Angular

$scope

/option values from ID myCss while overriding the value of

options.live

true

. This is useful when you want to use a

Variable

within your

style

attribute but do not require it to be live-bound like its source (as used in 2 of the 3 color profile selection boxes above to demonstrate the concept).

Only the

style

attribute is effected by ngCss in this context using a non-isolate

$scope

(even when the referenced element is!). This is accomplished by a bit of pre- and post-

$compile

slight-of-hand between the directive's

template

and

link

functions and custom linking code via a

$watch

(

live: true

) or

$on

(

live: false

Due to IE's behavior of removing invalid CSS settings from

STYLE

attributes at parse (which in turn, removes them from the DOM) it is necessary to specify ngCss styles in a

ng-css-style

(or HTML5-compliant

data-ng-css-style

) attribute. The

ng-css-style

(or HTML5-compliant

data-ng-css-style

) attribute is concatnated with the additionally-defined

STYLE

attribute if it is present.

How To Override The Default Option Values

If you wish to override any of the default option values you can call

ngCss.defaults

, passing in the new default option values like so:

                var myAngularApp = angular.module("myAngularApp", ["ngCss"]);
                
                myAngularApp.controller("ExampleController", ["$scope", "ngCss", function ($scope, ngCss) {
                    ngCss.defaults({ script: 'global' });
                }]);

In the example above, we reset the default value for

options.script

within ngCss to

global

Getting Started

Assuming the default option values are in effect as described above:

Download ngCss From GitHub

Include the ngCss

SCRIPT

tag in the

HEAD

of your HTML document below your Angular

SCRIPT

tag:

                        <script type="text/javascript" src="angular.min.js"></script>
                        <script type="text/javascript" src="angular.ngcss.min.js"></script>

Include the attribute

ng-app="myAngularApp"

in your HTML element (e.g.

<html ng-app="myAngularApp">

) and setup

myAngularApp

to include the ngCss factory like so:

                        <script>
                            var myAngularApp = angular.module("myAngularApp", ["ngCss"]);
                        </script>

Add the

ng-css

attribute to the LINK and/or STYLE elements we want to process:

                        <style id="myCss" type="text/css" ng-css>...</style>
                        
                        <link id="myExCss" rel="stylesheet" type="text/css" href="css/site.css" ng-css/>

Define the

options

used by ngCss (if any):

                        <style id="myCss" type="text/css" ng-css="{ script: 'local', live: true }">...</style>
                        
                        <link id="myExCss" rel="stylesheet" type="text/css" href="css/site.css"
                            ng-css="{ script: 'local', live: true }"
                        />

Edit the CSS within the LINK and/or STYLE elements to use ngCss like this:

                        /*
                        <script>
                            $scope.color = 'blue';
                        </script>
                        */
                        DIV {
                            color: /*color*/;
                        }

(Optional) Consume ngCss (or any other

$scope

's)

Variable

s within any element's

style

attribute like this:

                        <span style="color: color;" ng-css="#myCss">...</span>
                    
                        <a href="http://opensourcetaekwondo.com/ngcss" style="color: color;"
                            ng-css="{ scope: '#myExCss', live: false }"
                        >...</span>

Technically, you can import any Angular element's

$scope

into the

style

attribute, but the intention is for you to reference

ng-css

attributed

LINK

STYLE

elements.

NOTE: You are also permitted to use the attribute name

data-ng-css

in place of

ng-css

if you want to be HTML5 compliant.

HTML Tag		Live Example Source Code ❮ Choose Your Options
Script (Javascript Scoping)
Scope (Angular Scoping)
Live
Async
Callback	Reports $scope.$id 's

Selector	Property	Value
DIV.gotchas	background-color
BODY	color
BODY	font-family
[Pretty Font]	font-family
[Main Color]	background-color

Gotchas

It is recommended to comment the
```
Variable
```
s (e.g.
```
/*Variable*/
```
) as the braces used by Angular are also used within CSS and these additional non-CSS-valid braces can cause issues with CSS editors. But... this will require you to modify your ngCss-enabled *.css files before CSS minimization as the commented
```
Variable
```
s will likely be removed during minimization.
Any instances of
```
{{
```
followed by
```
}}
```
within your CSS will be eaten by
```
$interpolate
```
or will otherwise cause errors. Make sure you have whitespace between all braces that are not Variables.
As
```
LINK
```
tag CSS files are read via AJAX, the limitations of
```
XMLHttpRequest
```
can restrict where you serve your CSS files from. If your CSS files exist on the same server, this is a non-issue.
Each
```
LINK
```
tag is replaced by a new
```
STYLE
```
tag that contains the modified CSS file contents. This process can break some relative URLs within your CSS files (e.g.
```
background-image: url("../img/a.png");
```
). It is therefore recommended that you use absolute URLs within your CSS files (e.g.
```
background-image: url("/img/a.png");
```
) in order to avoid any such errors.

Embedded

SCRIPT

s are all evaluated in series at initialization prior to CSS modification, so the following will not work as expected:

                        /*<script>
                            $scope.color = 'blue';
                        </script>*/
                        DIV {
                            color: /*color*/; //# expecting 'blue' but gets 'green'
                        }
                        
                        /*<script>
                            $scope.color = 'green';
                        </script>*/
                        SPAN {
                            color: /*color*/; //# expecting 'green'
                        }

At initialization

$scope.color

will be set to "blue" then "green" prior to any CSS modification, so the

color

of both DIV and SPAN will be set to "green".

IE8+ is supported by ngCss out-of-the-box.
The required "advanced" JavaScript functionality is:
- XMLHttpRequest
- getElementsByTagName and createElement

Side Effects

Each
```
LINK
```
tag is replaced by a new
```
STYLE
```
tag that contains the modified CSS file contents. This is done so that the original unprocessed CSS referenced by the
```
LINK
```
tag does not apply to the webpage.
Any ngCss attributed tags without a defined HTML Element.id has a unique ID (formatted as ngCss###) added so ngCss can track it internally.
If you have elected to have a
script
value other than
sandbox
, ngCss-embedded Javascript has the ability to modify the global scope.
And of course... the CSS within ngCss attributed tags is modified based on the embedded Variables and related
Angular
```
$scope
```
.

ngCss

Overview

Options

script

callback

scope

live

async

style
Attributes

How To Override The Default Option Values

Getting Started

Examples

Complex Example

Gotchas

Side Effects

What is up with the 3-headed knight?