Skip to content

D
django-rest-framework
Commit 5cbb535d by Tom Christie
Options

Update documentation

parent 4d5a47de
Showing with 42 additions and 4 deletions
.DS_Store 0 → 100644
File added
api-guide/fields/index.html
......@@ -613,7 +613,7 @@ color_channel = serializers.ChoiceField(
style = {'base_template': 'radio.html'}
}
</code></pre>
<p><strong>Note</strong>: The <code>style</code> argument replaces the old-style version 2.x <code>widget</code> keyword argument. Because REST framework 3 now uses templated HTML form generation, the <code>widget</code> option that was used to support Django built-in widgets can no longer be supported. Version 3.1 is planned to include public API support for customizing HTML form generation.</p>
<p><strong>Note</strong>: The <code>style</code> argument replaces the old-style version 2.x <code>widget</code> keyword argument. Because REST framework 3 now uses templated HTML form generation, the <code>widget</code> option that was used to support Django built-in widgets can no longer be supported. Version 3.3 is planned to include public API support for customizing HTML form generation.</p>
<hr />
<h1 id="boolean-fields">Boolean fields</h1>
<h2 id="booleanfield">BooleanField</h2>
......@@ -787,6 +787,8 @@ The representation is a string following this format <code>'[DD] [HH:[MM:]]ss[.u
<ul>
<li><code>choices</code> - A list of valid values, or a list of <code>(key, display_name)</code> tuples.</li>
<li><code>allow_blank</code> - If set to <code>True</code> then the empty string should be considered a valid value. If set to <code>False</code> then the empty string is considered invalid and will raise a validation error. Defaults to <code>False</code>.</li>
<li><code>html_cutoff</code> - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to <code>None</code>.</li>
<li><code>html_cutoff_text</code> - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to <code>"More than {count} items…"</code></li>
</ul>
<p>Both the <code>allow_blank</code> and <code>allow_null</code> are valid options on <code>ChoiceField</code>, although it is highly recommended that you only use one and not both. <code>allow_blank</code> should be preferred for textual choices, and <code>allow_null</code> should be preferred for numeric or other non-textual choices.</p>
<h2 id="multiplechoicefield">MultipleChoiceField</h2>
......@@ -795,6 +797,8 @@ The representation is a string following this format <code>'[DD] [HH:[MM:]]ss[.u
<ul>
<li><code>choices</code> - A list of valid values, or a list of <code>(key, display_name)</code> tuples.</li>
<li><code>allow_blank</code> - If set to <code>True</code> then the empty string should be considered a valid value. If set to <code>False</code> then the empty string is considered invalid and will raise a validation error. Defaults to <code>False</code>.</li>
<li><code>html_cutoff</code> - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Can be used to ensure that automatically generated ChoiceFields with very large possible selections do not prevent a template from rendering. Defaults to <code>None</code>.</li>
<li><code>html_cutoff_text</code> - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to <code>"More than {count} items…"</code></li>
</ul>
<p>As with <code>ChoiceField</code>, both the <code>allow_blank</code> and <code>allow_null</code> options are valid, although it is highly recommended that you only use one and not both. <code>allow_blank</code> should be preferred for textual choices, and <code>allow_null</code> should be preferred for numeric or other non-textual choices.</p>
<hr />
......
api-guide/filtering/index.html
......@@ -556,6 +556,7 @@ class UserListView(generics.ListAPIView):
<pre><code>import django_filters
from myapp.models import Product
from myapp.serializers import ProductSerializer
from rest_framework import filters
from rest_framework import generics
class ProductFilter(django_filters.FilterSet):
......@@ -637,6 +638,7 @@ class ProductFilter(django_filters.FilterSet):
<li>'^' Starts-with search.</li>
<li>'=' Exact matches.</li>
<li>'@' Full-text search. (Currently only supported Django's MySQL backend.)</li>
<li>'$' Regex search.</li>
</ul>
<p>For example:</p>
<pre><code>search_fields = ('=username', '=email')
......
api-guide/relations/index.html
......@@ -338,7 +338,7 @@
<li>
<a href="#inspecting-automatically-generated-relationships">Inspecting automatically generated relationships.</a>
<a href="#inspecting-relationships">Inspecting relationships.</a>
</li>
......@@ -418,6 +418,10 @@
</li>
<li>
<a href="#select-field-cutoffs">Select field cutoffs</a>
</li>
<li>
<a href="#reverse-relations">Reverse relations</a>
</li>
......@@ -467,7 +471,7 @@ Good programmers worry about data structures and their relationships.</p>
<hr />
<p><strong>Note:</strong> The relational fields are declared in <code>relations.py</code>, but by convention you should import them from the <code>serializers</code> module, using <code>from rest_framework import serializers</code> and refer to fields as <code>serializers.&lt;FieldName&gt;</code>.</p>
<hr />
<h4 id="inspecting-automatically-generated-relationships">Inspecting automatically generated relationships.</h4>
<h4 id="inspecting-relationships">Inspecting relationships.</h4>
<p>When using the <code>ModelSerializer</code> class, serializer fields and relationships will be automatically generated for you. Inspecting these automatically generated fields can be a useful tool for determining how to customize the relationship style.</p>
<p>To do so, open the Django shell, using <code>python manage.py shell</code>, then import the serializer class, instantiate it, and print the object representation…</p>
<pre><code>&gt;&gt;&gt; from myapp.serializers import AccountSerializer
......@@ -817,6 +821,21 @@ class CustomerHyperlink(serializers.HyperlinkedRelatedField):
def display_value(self, instance):
return 'Track: %s' % (instance.title)
</code></pre>
<h2 id="select-field-cutoffs">Select field cutoffs</h2>
<p>When rendered in the browsable API relational fields will default to only displaying a maximum of 1000 selectable items. If more items are present then a disabled option with "More than 1000 items…" will be displayed.</p>
<p>This behavior is intended to prevent a template from being unable to render in an acceptable timespan due to a very large number of relationships being displayed.</p>
<p>There are two keyword arguments you can use to control this behavior:</p>
<ul>
<li><code>html_cutoff</code> - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to <code>None</code> to disable any limiting. Defaults to <code>1000</code>.</li>
<li><code>html_cutoff_text</code> - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to <code>"More than {count} items…"</code></li>
</ul>
<p>In cases where the cutoff is being enforced you may want to instead use a plain input field in the HTML form. You can do so using the <code>style</code> keyword argument. For example:</p>
<pre><code>assigned_to = serializers.SlugRelatedField(
queryset=User.objects.all(),
slug field='username',
style={'base_template': 'input.html'}
)
</code></pre>
<h2 id="reverse-relations">Reverse relations</h2>
<p>Note that reverse relationships are not automatically included by the <code>ModelSerializer</code> and <code>HyperlinkedModelSerializer</code> classes. To include a reverse relationship, you must explicitly add it to the fields list. For example:</p>
<pre><code>class AlbumSerializer(serializers.ModelSerializer):
......
mkdocs/search_index.json
This source diff could not be displayed because it is too large. You can view the blob instead.
topics/release-notes/index.html
......@@ -406,8 +406,19 @@
</code></pre>
<hr />
<h2 id="32x-series">3.2.x series</h2>
<h3 id="323">3.2.3</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.3+Release%22">24th August 2015</a>.</p>
<ul>
<li>Added <code>html_cutoff</code> and <code>html_cutoff_text</code> for limiting select dropdowns. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3313">#3313</a>)</li>
<li>Added regex style to <code>SearchFilter</code>. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3316">#3316</a>)</li>
<li>Resolve issues with setting blank HTML fields. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3318">#3318</a>) (<a href="https://github.com/tomchristie/django-rest-framework/issues/3321">#3321</a>)</li>
<li>Correctly display existing 'select multiple' values in browsable API forms. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3290">#3290</a>)</li>
<li>Resolve duplicated validation message for <code>IPAddressField</code>. ([#3249[gh3249]) (<a href="https://github.com/tomchristie/django-rest-framework/issues/3250">#3250</a>)</li>
<li>Fix to ensure admin renderer continues to work when pagination is disabled. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3275">#3275</a>)</li>
<li>Resolve error with <code>LimitOffsetPagination</code> when count=0, offset=0. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3303">#3303</a>)</li>
</ul>
<h3 id="322">3.2.2</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.1+Release%22">13th August 2015</a>.</p>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.2+Release%22">13th August 2015</a>.</p>
<ul>
<li>Add <code>display_value()</code> method for use when displaying relational field select inputs. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3254">#3254</a>)</li>
<li>Fix issue with <code>BooleanField</code> checkboxes incorrectly displaying as checked. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3258">#3258</a>)</li>
......@@ -617,6 +628,8 @@
<!-- 3.2.2 -->
<!-- 3.2.3 -->
</div> <!--/span-->
</div> <!--/row-->
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment