From 97a7f27c8219181e40dddcaf820545e08283de93 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 9 Oct 2012 15:58:48 +0100
Subject: Rename HTMLTemplateRenderer -> HTMLRenderer, DocuemntingHTMLRenderer
 -> BrowseableAPIRenderer

---
 docs/api-guide/fields.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 113 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide/fields.md')

diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index e9833a97..df54ea02 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -16,13 +16,48 @@ Serializer fields handle converting between primative values and internal dataty
 
 # Generic Fields
 
+These generic fields are used for representing arbitrary model fields or the output of model methods.
+
 ## Field
 
-A generic, read-only field.  You can use this field for any attribute that does not need to support write operations.
+A generic, **read-only** field.  You can use this field for any attribute that does not need to support write operations.
+
+For example, using the following model.
+
+    class Account(models.Model):
+        owner = models.ForeignKey('auth.user')
+        name = models.CharField(max_length=100)
+        created = models.DateTimeField(auto_now_add=True)
+        payment_expiry = models.DateTimeField()
+        
+        def has_expired(self):
+            now = datetime.datetime.now()
+            return now > self.payment_expiry
+
+A serializer definition that looked like this:
+
+    class AccountSerializer(serializers.HyperlinkedModelSerializer):
+        expired = Field(source='has_expired')
+        
+        class Meta:
+            fields = ('url', 'owner', 'name', 'expired')
+
+Would produced output similar to:
+
+    {
+        'url': 'http://example.com/api/accounts/3/',
+        'owner': 'http://example.com/api/users/12/',
+        'name': 'FooCorp business account', 
+        'expired': True
+    }
+
+Be default, the `Field` class will perform a basic translation of the source value into primative datatypes, falling back to unicode representations of complex datatypes when neccesary.
+
+You can customize this  behaviour by overriding the `.to_native(self, value)` method.
 
 ## WritableField
 
-A field that supports both read and 
+A field that supports both read and write operations.  By itself `WriteableField` does not perform any translation of input values into a given type.  You won't typically use this field directly, but you may want to override it and implement the `.to_native(self, value)` and `.from_native(self, value)` methods.
 
 ## ModelField
 
@@ -56,10 +91,86 @@ These fields represent basic datatypes, and support both reading and writing val
 
 Relational fields are used to represent model relationships.  They can be applied to `ForeignKey`, `ManyToManyField` and `OneToOneField` relationships, as well as to reverse relationships, and custom relationships such as `GenericForeignKey`.
 
+## RelatedField
+
+This field can be applied to any of the following:
+
+* A `ForeignKey` field.
+* A `OneToOneField` field.
+* A reverse OneToOne relationship
+* Any other "to-one" relationship.
+
+By default `RelatedField` will represent the target of the field using it's `__unicode__` method.
+
+You can customise this behaviour by subclassing `ManyRelatedField`, and overriding the `.to_native(self, value)` method.
+
+## ManyRelatedField
+
+This field can be applied to any of the following:
+ 
+* A `ManyToManyField` field.
+* A reverse ManyToMany relationship.
+* A reverse ForeignKey relationship
+* Any other "to-many" relationship.
+
+By default `ManyRelatedField` will represent the targets of the field using their `__unicode__` method.
+
+For example, given the following models:
+
+    class TaggedItem(models.Model):
+        """
+        Tags arbitrary model instances using a generic relation.
+        
+        See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/
+        """
+        tag = models.SlugField()
+        content_type = models.ForeignKey(ContentType)
+        object_id = models.PositiveIntegerField()
+        content_object = GenericForeignKey('content_type', 'object_id')
+    
+        def __unicode__(self):
+            return self.tag
+    
+    
+    class Bookmark(models.Model):
+        """
+        A bookmark consists of a URL, and 0 or more descriptive tags.
+        """
+        url = models.URLField()
+        tags = GenericRelation(TaggedItem)
+
+And a model serializer defined like this:
+
+    class BookmarkSerializer(serializers.ModelSerializer):
+        tags = serializers.ManyRelatedField(source='tags')
+
+        class Meta:
+            model = Bookmark
+            exclude = ('id',)
+
+The an example output format for a Bookmark instance would be:
+
+    {
+        'tags': [u'django', u'python'],
+        'url': u'https://www.djangoproject.com/'
+    }
+
 ## PrimaryKeyRelatedField
 
+As with `RelatedField` field can be applied to any "to-one" relationship, such as a `ForeignKey` field.
+
+`PrimaryKeyRelatedField` will represent the target of the field using it's primary key.
+
+Be default, `PrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `readonly` flag.
+
 ## ManyPrimaryKeyRelatedField
 
+As with `RelatedField` field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship.
+
+`PrimaryKeyRelatedField` will represent the target of the field using their primary key.
+
+Be default, `ManyPrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `readonly` flag.
+
 ## HyperlinkedRelatedField
 
 ## ManyHyperlinkedRelatedField
-- 
cgit v1.2.3