Podcast/lib/angular/docs/partials/api/ng.directive:ngPluralize.html

<a href="http://github.com/angular/angular.js/tree/v1.2.0rc1/src/ng/directive/ngPluralize.js#L3" class="view-source btn btn-action"><i class="icon-zoom-in"> </i> View source</a><a href="http://github.com/angular/angular.js/edit/master/src/ng/directive/ngPluralize.js" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable="">ngPluralize</code>
<div><span class="hint">directive in module <code ng:non-bindable="">ng</code>
</span>
</div>
</h1>
<div><h2 id="Description">Description</h2>
<div class="description"><div class="ng-directive-page ng-directive-ngpluralize-page"><h3>Overview</h1>
<p><code>ngPluralize</code> is a directive that displays messages according to en-US localization rules.
These rules are bundled with angular.js, but can be overridden
(see <a href="guide/i18n">Angular i18n</a> dev guide). You configure ngPluralize directive
by specifying the mappings between
<a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html">plural categories</a> and the strings to be displayed.</p>
<h1>Plural categories and explicit number rules</h1>
<p>There are two
<a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html">plural categories</a> in Angular&#39;s default en-US locale: &quot;one&quot; and &quot;other&quot;.</p>
<p>While a plural category may match many numbers (for example, in en-US locale, &quot;other&quot; can match
any number that is not 1), an explicit number rule can only match one number. For example, the
explicit number rule for &quot;3&quot; matches the number 3. There are examples of plural categories
and explicit number rules throughout the rest of this documentation.</p>
<h1>Configuring ngPluralize</h1>
<p>You configure ngPluralize by providing 2 attributes: <code>count</code> and <code>when</code>.
You can also provide an optional attribute, <code>offset</code>.</p>
<p>The value of the <code>count</code> attribute can be either a string or an <a href="guide/expression">Angular expression</a>; these are evaluated on the current scope for its bound value.</p>
<p>The <code>when</code> attribute specifies the mappings between plural categories and the actual
string to be displayed. The value of the attribute should be a JSON object.</p>
<p>The following example shows how to configure ngPluralize:</p>
<pre class="prettyprint linenums">
&lt;ng-pluralize count="personCount"
                 when="{'0': 'Nobody is viewing.',
                     'one': '1 person is viewing.',
                     'other': '{} people are viewing.'}"&gt;
&lt;/ng-pluralize&gt;
</pre>
<p>In the example, <code>&quot;0: Nobody is viewing.&quot;</code> is an explicit number rule. If you did not
specify this rule, 0 would be matched to the &quot;other&quot; category and &quot;0 people are viewing&quot;
would be shown instead of &quot;Nobody is viewing&quot;. You can specify an explicit number rule for
other numbers, for example 12, so that instead of showing &quot;12 people are viewing&quot;, you can
show &quot;a dozen people are viewing&quot;.</p>
<p>You can use a set of closed braces(<code>{}</code>) as a placeholder for the number that you want substituted
into pluralized strings. In the previous example, Angular will replace <code>{}</code> with
<span ng-non-bindable><code>{{personCount}}</code></span>. The closed braces <code>{}</code> is a placeholder
for <span ng-non-bindable>{{numberExpression}}</span>.</p>
<h1>Configuring ngPluralize with offset</h3>
<p>The <code>offset</code> attribute allows further customization of pluralized text, which can result in
a better user experience. For example, instead of the message &quot;4 people are viewing this document&quot;,
you might display &quot;John, Kate and 2 others are viewing this document&quot;.
The offset attribute allows you to offset a number by any desired value.
Let&#39;s take a look at an example:</p>
<pre class="prettyprint linenums">
&lt;ng-pluralize count="personCount" offset=2
              when="{'0': 'Nobody is viewing.',
                     '1': '{{person1}} is viewing.',
                     '2': '{{person1}} and {{person2}} are viewing.',
                     'one': '{{person1}}, {{person2}} and one other person are viewing.',
                     'other': '{{person1}}, {{person2}} and {} other people are viewing.'}"&gt;
&lt;/ng-pluralize&gt;
</pre>
<p>Notice that we are still using two plural categories(one, other), but we added
three explicit number rules 0, 1 and 2.
When one person, perhaps John, views the document, &quot;John is viewing&quot; will be shown.
When three people view the document, no explicit number rule is found, so
an offset of 2 is taken off 3, and Angular uses 1 to decide the plural category.
In this case, plural category &#39;one&#39; is matched and &quot;John, Marry and one other person are viewing&quot;
is shown.</p>
<p>Note that when you specify offsets, you must provide explicit number rules for
numbers from 0 up to and including the offset. If you use an offset of 3, for example,
you must provide explicit number rules for 0, 1, 2 and 3. You must also provide plural strings for
plural categories &quot;one&quot; and &quot;other&quot;.</p>
</div></div>
<h2 id="Usage">Usage</h2>
<div class="usage"><p>This directive can be used as custom element, but be aware of <a href="guide/ie">IE restrictions</a>.</p>as element:<pre class="prettyprint linenums">&lt;ng-pluralize
       count="{string|expression}"
       when="{string}"
       [offset="{number}"]&gt;
&lt;/ng-pluralize&gt;</pre>
as attribute<pre class="prettyprint linenums">&lt;ANY ng-pluralize
     count="{string|expression}"
     when="{string}"
     [offset="{number}"]&gt;
   ...
&lt;/ANY&gt;</pre>
<h4 id="parameters">Parameters</h4><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>count</td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-expression">expression</a></td><td><div class="ng-directive-page ng-directive-ngpluralize-page"><p>The variable to be bounded to.</p>
</div></td></tr><tr><td>when</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-directive-page ng-directive-ngpluralize-page"><p>The mapping between plural category to its corresponding strings.</p>
</div></td></tr><tr><td>offset <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-number">number</a></td><td><div class="ng-directive-page ng-directive-ngpluralize-page"><p>Offset to deduct from the total number.</p>
</div></td></tr></tbody></table></div>
<h2 id="Example">Example</h2>
<div class="example"><div class="ng-directive-page ng-directive-ngpluralize-page"><h4>Source</h2>
<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-86" source-edit-css="" source-edit-js="script.js-85" source-edit-json="" source-edit-unit="" source-edit-scenario="scenario.js-87"></div>
<div class="tabbable"><div class="tab-pane" title="index.html">
<pre class="prettyprint linenums" ng-set-text="index.html-86" ng-html-wrap=" angular.js script.js"></pre>
<script type="text/ng-template" id="index.html-86">
  
  <div ng-controller="Ctrl">
    Person 1:<input type="text" ng-model="person1" value="Igor" /><br/>
    Person 2:<input type="text" ng-model="person2" value="Misko" /><br/>
    Number of People:<input type="text" ng-model="personCount" value="1" /><br/>

    <!--- Example with simple pluralization rules for en locale --->
    Without Offset:
    <ng-pluralize count="personCount"
                  when="{'0': 'Nobody is viewing.',
                         'one': '1 person is viewing.',
                         'other': '{} people are viewing.'}">
    </ng-pluralize><br>

    <!--- Example with offset --->
    With Offset(2):
    <ng-pluralize count="personCount" offset=2
                  when="{'0': 'Nobody is viewing.',
                         '1': '{{person1}} is viewing.',
                         '2': '{{person1}} and {{person2}} are viewing.',
                         'one': '{{person1}}, {{person2}} and one other person are viewing.',
                         'other': '{{person1}}, {{person2}} and {} other people are viewing.'}">
    </ng-pluralize>
  </div>
</script>
</div>
<div class="tab-pane" title="script.js">
<pre class="prettyprint linenums" ng-set-text="script.js-85"></pre>
<script type="text/ng-template" id="script.js-85">
    function Ctrl($scope) {
      $scope.person1 = 'Igor';
      $scope.person2 = 'Misko';
      $scope.personCount = 1;
    }
  </script>
</div>
<div class="tab-pane" title="End to end test">
<pre class="prettyprint linenums" ng-set-text="scenario.js-87"></pre>
<script type="text/ng-template" id="scenario.js-87">
  it('should show correct pluralized string', function() {
    expect(element('.doc-example-live ng-pluralize:first').text()).
                                       toBe('1 person is viewing.');
    expect(element('.doc-example-live ng-pluralize:last').text()).
                                          toBe('Igor is viewing.');

    using('.doc-example-live').input('personCount').enter('0');
    expect(element('.doc-example-live ng-pluralize:first').text()).
                                         toBe('Nobody is viewing.');
    expect(element('.doc-example-live ng-pluralize:last').text()).
                                        toBe('Nobody is viewing.');

    using('.doc-example-live').input('personCount').enter('2');
    expect(element('.doc-example-live ng-pluralize:first').text()).
                                      toBe('2 people are viewing.');
    expect(element('.doc-example-live ng-pluralize:last').text()).
                        toBe('Igor and Misko are viewing.');

    using('.doc-example-live').input('personCount').enter('3');
    expect(element('.doc-example-live ng-pluralize:first').text()).
                                      toBe('3 people are viewing.');
    expect(element('.doc-example-live ng-pluralize:last').text()).
                        toBe('Igor, Misko and one other person are viewing.');

    using('.doc-example-live').input('personCount').enter('4');
    expect(element('.doc-example-live ng-pluralize:first').text()).
                                      toBe('4 people are viewing.');
    expect(element('.doc-example-live ng-pluralize:last').text()).
                        toBe('Igor, Misko and 2 other people are viewing.');
  });

  it('should show data-binded names', function() {
    using('.doc-example-live').input('personCount').enter('4');
    expect(element('.doc-example-live ng-pluralize:last').text()).
        toBe('Igor, Misko and 2 other people are viewing.');

    using('.doc-example-live').input('person1').enter('Di');
    using('.doc-example-live').input('person2').enter('Vojta');
    expect(element('.doc-example-live ng-pluralize:last').text()).
        toBe('Di, Vojta and 2 other people are viewing.');
  });
</script>
</div>
</div><h2>Demo</h4>
<div class="well doc-example-live animate-container" ng-embed-app="" ng-set-html="index.html-86" ng-eval-javascript="script.js-85"></div>
</div></div>
</div>