[DOC release] Bring back docs for several helpers

(cherry picked from commit 99aaa34)
emberjs · Aug 13, 2015 · bcef793 · bcef793
1 parent 1939d01
commit bcef793
Show file tree

Hide file tree

Showing 6 changed files with 543 additions and 4 deletions.
diff --git a/packages/ember-htmlbars/lib/keywords/collection.js b/packages/ember-htmlbars/lib/keywords/collection.js
@@ -1,13 +1,137 @@
 /**
 @module ember
-@submodule ember-htmlbars
+@submodule ember-templates
 */
 
 import { readViewFactory } from 'ember-views/streams/utils';
 import CollectionView from 'ember-views/views/collection_view';
 import ViewNodeManager from 'ember-htmlbars/node-managers/view-node-manager';
 import { assign } from 'ember-metal/merge';
 
+/**
+  `{{collection}}` is a template helper for adding instances of
+  `Ember.CollectionView` to a template. See [Ember.CollectionView](/api/classes/Ember.CollectionView.html)
+   for additional information on how a `CollectionView` functions.
+
+  `{{collection}}`'s primary use is as a block helper with a `contentBinding`
+  option pointing towards an `Ember.Array`-compatible object. An `Ember.View`
+  instance will be created for each item in its `content` property. Each view
+  will have its own `content` property set to the appropriate item in the
+  collection.
+
+  The provided block will be applied as the template for each item's view.
+
+  Given an empty `<body>` the following template:
+
+  ```handlebars
+  {{! application.hbs }}
+  {{#collection content=model}}
+    Hi {{view.content.name}}
+  {{/collection}}
+  ```
+
+  And the following application code
+
+  ```javascript
+  App = Ember.Application.create();
+  App.ApplicationRoute = Ember.Route.extend({
+    model: function() {
+      return [{name: 'Yehuda'},{name: 'Tom'},{name: 'Peter'}];
+    }
+  });
+  ```
+
+  The following HTML will result:
+
+  ```html
+  <div class="ember-view">
+    <div class="ember-view">Hi Yehuda</div>
+    <div class="ember-view">Hi Tom</div>
+    <div class="ember-view">Hi Peter</div>
+  </div>
+  ```
+
+  ### Non-block version of collection
+
+  If you provide an `itemViewClass` option that has its own `template` you may
+  omit the block.
+
+  The following template:
+
+  ```handlebars
+  {{! application.hbs }}
+  {{collection content=model itemViewClass="an-item"}}
+  ```
+
+  And application code
+
+  ```javascript
+  App = Ember.Application.create();
+  App.ApplicationRoute = Ember.Route.extend({
+    model: function() {
+      return [{name: 'Yehuda'},{name: 'Tom'},{name: 'Peter'}];
+    }
+  });
+
+  App.AnItemView = Ember.View.extend({
+    template: Ember.Handlebars.compile("Greetings {{view.content.name}}")
+  });
+  ```
+
+  Will result in the HTML structure below
+
+  ```html
+  <div class="ember-view">
+    <div class="ember-view">Greetings Yehuda</div>
+    <div class="ember-view">Greetings Tom</div>
+    <div class="ember-view">Greetings Peter</div>
+  </div>
+  ```
+
+  ### Specifying a CollectionView subclass
+
+  By default the `{{collection}}` helper will create an instance of
+  `Ember.CollectionView`. You can supply a `Ember.CollectionView` subclass to
+  the helper by passing it as the first argument:
+
+  ```handlebars
+  {{#collection "my-custom-collection" content=model}}
+    Hi {{view.content.name}}
+  {{/collection}}
+  ```
+
+  This example would look for the class `App.MyCustomCollection`.
+
+  ### Forwarded `item.*`-named Options
+
+  As with the `{{view}}`, helper options passed to the `{{collection}}` will be
+  set on the resulting `Ember.CollectionView` as properties. Additionally,
+  options prefixed with `item` will be applied to the views rendered for each
+  item (note the camelcasing):
+
+  ```handlebars
+  {{#collection content=model
+                itemTagName="p"
+                itemClassNames="greeting"}}
+    Howdy {{view.content.name}}
+  {{/collection}}
+  ```
+
+  Will result in the following HTML structure:
+
+  ```html
+  <div class="ember-view">
+    <p class="ember-view greeting">Howdy Yehuda</p>
+    <p class="ember-view greeting">Howdy Tom</p>
+    <p class="ember-view greeting">Howdy Peter</p>
+  </div>
+  ```
+
+  @method collection
+  @for Ember.Templates.helpers
+  @deprecated Use `{{each}}` helper instead.
+  @public
+*/
 export default {
   setupState(state, env, scope, params, hash) {
     var read = env.hooks.getValue;

diff --git a/packages/ember-htmlbars/lib/keywords/partial.js b/packages/ember-htmlbars/lib/keywords/partial.js
@@ -1,11 +1,52 @@
 /**
 @module ember
-@submodule ember-htmlbars
+@submodule ember-templates
 */
 
 import lookupPartial from 'ember-views/system/lookup_partial';
 import { internal } from 'htmlbars-runtime';
 
+/**
+  The `partial` helper renders another template without
+  changing the template context:
+
+  ```handlebars
+  {{foo}}
+  {{partial "nav"}}
+  ```
+
+  The above example template will render a template named
+  "_nav", which has the same context as the parent template
+  it's rendered into, so if the "_nav" template also referenced
+  `{{foo}}`, it would print the same thing as the `{{foo}}`
+  in the above example.
+
+  If a "_nav" template isn't found, the `partial` helper will
+  fall back to a template named "nav".
+
+  ### Bound template names
+
+  The parameter supplied to `partial` can also be a path
+  to a property containing a template name, e.g.:
+
+  ```handlebars
+  {{partial someTemplateName}}
+  ```
+
+  The above example will look up the value of `someTemplateName`
+  on the template context (e.g. a controller) and use that
+  value as the name of the template to render. If the resolved
+  value is falsy, nothing will be rendered. If `someTemplateName`
+  changes, the partial will be re-rendered using the new template
+  name.
+
+
+  @method partial
+  @for Ember.Templates.helpers
+  @param {String} partialName the name of the template to render minus the leading underscore
+  @public
+*/
+
 export default {
   setupState(state, env, scope, params, hash) {
     return { partialName: env.hooks.getValue(params[0]) };

diff --git a/packages/ember-htmlbars/lib/keywords/readonly.js b/packages/ember-htmlbars/lib/keywords/readonly.js
@@ -1,3 +1,8 @@
+/**
+@module ember
+@submodule ember-templates
+*/
+
 import { MUTABLE_REFERENCE } from 'ember-htmlbars/keywords/mut';
 
 export default function readonly(morph, env, scope, originalParams, hash, template, inverse) {

diff --git a/packages/ember-htmlbars/lib/keywords/textarea.js b/packages/ember-htmlbars/lib/keywords/textarea.js
@@ -1,8 +1,194 @@
 /**
 @module ember
-@submodule ember-htmlbars
+@submodule ember-templates
 */
 
+/**
+  `{{textarea}}` inserts a new instance of `<textarea>` tag into the template.
+  The attributes of `{{textarea}}` match those of the native HTML tags as
+  closely as possible.
+
+  The following HTML attributes can be set:
+
+    * `value`
+    * `name`
+    * `rows`
+    * `cols`
+    * `placeholder`
+    * `disabled`
+    * `maxlength`
+    * `tabindex`
+    * `selectionEnd`
+    * `selectionStart`
+    * `selectionDirection`
+    * `wrap`
+    * `readonly`
+    * `autofocus`
+    * `form`
+    * `spellcheck`
+    * `required`
+
+  When set to a quoted string, these value will be directly applied to the HTML
+  element. When left unquoted, these values will be bound to a property on the
+  template's current rendering context (most typically a controller instance).
+
+  Unbound:
+
+  ```handlebars
+  {{textarea value="Lots of static text that ISN'T bound"}}
+  ```
+
+  Would result in the following HTML:
+
+  ```html
+  <textarea class="ember-text-area">
+    Lots of static text that ISN'T bound
+  </textarea>
+  ```
+
+  Bound:
+
+  In the following example, the `writtenWords` property on `App.ApplicationController`
+  will be updated live as the user types 'Lots of text that IS bound' into
+  the text area of their browser's window.
+
+  ```javascript
+  App.ApplicationController = Ember.Controller.extend({
+    writtenWords: "Lots of text that IS bound"
+  });
+  ```
+
+  ```handlebars
+  {{textarea value=writtenWords}}
+  ```
+
+   Would result in the following HTML:
+
+  ```html
+  <textarea class="ember-text-area">
+    Lots of text that IS bound
+  </textarea>
+  ```
+
+  If you wanted a one way binding between the text area and a div tag
+  somewhere else on your screen, you could use `Ember.computed.oneWay`:
+
+  ```javascript
+  App.ApplicationController = Ember.Controller.extend({
+    writtenWords: "Lots of text that IS bound",
+    outputWrittenWords: Ember.computed.oneWay("writtenWords")
+  });
+  ```
+
+  ```handlebars
+  {{textarea value=writtenWords}}
+
+  <div>
+    {{outputWrittenWords}}
+  </div>
+  ```
+
+  Would result in the following HTML:
+
+  ```html
+  <textarea class="ember-text-area">
+    Lots of text that IS bound
+  </textarea>
+
+  <-- the following div will be updated in real time as you type -->
+
+  <div>
+    Lots of text that IS bound
+  </div>
+  ```
+
+  Finally, this example really shows the power and ease of Ember when two
+  properties are bound to eachother via `Ember.computed.alias`. Type into
+  either text area box and they'll both stay in sync. Note that
+  `Ember.computed.alias` costs more in terms of performance, so only use it when
+  your really binding in both directions:
+
+  ```javascript
+  App.ApplicationController = Ember.Controller.extend({
+    writtenWords: "Lots of text that IS bound",
+    twoWayWrittenWords: Ember.computed.alias("writtenWords")
+  });
+  ```
+
+  ```handlebars
+  {{textarea value=writtenWords}}
+  {{textarea value=twoWayWrittenWords}}
+  ```
+
+  ```html
+  <textarea id="ember1" class="ember-text-area">
+    Lots of text that IS bound
+  </textarea>
+
+  <-- both updated in real time -->
+
+  <textarea id="ember2" class="ember-text-area">
+    Lots of text that IS bound
+  </textarea>
+  ```
+
+  ### Actions
+
+  The helper can send multiple actions based on user events.
+
+  The action property defines the action which is send when
+  the user presses the return key.
+
+  ```handlebars
+  {{input action="submit"}}
+  ```
+
+  The helper allows some user events to send actions.
+
+* `enter`
+* `insert-newline`
+* `escape-press`
+* `focus-in`
+* `focus-out`
+* `key-press`
+
+  For example, if you desire an action to be sent when the input is blurred,
+  you only need to setup the action name to the event name property.
+
+  ```handlebars
+  {{textarea focus-in="alertMessage"}}
+  ```
+
+  See more about [Text Support Actions](/api/classes/Ember.TextArea.html)
+
+  ### Extension
+
+  Internally, `{{textarea}}` creates an instance of `Ember.TextArea`, passing
+  arguments from the helper to `Ember.TextArea`'s `create` method. You can
+  extend the capabilities of text areas in your application by reopening this
+  class. For example, if you are building a Bootstrap project where `data-*`
+  attributes are used, you can globally add support for a `data-*` attribute
+  on all `{{textarea}}`s' in your app by reopening `Ember.TextArea` or
+  `Ember.TextSupport` and adding it to the `attributeBindings` concatenated
+  property:
+
+  ```javascript
+  Ember.TextArea.reopen({
+    attributeBindings: ['data-error']
+  });
+  ```
+
+  Keep in mind when writing `Ember.TextArea` subclasses that `Ember.TextArea`
+  itself extends `Ember.Component`. Expect isolated component semantics, not
+  legacy 1.x view semantics (like `controller` being present).
+
+  See more about [Ember components](/api/classes/Ember.Component.html)
+
+  @method textarea
+  @for Ember.Templates.helpers
+  @param {Hash} options
+  @public
+*/
 export default function textarea(morph, env, scope, originalParams, hash, template, inverse, visitor) {
   env.hooks.component(morph, env, scope, '-text-area', originalParams, hash, { default: template, inverse }, visitor);
   return true;