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

https://bitbucket.org/kaiquewdev/front-in-sampa-example · HTML · 197 lines · 169 code · 26 blank · 2 comment · 0 complexity · bed25b4ffbaeeddc7f1cbdde52f4b1f9 MD5 · raw file

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