array.html 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. <section>
  2. <h2 id="data">
  3. Can I load data into Select2 using an array?
  4. </h2>
  5. <p>
  6. While Select2 is designed to be used with a <code>&lt;select&gt;</code> tag
  7. the data that is used to search through and display the results can be
  8. loaded from a JavaScript array using the <code>data</code> option. This
  9. option should be passed in during the initialization of Select2.
  10. </p>
  11. {% highlight js linenos %}
  12. $('select').select2({
  13. data: [
  14. {
  15. id: 'value',
  16. text: 'Text to display'
  17. },
  18. // ... more data objects ...
  19. ]
  20. });
  21. {% endhighlight %}
  22. <h3>
  23. What properties are required on the objects passed in to the array?
  24. </h3>
  25. <p>
  26. The <code>id</code> and <code>text</code> properties are required on each
  27. object, and these are the properties that Select2 uses for the internal
  28. data objects. Any additional paramters passed in with data objects will be
  29. included on the data objects that Select2 exposes.
  30. </p>
  31. <h3>
  32. Do the <code>id</code> properties have to be strings?
  33. </h3>
  34. <p>
  35. Because the <code>value</code> attributes on a <code>&gt;select&lt;</code>
  36. tag must be strings, the <code>id</code> property on the data objects must
  37. also be strings. Select2 will attempt to convert anything that is not a
  38. string to a string, which will work for most situations, but it is
  39. recommended to force all of your ids to strings ahead of time.
  40. </p>
  41. <h3>
  42. I can't select results with blank ids or an id of <code>0</code>!
  43. </h3>
  44. <p>
  45. See <a href="#do-the-id-properties-have-to-be-strings">Do the <code>id</code> properties have to be strings?</a>.
  46. </p>
  47. <h3>
  48. How should nested results be formatted?
  49. </h3>
  50. <p>
  51. Nested results should be specified using the <code>children</code> property
  52. on the data objects that are passed in. This <code>children</code> property
  53. should be an array of data objects that are grouped under this option, and
  54. the label for the group should be specified as the <code>text</code>
  55. property on the root data object.
  56. </p>
  57. {% highlight js linenos %}
  58. {
  59. text: 'Group label',
  60. children: [
  61. {
  62. id: 'nested-1',
  63. text: 'First nested option'
  64. },
  65. // ... more data objects ...
  66. ]
  67. }
  68. {% endhighlight %}
  69. <h3>
  70. How many levels of nesting are allowed?
  71. </h3>
  72. <p>
  73. Because Select2 falls back to an <code>&lt;optgroup&gt;</code> when
  74. creating nested options, only
  75. <a href="#how-many-levels-of-nesting-can-there-be">a single level of nesting</a>
  76. is supported. Any additional levels of nesting is not guarenteed to be
  77. displayed properly across all browsers and devices.
  78. </p>
  79. <h3>
  80. Why are <code>&lt;option&gt;</code> tags being created?
  81. </h3>
  82. <p>
  83. The <code>data</code> option is a shortcut that Select2 provides which
  84. allows you to load options into your <code>select</code> from a data array.
  85. </p>
  86. {% include options/not-written.html %}
  87. <h3>
  88. My objects don&apos;t use <code>id</code> for their unique identifiers,
  89. what can I do?
  90. </h3>
  91. <p>
  92. Select2 requires that the <code>id</code> property is used to uniquely
  93. identify the options that are displayed in the results list. If you use a
  94. property other than <code>id</code> (like <code>pk</code>) to uniquely
  95. identify an option, you need to map your old property to <code>id</code>
  96. before passing it to Select2.
  97. </p>
  98. <p>
  99. If you cannot do this on your server or you are in a situation where the
  100. identifier cannot be changed, you can do this in JavaScript before passing
  101. it to Select2.
  102. </p>
  103. {% highlight js linenos %}
  104. var data = $.map(yourArrayData, function (obj) {
  105. obj.id = obj.id || obj.pk; // replace pk with your identifier
  106. return obj;
  107. });
  108. {% endhighlight %}
  109. <h3>
  110. My objects use a property other than <code>text</code> for the text that
  111. needs to be displayed
  112. </h3>
  113. <p>
  114. Just like with the <code>id</code> property, Select2 requires that the text
  115. that should be displayed for an option is stored in the <code>text</code>
  116. property. You can map this property from any existing property using the
  117. following JavaScript.
  118. </p>
  119. {% highlight js linenos %}
  120. var data = $.map(yourArrayData, function (obj) {
  121. obj.text = obj.text || obj.name; // replace name with the property used for the text
  122. return obj;
  123. });
  124. {% endhighlight %}
  125. </section>