1.1 --- a/README.txt	Thu Aug 13 12:13:02 2009 -0500
     1.2 +++ b/README.txt	Thu Aug 13 12:41:22 2009 -0500
     1.3 @@ -1,62 +1,69 @@
     1.4 +Limited Related Admin
     1.5 +=====================
     1.6 +
     1.7  What is this?
     1.8 -================================================================================
     1.9 -In the typical Django admin when you use a related field (e.g., a `ForeignKey` 
    1.10 -or `ManyToManyField`) you are present with _every_ possible relation for your
    1.11 +-------------
    1.12 +
    1.13 +In the typical Django admin when you use a related field (e.g., a ``ForeignKey`` 
    1.14 +or ``ManyToManyField``) you are present with _every_ possible relation for your
    1.15  choices.  While this is OK for small number of possible relations, the admin
    1.16  can quickly die when there are thousands of related possibilities.  The typical 
    1.17 -solution is to use the `raw_id_fields` option, however this is too "raw" --
    1.18 +solution is to use the ``raw_id_fields`` option, however this is too "raw" --
    1.19  an ID provides no information about the object it's attached to.
    1.20  
    1.21 -The `LimitedRelatedAdmin` makes it possible to only view the related objects 
    1.22 +The ``LimitedRelatedAdmin`` makes it possible to only view the related objects 
    1.23  that are associated with the current model being viewed (through the objects
    1.24  representation, rather than its ID), and allows the user to modify the related
    1.25  objects via popup windows.
    1.26  
    1.27  Installation
    1.28 -================================================================================
    1.29 -Make sure `limited_related` is in your PYTHONPATH, and add `limited_related` to
    1.30 -your `INSTALLED_APPS`.
    1.31 +------------
    1.32 +
    1.33 +Make sure ``limited_related`` is in your PYTHONPATH, and add ``limited_related``
    1.34 +to your `INSTALLED_APPS`.
    1.35  
    1.36  Example
    1.37 -================================================================================
    1.38 +-------
    1.39  
    1.40 -Code:
    1.41 -----------------------------------------------------------
    1.42 -### models.py ###
    1.43 -from django.db import models
    1.44 +Here's an example ``models.py``::
    1.45  
    1.46 -class Location(models.Model):
    1.47 -    name = models.CharField(max_length=50)
    1.48 -    def __unicode__(self): return self.name
    1.49 +    from django.db import models
    1.50 +    
    1.51 +    class Location(models.Model):
    1.52 +        name = models.CharField(max_length=50)
    1.53 +        def __unicode__(self): return self.name
    1.54  
    1.55 -class Person(models.Model):
    1.56 -    name = models.CharField(max_length=50)
    1.57 -    location = models.ForeignKey(Location)
    1.58 -    def __unicode__(self): return self.name
    1.59 +    class Person(models.Model):
    1.60 +        name = models.CharField(max_length=50)
    1.61 +        location = models.ForeignKey(Location)
    1.62 +        def __unicode__(self): return self.name
    1.63  
    1.64 -class Group(models.Model):
    1.65 -    name = models.CharField(max_length=50)
    1.66 -    people = models.ManyToManyField(Person)
    1.67 -    def __unicode__(self): return self.name
    1.68 +    class Group(models.Model):
    1.69 +        name = models.CharField(max_length=50)
    1.70 +        people = models.ManyToManyField(Person)
    1.71 +        def __unicode__(self): return self.name
    1.72      
    1.73 -### admin.py ###
    1.74 -from django.contrib import admin
    1.75 -from models import Location, Person, Group
    1.76 -from limited_related import LimitedRelatedAdmin
    1.77 +And the corresponding ``admin.py`` for the application::
    1.78  
    1.79 -class LocationAdmin(LimitedRelatedAdmin): pass
    1.80 +    from django.contrib import admin
    1.81 +    from models import Location, Person, Group
    1.82 +    from limited_related import LimitedRelatedAdmin
    1.83  
    1.84 -class PersonAdmin(LimitedRelatedAdmin):
    1.85 -    limited_related = ['location']
    1.86 +    class LocationAdmin(LimitedRelatedAdmin): pass
    1.87  
    1.88 -class GroupAdmin(LimitedRelatedAdmin):
    1.89 -    limited_related = ['people']
    1.90 +    class PersonAdmin(LimitedRelatedAdmin):
    1.91 +        limited_related = ['location']
    1.92  
    1.93 -admin.site.register(Location, LocationAdmin)
    1.94 -admin.site.register(Person, PersonAdmin)
    1.95 -admin.site.register(Group, GroupAdmin)
    1.96 -----------------------------------------------------------------
    1.97 +    class GroupAdmin(LimitedRelatedAdmin):
    1.98 +        limited_related = ['people']
    1.99  
   1.100 -Note: Even though `Location` has no related fields, the `LimitedRelatedAdmin`
   1.101 -must be used in order for it to work correctly in the `Person` admin screen.
   1.102 -This is the only "catch", no patches required (as in previous versions).
   1.103 +    admin.site.register(Location, LocationAdmin)
   1.104 +    admin.site.register(Person, PersonAdmin)
   1.105 +    admin.site.register(Group, GroupAdmin)
   1.106 +    
   1.107 +.. note ::
   1.108 +
   1.109 +    Even though ``Location`` has no related fields, the 
   1.110 +    ``LimitedRelatedAdmin`` must be used in order for it to work correctly 
   1.111 +    in the ``Person`` admin screen.  This is the only "catch", no patches 
   1.112 +    required (as in previous versions).