Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Update the docs and tweak some pep8/pyflakes issues #1

Merged
merged 7 commits into from

2 participants

@tswicegood

No description provided.

tswicegood added some commits
@tswicegood tswicegood Remove unnecessary sentence fddc91c
@tswicegood tswicegood Update copyright year 8325f9a
@tswicegood tswicegood Tweak intro a bit 510cb1d
@tswicegood tswicegood Convert these into sub-sections 4540112
@tswicegood tswicegood Switch over to new installation & configuration section 2823bff
@tswicegood tswicegood pep8 and pyflakes issues fc19c75
@tswicegood tswicegood Simplify README
This is part of a move toward better documentation across the board.
README files aren't the best place to put end-user documentation, so
I've removed a few of the more documentation-oriented things.
4487af3
@dmclain dmclain closed this
@dmclain dmclain reopened this
@dmclain dmclain merged commit a478bea into dmclain:related_content2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 26, 2012
  1. @tswicegood

    Remove unnecessary sentence

    tswicegood authored
  2. @tswicegood

    Update copyright year

    tswicegood authored
  3. @tswicegood

    Tweak intro a bit

    tswicegood authored
  4. @tswicegood
  5. @tswicegood
  6. @tswicegood

    pep8 and pyflakes issues

    tswicegood authored
  7. @tswicegood

    Simplify README

    tswicegood authored
    This is part of a move toward better documentation across the board.
    README files aren't the best place to put end-user documentation, so
    I've removed a few of the more documentation-oriented things.
This page is out of date. Refresh to see the latest.
Showing with 62 additions and 44 deletions.
  1. +48 −37 README.rst
  2. +14 −7 armstrong/apps/related_content/fields.py
View
85 README.rst
@@ -2,59 +2,70 @@ armstrong.apps.related_content
==============================
Provides mechanism for relating content to other models
-Overview
---------
+You can use ``armstrong.apps.related_content`` to link two separate models
+together through a ``GenericForeignKey`` for the ``source`` and the
+``destination``. You can further organize the relationship with
+``RelatedType`` (think: "articles", "images", "external_links", and so on) and
+all relationships are ordered.
-armstrong.apps.related_content provides a model that generically links objects
-as well as providing a type and ordering for those links. The heart of the system is
-the RelatedContent type which consits of a GenericForeignKey to a source object, a
-GenericForeignKey to a destination object, an IntegerField for order and a ForeignKey
-to a RelatedType object that consists of a title.
+Usage
+-----
+You do *not* have to change your models to utilize related content---it exists
+outside of your model. There are two fields that you can add that give you
+easy access to your related content:
-Creating RelatedContent objects
--------------------------------
+* ``armstrong.apps.related_content.fields.RelatedObjectsField``
+* ``armstrong.apps.related_content.fields.ReverseRelatedObjectsField``
-This package provides ``armstrong.apps.related_content.admin.RelatedContentInline`` which
-should be the primary way that staff interact with the related_content system.
+The first let's you access objects where your model is the ``source``, the
+latter lets you access objects where your model is the ``destination``. Note
+that these return the *actual* models that are related, not the
+``RelatedContent`` model. If you need access to the raw ``RelatedContent``
+model directly from your model, see
+``armstrong.apps.related_content.fields.RelatedContentField``.
-For python access, we provide ``armstrong.apps.related_content.fields.RelatedContentField``
-which is a `GenericRelation`_ that has the right defaults to work with the related_content
-system.
-
-.. _GenericRelation: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#reverse-generic-relations
+You can also use the ``RelatedContentInline`` for exposing an admin interface
+to your related content inside Django's admin.
Accessing Related Content
--------------------------
+"""""""""""""""""""""""""
+You can access fields through the ``RelatedObjectsField`` or
+``ReverseRelatedObjectsField`` by calling ``all()`` or
+``by_type("some_type")``. These return QuerySet-like objects, but since they
+are generic relationships, they're not quite QuerySets.
-For convenient access, we provide ``armstrong.apps.related_content.fields.RelatedObjectsField``
-and ``armstrong.apps.related_content.fields.ReverseRelatedObjectsField``. These fields
-utilize the GenericForeignKeyQuerySet for efficient access of the objects on the
-far side of the RelatedContent objects. For example::
+Inside templates, you can access related content by type using the dot-syntax.
+For example, you could load the first related content of a type ``"articles"``
+with this syntax:
- obj.related['lead_art'][0]
- # retrieves the destination_object from the first RelatedContent object with
- # a RelatedType with title 'lead_art'
+::
-While this syntax might seem somewhat strange, it allows for convenient usage in templates::
+ {{ my_article.related.articles.0 }}
- {% load layout_helpers %}
- {% render_model object.related.lead_art.0 'lead_art' %}
-This usage will render the lead_art.html template that is appropriate for the type that
-the user has associated with the object. This means you can have a lead_art relationship
-to an Image, or an ImageSet or an embeded video type as long as you have a lead_art.html
-template in the right place.
+Installation & Configuration
+----------------------------
+You can install the latest release of ``armstrong.apps.related_content`` using
+`pip`_:
+::
-Installation
-------------
+ pip install armstrong.apps.related_content
+
+Make sure to add ``armstrong.apps.related_content`` to your ``INSTALLED_APPS``.
+You can add this however you like. This works as a copy-and-paste solution:
::
- name="armstrong.apps.related_content"
- pip install -e git://github.com/armstrong/$name#egg=$name
+ INSTALLED_APPS += ["armstrong.apps.related_content", ]
+
+Once installed, you have to run either ``syncdb``, or ``migrate`` if you are
+using `South`_.
+
+.. _pip: http://www.pip-installer.org/
+.. _South: http://south.aeracode.org/
Contributing
@@ -76,7 +87,7 @@ State of Project
Armstrong is an open-source news platform that is freely available to any
organization. It is the result of a collaboration between the `Texas Tribune`_
and `Bay Citizen`_, and a grant from the `John S. and James L. Knight
-Foundation`_. The first release is scheduled for June, 2011.
+Foundation`_.
To follow development, be sure to join the `Google Group`_.
@@ -92,7 +103,7 @@ probably looking for that.
License
-------
-Copyright 2011 Bay Citizen and Texas Tribune
+Copyright 2011-2012 Bay Citizen and Texas Tribune
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
View
21 armstrong/apps/related_content/fields.py
@@ -5,7 +5,7 @@
from armstrong.core.arm_wells.querysets import GenericForeignKeyQuerySet
from .models import RelatedContent
-from .managers import RelatedContentManager
+
class BoundRelatedContentAccessor(object):
def __init__(self, instance, model, from_field, to_field, *args, **kwargs):
@@ -21,7 +21,8 @@ def get_query_set_params(self):
for field in self.model._meta.virtual_fields:
if field.name == self.from_field:
self.params = {
- field.ct_field: ContentType.objects.get_for_model(self.instance).pk,
+ field.ct_field: ContentType.objects.get_for_model(
+ self.instance).pk,
field.fk_field: self.instance.pk
}
break
@@ -48,7 +49,8 @@ def __getitem__(self, index):
if isinstance(index, basestring):
return self.by_type(index)
else:
- raise IndexError("RelatedFields can only be filtered by related_type title")
+ raise IndexError("RelatedFields can only be filtered by "
+ "related_type title")
class NonAssignableError(RuntimeError):
@@ -56,7 +58,8 @@ class NonAssignableError(RuntimeError):
class RelatedM2MDescriptor(object):
- def __init__(self, model=RelatedContent, from_field="source_object", to_field="destination_object"):
+ def __init__(self, model=RelatedContent, from_field="source_object",
+ to_field="destination_object"):
self.model = model
self.from_field = from_field
self.to_field = to_field
@@ -70,11 +73,13 @@ def __get__(self, instance, cls=None):
)
def __set__(self, instance, value):
- raise NonAssignableError("RelatedFields cannot be used to assign RelatedContent objects, use a RelatedContentField")
+ raise NonAssignableError("RelatedFields cannot be used to assign "
+ " RelatedContent objects, use a RelatedContentField")
class RelatedObjectsField(object):
- def __init__(self, model=RelatedContent, from_field="source_object", to_field="destination_object"):
+ def __init__(self, model=RelatedContent, from_field="source_object",
+ to_field="destination_object"):
self.model = model
self.from_field = from_field
self.to_field = to_field
@@ -104,5 +109,7 @@ def __init__(self, **kwargs):
defaults.update(kwargs)
super(RelatedContentField, self).__init__(RelatedContent, **defaults)
+
from south.modelsinspector import add_ignored_fields
-add_ignored_fields(["^armstrong\.apps\.related_content\.fields\.RelatedContentField"])
+add_ignored_fields(
+ ["^armstrong\.apps\.related_content\.fields\.RelatedContentField"])
Something went wrong with that request. Please try again.