|
1 | | -API Documentation |
2 | | -================= |
| 1 | +################### |
| 2 | + API Documentation |
| 3 | +################### |
3 | 4 |
|
4 | | -Configuration |
5 | | -------------- |
| 5 | +*************** |
| 6 | + Configuration |
| 7 | +*************** |
6 | 8 |
|
7 | 9 | .. automodule:: django_select2.conf |
8 | | - :members: |
9 | | - :undoc-members: |
10 | | - :show-inheritance: |
| 10 | + :members: |
| 11 | + :undoc-members: |
| 12 | + :show-inheritance: |
11 | 13 |
|
12 | | -Widgets |
13 | | -------- |
| 14 | +********* |
| 15 | + Widgets |
| 16 | +********* |
14 | 17 |
|
15 | 18 | .. automodule:: django_select2.forms |
16 | | - :members: |
17 | | - :undoc-members: |
18 | | - :show-inheritance: |
| 19 | + :members: |
| 20 | + :undoc-members: |
| 21 | + :show-inheritance: |
19 | 22 |
|
20 | | -URLs |
21 | | ----- |
| 23 | +****** |
| 24 | + URLs |
| 25 | +****** |
22 | 26 |
|
23 | 27 | .. automodule:: django_select2.urls |
24 | | - :members: |
25 | | - :undoc-members: |
26 | | - :show-inheritance: |
| 28 | + :members: |
| 29 | + :undoc-members: |
| 30 | + :show-inheritance: |
27 | 31 |
|
28 | | -Views |
29 | | ------ |
| 32 | +******* |
| 33 | + Views |
| 34 | +******* |
30 | 35 |
|
31 | 36 | .. automodule:: django_select2.views |
32 | | - :members: |
33 | | - :undoc-members: |
34 | | - :show-inheritance: |
| 37 | + :members: |
| 38 | + :undoc-members: |
| 39 | + :show-inheritance: |
35 | 40 |
|
36 | | -Cache |
37 | | ------ |
| 41 | +******* |
| 42 | + Cache |
| 43 | +******* |
38 | 44 |
|
39 | 45 | .. automodule:: django_select2.cache |
40 | | - :members: |
41 | | - :undoc-members: |
42 | | - :show-inheritance: |
| 46 | + :members: |
| 47 | + :undoc-members: |
| 48 | + :show-inheritance: |
43 | 49 |
|
| 50 | +************ |
| 51 | + JavaScript |
| 52 | +************ |
44 | 53 |
|
45 | | -JavaScript |
46 | | ----------- |
| 54 | +DjangoSelect2 handles the initialization of select2 fields |
| 55 | +automatically. Just include ``{{ form.media.js }}`` in your template |
| 56 | +before the closing ``body`` tag. That's it! |
47 | 57 |
|
48 | | -DjangoSelect2 handles the initialization of select2 fields automatically. Just include |
49 | | -``{{ form.media.js }}`` in your template before the closing ``body`` tag. That's it! |
| 58 | +If you insert forms after page load or if you want to handle the |
| 59 | +initialization yourself, DjangoSelect2 provides a jQuery plugin, |
| 60 | +replacing and enhancing the Select2 plugin. It will handle both normal |
| 61 | +and heavy fields. Simply call ``djangoSelect2(options)`` on your select |
| 62 | +fields.: |
50 | 63 |
|
51 | | -If you insert forms after page load or if you want to handle the initialization |
52 | | -yourself, DjangoSelect2 provides a jQuery plugin, replacing and enhancing the Select2 |
53 | | -plugin. It will handle both normal and heavy fields. Simply call |
54 | | -``djangoSelect2(options)`` on your select fields.:: |
| 64 | +.. code:: |
55 | 65 |
|
56 | | - $('.django-select2').djangoSelect2(); |
| 66 | + $('.django-select2').djangoSelect2(); |
57 | 67 |
|
58 | 68 | Please replace all your ``.select2`` invocations with the here provided |
59 | 69 | ``.djangoSelect2``. |
60 | 70 |
|
| 71 | +********************* |
| 72 | + Configuring Select2 |
| 73 | +********************* |
61 | 74 |
|
62 | | -Configuring Select2 |
63 | | -------------------- |
64 | | - |
65 | | -Select2 options can be configured either directly from Javascript or from within Django |
66 | | -using widget attributes. `(List of options in the Select2 docs) <https://select2.org/configuration/options-api>`_. |
| 75 | +Select2 options can be configured either directly from Javascript or |
| 76 | +from within Django using widget attributes. `(List of options in the |
| 77 | +Select2 docs) <https://select2.org/configuration/options-api>`_. |
67 | 78 |
|
68 | 79 | To pass options in javascript |
69 | 80 |
|
70 | | -.. code-block:: javascript |
71 | | -
|
72 | | - $('.django-select2').djangoSelect2({ |
73 | | - minimumInputLength: 0, |
74 | | - placeholder: 'Select an option', |
75 | | - }); |
76 | | -
|
77 | | -From Django, you can use ``data-`` attributes using the same names in camel-case and |
78 | | -passing them to your widget. Select2 will then pick these up. For example when |
79 | | -initialising a widget in a form, you could do: |
80 | | - |
81 | | -.. code-block:: python |
82 | | -
|
83 | | - class MyForm(forms.Form): |
84 | | - my_field = forms.ModelMultipleChoiceField( |
85 | | - widget=ModelSelect2MultipleWidget( |
86 | | - model=MyModel |
87 | | - search_fields=['another_field'] |
88 | | - attrs={ |
89 | | - "data-minimum-input-length": 0, |
90 | | - "data-placeholder": "Select an option", |
91 | | - "data-close-on-select": "false", |
92 | | - } |
93 | | - ) |
94 | | - ) |
95 | | -
|
96 | | -(If you do not want to initialize the widget, you could add the attributes by overriding |
97 | | -a widget method and adding them in a super call, e.g. `get_context() <https://docs.djangoproject.com/en/dev/ref/forms/widgets/#django.forms.Widget.get_context>`_) |
98 | | - |
99 | | - |
100 | | -Security & Authentication |
101 | | -------------------------- |
| 81 | +.. code:: javascript |
| 82 | +
|
| 83 | + $('.django-select2').djangoSelect2({ |
| 84 | + minimumInputLength: 0, |
| 85 | + placeholder: 'Select an option', |
| 86 | + }); |
| 87 | +
|
| 88 | +From Django, you can use ``data-`` attributes using the same names in |
| 89 | +camel-case and passing them to your widget. Select2 will then pick these |
| 90 | +up. For example when initialising a widget in a form, you could do: |
| 91 | + |
| 92 | +.. code:: python |
| 93 | +
|
| 94 | + class MyForm(forms.Form): |
| 95 | + my_field = forms.ModelMultipleChoiceField( |
| 96 | + widget=ModelSelect2MultipleWidget( |
| 97 | + model=MyModel |
| 98 | + search_fields=['another_field'] |
| 99 | + attrs={ |
| 100 | + "data-minimum-input-length": 0, |
| 101 | + "data-placeholder": "Select an option", |
| 102 | + "data-close-on-select": "false", |
| 103 | + } |
| 104 | + ) |
| 105 | + ) |
| 106 | +
|
| 107 | +(If you do not want to initialize the widget, you could add the |
| 108 | +attributes by overriding a widget method and adding them in a super |
| 109 | +call, e.g. `get_context() |
| 110 | +<https://docs.djangoproject.com/en/dev/ref/forms/widgets/#django.forms.Widget.get_context>`_) |
| 111 | + |
| 112 | +*************************** |
| 113 | + Security & Authentication |
| 114 | +*************************** |
102 | 115 |
|
103 | 116 | Security is important. Therefore make sure to read and understand what |
104 | 117 | the security measures in place and their limitations. |
105 | 118 |
|
106 | | -Set up a separate cache. If you have a public form that uses a model widget |
107 | | -make sure to setup a separate cache database for Select2. An attacker |
108 | | -could constantly reload your site and fill up the select2 cache. |
109 | | -Having a separate cache allows you to limit the effect to select2 only. |
| 119 | +Set up a separate cache. If you have a public form that uses a model |
| 120 | +widget make sure to setup a separate cache database for Select2. An |
| 121 | +attacker could constantly reload your site and fill up the select2 |
| 122 | +cache. Having a separate cache allows you to limit the effect to select2 |
| 123 | +only. |
110 | 124 |
|
111 | 125 | You might want to add a secure select2 JSON endpoint for data you don't |
112 | | -want to be accessible to the general public. Doing so is easy:: |
| 126 | +want to be accessible to the general public. Doing so is easy: |
| 127 | + |
| 128 | +.. code:: |
113 | 129 |
|
114 | | - class UserSelect2View(LoginRequiredMixin, AutoResponseView): |
115 | | - pass |
| 130 | + class UserSelect2View(LoginRequiredMixin, AutoResponseView): |
| 131 | + pass |
116 | 132 |
|
117 | | - class UserSelect2WidgetMixin(object): |
118 | | - def __init__(self, *args, **kwargs): |
119 | | - kwargs['data_view'] = 'user-select2-view' |
120 | | - super(UserSelect2WidgetMixin, self).__init__(*args, **kwargs) |
| 133 | + class UserSelect2WidgetMixin(object): |
| 134 | + def __init__(self, *args, **kwargs): |
| 135 | + kwargs['data_view'] = 'user-select2-view' |
| 136 | + super(UserSelect2WidgetMixin, self).__init__(*args, **kwargs) |
121 | 137 |
|
122 | | - class MySecretWidget(UserSelect2WidgetMixin, ModelSelect2Widget): |
123 | | - model = MySecretModel |
124 | | - search_fields = ['title__icontains'] |
| 138 | + class MySecretWidget(UserSelect2WidgetMixin, ModelSelect2Widget): |
| 139 | + model = MySecretModel |
| 140 | + search_fields = ['title__icontains'] |
0 commit comments