Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge pull request #1497 from trek/document-bindAttr-mixed-with-exist…

…ing-attributes

additional documentation for bindAttr specifically related to `class`
  • Loading branch information...
commit e781c9e2001a8a70ff0127c46faebaddcca04cf9 2 parents 0ac8748 + 8b2eafb
Tom Dale tomdale authored
Showing with 100 additions and 0 deletions.
  1. +100 −0 packages/ember-handlebars/lib/helpers/binding.js
100 packages/ember-handlebars/lib/helpers/binding.js
View
@@ -296,10 +296,110 @@ EmberHandlebars.registerHelper('unless', function(context, options) {
`bindAttr` allows you to create a binding between DOM element attributes and
Ember objects. For example:
+
``` handlebars
<img {{bindAttr src="imageUrl" alt="imageTitle"}}>
```
+ The above handlebars template will fill the `<img>`'s `src` attribute
+ will the value of the property referenced with `"imageUrl"` and its
+ `alt` attribute with the value of the property referenced with `"imageTitle"`.
+
+ If the rendering context of this template is the following object:
+
+ ``` javascript
+ {
+ imageUrl: 'http://lolcats.info/haz-a-funny',
+ imageTitle: 'A humorous image of a cat'
+ }
+ ```
+
+ The resulting HTML output will be:
+
+ ``` html
+ <img src="http://lolcats.info/haz-a-funny" alt="A humorous image of a cat">
+ ```
+
+ `bindAttr` cannot redeclare existing DOM element attributes. The use
+ of `src` in the following `bindAttr` example will be ignored and the hard coded value
+ of `src="/failwhale.gif"` will take precedence:
+
+ ``` handlebars
+ <img src="/failwhale.gif" {{bindAttr src="imageUrl" alt="imageTitle"}}>
+ ```
+
+ ### `bindAttr` and the `class` attribute
+ `bindAttr` supports a special syntax for handling a number of cases unique
+ to the `class` DOM element attribute. The `class` attribute combines
+ multiple discreet values into a single attribute as a space-delimited
+ list of strings. Each string can be
+
+ * a string return value of an object's property.
+ * a boolean return value of an object's property
+ * a hard-coded value
+
+ A string return value works identically to other uses of `bindAttr`. The return
+ value of the property will become the value of the attribute. For example,
+ the following view and template:
+
+ ``` javascript
+ AView = Ember.View.extend({
+ someProperty: function(){
+ return "aValue";
+ }.property()
+ })
+ ```
+
+ ``` handlebars
+ <img {{bindAttr class="view.someProperty}}>
+ ```
+
+ Result in the following rendered output:
+ <img class="aValue">
+
+ A boolean return value will insert a specified class name if the property
+ returns `true` and remove the class name if the property returns `false`.
+
+ A class name is provided via the syntax `somePropertyName:class-name-if-true`.
+
+ ``` javascript
+ AView = Ember.View.extend({
+ someBool: true
+ })
+ ```
+
+ ``` handlebars
+ <img {{bindAttr class="view.someBool:class-name-if-true"}}>
+ ```
+
+ Result in the following rendered output:
+ <img class="class-name-if-true">
+
+ An additional section of the binding can be provided if you want to
+ replace the existing class instead of removing it when the boolean
+ value changes:
+
+ ``` handlebars
+ <img {{bindAttr class="view.someBool:class-name-if-true:class-name-if-false"}}>
+ ```
+
+ A hard-coded value can be used by prepending `:` to the desired
+ class name: `:class-name-to-always-apply`.
+
+ ``` handlebars
+ <img {{bindAttr class=":class-name-to-always-apply"}}>
+ ```
+
+ Results in the following rendered output:
+ <img class=":class-name-to-always-apply">
+
+ All three strategies - string return value, boolean return value, and
+ hard-coded value – can be combined in a single declaration:
+
+ ```handlebars
+ <img {{bindAttr class=":class-name-to-always-apply view.someBool:class-name-if-true view.someProperty"}}>
+ ```
+
@method bindAttr
@for Ember.Handlebars.helpers
@param {Hash} options
Please sign in to comment.
Something went wrong with that request. Please try again.