/app/public/js/libs/angular/docs/partials/api/ng.directive:ngPluralize.html

  1<h1><code ng:non-bindable="">ngPluralize</code>
  2<span class="hint">(directive in module <code ng:non-bindable="">ng</code>
  3)</span>
  4</h1>
  5<div><h2 id="Description">Description</h2>
  6<div class="description"><h3>Overview</h3>
  7
  8<p><code>ngPluralize</code> is a directive that displays messages according to en-US localization rules.
  9These rules are bundled with angular.js and the rules can be overridden
 10(see <a href="guide/i18n">Angular i18n</a> dev guide). You configure ngPluralize directive
 11by specifying the mappings between
 12<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>
 13
 14<h3>Plural categories and explicit number rules</h3>
 15
 16<p>There are two
 17<a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html">plural categories</a> in Angular's default en-US locale: "one" and "other".</p>
 18
 19<p>While a pural category may match many numbers (for example, in en-US locale, "other" can match
 20any number that is not 1), an explicit number rule can only match one number. For example, the
 21explicit number rule for "3" matches the number 3. You will see the use of plural categories
 22and explicit number rules throughout later parts of this documentation.</p>
 23
 24<h3>Configuring ngPluralize</h3>
 25
 26<p>You configure ngPluralize by providing 2 attributes: <code>count</code> and <code>when</code>.
 27You can also provide an optional attribute, <code>offset</code>.</p>
 28
 29<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>
 30
 31<p>The <code>when</code> attribute specifies the mappings between plural categories and the actual
 32string to be displayed. The value of the attribute should be a JSON object so that Angular
 33can interpret it correctly.</p>
 34
 35<p>The following example shows how to configure ngPluralize:</p>
 36
 37<pre class="prettyprint linenums">
 38&lt;ng-pluralize count="personCount"
 39                 when="{'0': 'Nobody is viewing.',
 40                     'one': '1 person is viewing.',
 41                     'other': '{} people are viewing.'}"&gt;
 42&lt;/ng-pluralize&gt;
 43</pre>
 44
 45<p>In the example, <code>"0: Nobody is viewing."</code> is an explicit number rule. If you did not
 46specify this rule, 0 would be matched to the "other" category and "0 people are viewing"
 47would be shown instead of "Nobody is viewing". You can specify an explicit number rule for
 48other numbers, for example 12, so that instead of showing "12 people are viewing", you can
 49show "a dozen people are viewing".</p>
 50
 51<p>You can use a set of closed braces(<code>{}</code>) as a placeholder for the number that you want substituted
 52into pluralized strings. In the previous example, Angular will replace <code>{}</code> with
 53<span ng-non-bindable><code>{{personCount}}</code></span>. The closed braces <code>{}</code> is a placeholder
 54for <span ng-non-bindable>{{numberExpression}}</span>.</p>
 55
 56<h3>Configuring ngPluralize with offset</h3>
 57
 58<p>The <code>offset</code> attribute allows further customization of pluralized text, which can result in
 59a better user experience. For example, instead of the message "4 people are viewing this document",
 60you might display "John, Kate and 2 others are viewing this document".
 61The offset attribute allows you to offset a number by any desired value.
 62Let's take a look at an example:</p>
 63
 64<pre class="prettyprint linenums">
 65&lt;ng-pluralize count="personCount" offset=2
 66              when="{'0': 'Nobody is viewing.',
 67                     '1': '{{person1}} is viewing.',
 68                     '2': '{{person1}} and {{person2}} are viewing.',
 69                     'one': '{{person1}}, {{person2}} and one other person are viewing.',
 70                     'other': '{{person1}}, {{person2}} and {} other people are viewing.'}"&gt;
 71&lt;/ng-pluralize&gt;
 72</pre>
 73
 74<p>Notice that we are still using two plural categories(one, other), but we added
 75three explicit number rules 0, 1 and 2.
 76When one person, perhaps John, views the document, "John is viewing" will be shown.
 77When three people view the document, no explicit number rule is found, so
 78an offset of 2 is taken off 3, and Angular uses 1 to decide the plural category.
 79In this case, plural category 'one' is matched and "John, Marry and one other person are viewing"
 80is shown.</p>
 81
 82<p>Note that when you specify offsets, you must provide explicit number rules for
 83numbers from 0 up to and including the offset. If you use an offset of 3, for example,
 84you must provide explicit number rules for 0, 1, 2 and 3. You must also provide plural strings for
 85plural categories "one" and "other".</p></div>
 86<h2 id="Usage">Usage</h2>
 87<div class="usage">as element (see <a href="guide/ie">IE restrictions</a>)<pre class="prettyprint linenums">&lt;ng-pluralize
 88       count="{string|expression}"
 89       when="{string}"
 90       [offset="{number}"]&gt;
 91&lt;/ng-pluralize&gt;</pre>
 92as attribute<pre class="prettyprint linenums">&lt;ANY ng-pluralize
 93     count="{string|expression}"
 94     when="{string}"
 95     [offset="{number}"]&gt;
 96   ...
 97&lt;/ANY&gt;</pre>
 98<h3 id="Parameters">Parameters</h3>
 99<ul class="parameters"><li><code ng:non-bindable="">count � {string|expression} � </code>
100<p>The variable to be bounded to.</p></li>
101<li><code ng:non-bindable="">when � {string} � </code>
102<p>The mapping between plural category to its correspoding strings.</p></li>
103<li><code ng:non-bindable="">offset<i>(optional)</i> � {number=} � </code>
104<p>Offset to deduct from the total number.</p></li>
105</ul>
106</div>
107<h2 id="Example">Example</h2>
108<div class="example"><h4>Source</h4>
109<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-170" source-edit-css="" source-edit-js="script.js-169" source-edit-unit="" source-edit-scenario="scenario.js-171"></div>
110<div class="tabbable"><div class="tab-pane" title="index.html">
111<pre class="prettyprint linenums" ng-set-text="index.html-170" ng-html-wrap=" angular.js script.js"></pre>
112<script type="text/ng-template" id="index.html-170">
113  
114  <div ng-controller="Ctrl">
115    Person 1:<input type="text" ng-model="person1" value="Igor" /><br/>
116    Person 2:<input type="text" ng-model="person2" value="Misko" /><br/>
117    Number of People:<input type="text" ng-model="personCount" value="1" /><br/>
118
119    <!--- Example with simple pluralization rules for en locale --->
120    Without Offset:
121    <ng-pluralize count="personCount"
122                  when="{'0': 'Nobody is viewing.',
123                         'one': '1 person is viewing.',
124                         'other': '{} people are viewing.'}">
125    </ng-pluralize><br>
126
127    <!--- Example with offset --->
128    With Offset(2):
129    <ng-pluralize count="personCount" offset=2
130                  when="{'0': 'Nobody is viewing.',
131                         '1': '{{person1}} is viewing.',
132                         '2': '{{person1}} and {{person2}} are viewing.',
133                         'one': '{{person1}}, {{person2}} and one other person are viewing.',
134                         'other': '{{person1}}, {{person2}} and {} other people are viewing.'}">
135    </ng-pluralize>
136  </div>
137</script>
138</div>
139<div class="tab-pane" title="script.js">
140<pre class="prettyprint linenums" ng-set-text="script.js-169"></pre>
141<script type="text/ng-template" id="script.js-169">
142    function Ctrl($scope) {
143      $scope.person1 = 'Igor';
144      $scope.person2 = 'Misko';
145      $scope.personCount = 1;
146    }
147  </script>
148</div>
149<div class="tab-pane" title="End to end test">
150<pre class="prettyprint linenums" ng-set-text="scenario.js-171"></pre>
151<script type="text/ng-template" id="scenario.js-171">
152  it('should show correct pluralized string', function() {
153    expect(element('.doc-example-live ng-pluralize:first').text()).
154                                       toBe('1 person is viewing.');
155    expect(element('.doc-example-live ng-pluralize:last').text()).
156                                          toBe('Igor is viewing.');
157
158    using('.doc-example-live').input('personCount').enter('0');
159    expect(element('.doc-example-live ng-pluralize:first').text()).
160                                         toBe('Nobody is viewing.');
161    expect(element('.doc-example-live ng-pluralize:last').text()).
162                                        toBe('Nobody is viewing.');
163
164    using('.doc-example-live').input('personCount').enter('2');
165    expect(element('.doc-example-live ng-pluralize:first').text()).
166                                      toBe('2 people are viewing.');
167    expect(element('.doc-example-live ng-pluralize:last').text()).
168                        toBe('Igor and Misko are viewing.');
169
170    using('.doc-example-live').input('personCount').enter('3');
171    expect(element('.doc-example-live ng-pluralize:first').text()).
172                                      toBe('3 people are viewing.');
173    expect(element('.doc-example-live ng-pluralize:last').text()).
174                        toBe('Igor, Misko and one other person are viewing.');
175
176    using('.doc-example-live').input('personCount').enter('4');
177    expect(element('.doc-example-live ng-pluralize:first').text()).
178                                      toBe('4 people are viewing.');
179    expect(element('.doc-example-live ng-pluralize:last').text()).
180                        toBe('Igor, Misko and 2 other people are viewing.');
181  });
182
183  it('should show data-binded names', function() {
184    using('.doc-example-live').input('personCount').enter('4');
185    expect(element('.doc-example-live ng-pluralize:last').text()).
186        toBe('Igor, Misko and 2 other people are viewing.');
187
188    using('.doc-example-live').input('person1').enter('Di');
189    using('.doc-example-live').input('person2').enter('Vojta');
190    expect(element('.doc-example-live ng-pluralize:last').text()).
191        toBe('Di, Vojta and 2 other people are viewing.');
192  });
193</script>
194</div>
195</div><h4>Demo</h4>
196<div class="well doc-example-live" ng-embed-app="" ng-set-html="index.html-170" ng-eval-javascript="script.js-169"></div></div>
197</div>