Merge pull request #11730 from knownasilya/patch-5

[DOC release] Bring back docs for component helper, fixes #11720
emberjs · Jul 13, 2015 · a32ee08 · a32ee08
2 parents 3f01294 + 3f85ae4
commit a32ee08
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 6 deletions.
diff --git a/packages/ember-htmlbars/lib/keywords/component.js b/packages/ember-htmlbars/lib/keywords/component.js
@@ -1,5 +1,57 @@
+/**
+  @module ember
+  @submodule ember-templates
+  @public
+*/
 import { assign } from 'ember-metal/merge';
 
+/**
+  The `{{component}}` helper lets you add instances of `Ember.Component` to a
+  template. See [Ember.Component](/api/classes/Ember.Component.html) for
+  additional information on how a `Component` functions.
+  `{{component}}`'s primary use is for cases where you want to dynamically
+  change which type of component is rendered as the state of your application
+  changes. The provided block will be applied as the template for the component.
+  Given an empty `<body>` the following template:
+
+  ```handlebars
+  {{! application.hbs }}
+  {{component infographicComponentName}}
+  ```
+
+  And the following application code:
+
+  ```javascript
+  export default Ember.Controller.extend({
+    infographicComponentName: computed('isMarketOpen', {
+      get() {
+        if (this.get('isMarketOpen')) {
+          return 'live-updating-chart';
+        } else {
+          return 'market-close-summary';
+        }
+      }
+    })
+  });
+  ```
+
+  The `live-updating-chart` component will be appended when `isMarketOpen` is
+  `true`, and the `market-close-summary` component will be appended when
+  `isMarketOpen` is `false`. If the value changes while the app is running,
+  the component will be automatically swapped out accordingly.
+  Note: You should not use this helper when you are consistently rendering the same
+  component. In that case, use standard component syntax, for example:
+
+  ```handlebars
+  {{! application.hbs }}
+  {{live-updating-chart}}
+  ```
+
+  @method component
+  @since 1.11.0
+  @for Ember.Templates.helpers
+  @public
+*/
 export default {
   setupState(lastState, env, scope, params, hash) {
     let componentPath = env.hooks.getValue(params[0]);

diff --git a/packages/ember-htmlbars/lib/main.js b/packages/ember-htmlbars/lib/main.js
@@ -2,9 +2,10 @@
 
   &nbsp;
 
-@module ember
-@submodule ember-templates
-@main ember-templates
+  @module ember
+  @submodule ember-templates
+  @main ember-templates
+  @public
 */
 
 /**
@@ -16,9 +17,10 @@
   helpers, please see the [ember-templates](/api/modules/ember-templates.html)
   package.
 
-@module ember
-@submodule ember-htmlbars
-@main ember-htmlbars
+  @module ember
+  @submodule ember-htmlbars
+  @main ember-htmlbars
+  @public
 */
 import Ember from 'ember-metal/core';
 import isEnabled from 'ember-metal/features';