Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Really fix the README

  • Loading branch information...
commit b7562ce19af9f3af6d3f9d4a6563439be0bacaaf 1 parent e218a31
Dave McLain authored May 09, 2012

Showing 1 changed file with 67 additions and 10 deletions. Show diff stats Hide diff stats

  1. 77  README.rst
77  README.rst
Source Rendered
@@ -2,22 +2,79 @@ armstrong.apps.related_content
2 2
 ==============================
3 3
 Provides mechanism for relating content to other models
4 4
 
5  
-.. warning:: This is development level software.  Please do not unless you are
6  
-             familiar with what that means and are comfortable using that type
7  
-             of software.
  5
+You can use ``armstrong.apps.related_content`` to link two separate models
  6
+together through a ``GenericForeignKey`` for the ``source`` and the
  7
+``destination``.  You can further organize the relationship with
  8
+``RelatedType`` (think: "articles", "images", "external_links", and so on) and
  9
+all relationships are ordered.
  10
+
8 11
 
9 12
 Usage
10 13
 -----
  14
+You do *not* have to change your models to utilize related content---it exists
  15
+outside of your model.  There are two fields that you can add that give you
  16
+easy access to your related content:
11 17
 
12  
-**TODO**
  18
+* ``armstrong.apps.related_content.fields.RelatedObjectsField``
  19
+* ``armstrong.apps.related_content.fields.ReverseRelatedObjectsField``
  20
+
  21
+The first let's you access objects where your model is the ``source``, the
  22
+latter lets you access objects where your model is the ``destination``.  Note
  23
+that these return the *actual* models that are related, not the
  24
+``RelatedContent`` model.  If you need access to the raw ``RelatedContent``
  25
+model directly from your model, see
  26
+``armstrong.apps.related_content.fields.RelatedContentField``.
  27
+
  28
+You can also use the ``RelatedContentInline`` for exposing an admin interface
  29
+to your related content inside Django's admin.
  30
+
  31
+
  32
+Accessing Related Content
  33
+"""""""""""""""""""""""""
  34
+You can access fields through the ``RelatedObjectsField`` or
  35
+``ReverseRelatedObjectsField`` by calling ``all()`` or
  36
+``by_type("some_type")``.  These return QuerySet-like objects, but since they
  37
+are generic relationships, they're not quite QuerySets.
  38
+
  39
+Inside templates, you can access related content by type using the dot-syntax.
  40
+For example, you could load the first related content of a type ``"articles"``
  41
+with this syntax:
  42
+
  43
+::
  44
+
  45
+    {{ my_article.related.articles.0 }}
13 46
 
14  
-Installation
15  
-------------
  47
+
  48
+Installation & Configuration
  49
+----------------------------
  50
+You can install the latest release of ``armstrong.apps.related_content`` using
  51
+`pip`_:
  52
+
  53
+::
  54
+
  55
+    pip install armstrong.apps.related_content
  56
+
  57
+Make sure to add ``armstrong.apps.related_content`` to your ``INSTALLED_APPS``.
  58
+You can add this however you like.  This works as a copy-and-paste solution:
16 59
 
17 60
 ::
18 61
 
19  
-    name="armstrong.apps.related_content"
20  
-    pip install -e git://github.com/armstrong/$name#egg=$name
  62
+	INSTALLED_APPS += ["armstrong.apps.related_content", ]
  63
+
  64
+Once installed, you have to run either ``syncdb``, or ``migrate`` if you are
  65
+using `South`_.
  66
+
  67
+.. _pip: http://www.pip-installer.org/
  68
+.. _South: http://south.aeracode.org/
  69
+
  70
+
  71
+Backwards Incompatible Changes
  72
+------------------------------
  73
+
  74
+*Version 2.0*
  75
+  * ``RelatedObjectsField`` no longer extends
  76
+    ``genericm2m.models.RelatedObjectsDescriptor``.
  77
+  * All fields have been been moved into the ``fields`` module now.
21 78
 
22 79
 
23 80
 Contributing
@@ -39,7 +96,7 @@ State of Project
39 96
 Armstrong is an open-source news platform that is freely available to any
40 97
 organization.  It is the result of a collaboration between the `Texas Tribune`_
41 98
 and `Bay Citizen`_, and a grant from the `John S. and James L. Knight
42  
-Foundation`_.  The first release is scheduled for June, 2011.
  99
+Foundation`_.
43 100
 
44 101
 To follow development, be sure to join the `Google Group`_.
45 102
 
@@ -55,7 +112,7 @@ probably looking for that.
55 112
 
56 113
 License
57 114
 -------
58  
-Copyright 2011 Bay Citizen and Texas Tribune
  115
+Copyright 2011-2012 Bay Citizen and Texas Tribune
59 116
 
60 117
 Licensed under the Apache License, Version 2.0 (the "License");
61 118
 you may not use this file except in compliance with the License.

0 notes on commit b7562ce

Please sign in to comment.
Something went wrong with that request. Please try again.