diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index e05c03061..be41a2c79 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -297,6 +297,35 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. --- +# Compound Fields + +These fields represent compound datatypes, which build on other fields with some additional aspect such collecting multiple elements. + +## ListField + +A list representation, whose elements are described by a given item field. This means that all elements must meet the definition of +that field. The item field can be another field type (e.g., CharField) or a serializer. If `item_field` is not given, then the +list-items are passed through as-is, and can be anything. Note that in this case, any non-native list elements wouldn't be properly +prepared for data rendering. + +**Signature:** `ListField(item_field=None)` + +## DictField + +A dictionary representation, whose values are described by a given value field. This means that all values must meet the definition of +that field. The value field can be another field type (e.g., CharField) or a serializer. If `value_field` is not given, then the `dict` +values are passed through-as-is, and can be anything. Note that in this case, any non-native `dict` values wouldn't be properly +prepared for data rendering. + +Dictionary keys are presumed to be character strings or convertible to such, and so during processing are casted to `unicode`. If +necessary, options for unicode conversion (such as the encoding, or error processing) can be provided to a `DictField`. For more info, +see [py_unicode]. + +**Signature:** `DictField(value_field=None, unicode_options=None)` + +If given, unicode_options must be a dict providing options per the [unicode](http://docs.python.org/2/library/functions.html#unicode) +function. + # Custom fields If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods. These two methods are used to convert between the initial datatype, and a primitive, serializable datatype. Primitive datatypes may be any of a number, string, date/time/datetime or None. They may also be any list or dictionary like object that only contains other primitive objects. @@ -345,3 +374,4 @@ As an example, let's create a field that can be used represent the class name of [ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior [iso8601]: http://www.w3.org/TR/NOTE-datetime +[py_unicode]: http://docs.python.org/2/howto/unicode.html