Feature/new articles

docs/howto/plugins.md

@@ -37,9 +37,10 @@ ICEkit also has a simpler `PublishableArticle` model, which implements a
 Publishable Fluent Contents model - ie it's a straightforward Django model
 that happens to have rich content and be publishable. This is useful for more
  normal Django collections-of-things, like Press Releases, People, Articles.
+
 It's common to have a collecton of items with a paired `AbstractLayoutPage`
-Page to list/navigate the collection. See the `icekit-press-releases`
-project for a worked example of this.
+Page to list/navigate the collection. See the `authors` app for a worked
+example of this.
 
 ### Adding help text to a Placeholder
 

docs/index.md

@@ -24,15 +24,20 @@ Add custom functionality to your site.
 * [Placeholders]
 * [Publishing]
 * [Page trees and mptt]
+* [Articles]
 * [Writing portable apps]
 
 
 # Apps for ICEkit
 ## Included apps, pagetypes and plugins
 
+  * Apps:
+      * `authors` - descriptions of site contributors
+
   * Page type plugins:
       * `layout_page` - integrates with our flexible layouts system.
       * `search_page` - integrates with [Haystack].
+      * `authors.page.AuthorListing` - a list of Authors
   * Modular content plugins:
       * `brightcove`
       * `child_pages`
@@ -88,6 +93,7 @@ team at [the Interaction Consortium]: [labs@interaction.net.au](mailto:labs@inte
 [Creating content plugins]: howto/plugins.md
 [Deploying ICEkit]: howto/deployment.md
 [Layouts]: topics/layouts.md
+[Articles]: topics/articles.md
 [Placeholders]: topics/placeholders.md
 [Publishing]: topics/publishing.md
 [Page trees and mptt]: topics/page-trees-and-mptt.md

docs/topics/articles.md

@@ -0,0 +1,184 @@
+# `Article`s and `ListingPage`s
+
+`Article`s are publishable content types that live in collections. Normally
+articles are mounted under a parent's URL.
+
+An example of an article is a Press Release, which would be mounted under a
+Press Release Listing Page. The Listing Page has the URL "/press" and thus all
+the Press Releases have the URL "/press/<slug>".
+
+## `ArticleBase`
+
+The `icekit.articles.models.ArticleBase` inherits `title`, `slug` and
+publishing fields, and each `ArticleBase` subclass implements some key
+functionality:
+
+1. **Links to parents.**
+In order for an Article to know its URL (which is based on a parent's URL), it
+should define a `parent` link, which is normally a link to a `ListingPage`.
+
+1. **A view.**
+If an Article is mounted under a `ListingPage` parent, the ListingPagePlugin
+will call `get_response(request, parent)` on the article, which should
+return the necessary `HttpResponse`. If the Article is a `fluent_contents`
+model, the view functions are implemented by `fluent_contents`.
+
+There is also a class `icekit.articles.models.PolymorphicArticleBase` which
+extends the Article class with django-polymorphic functionality, allowing
+you to define articles of different shapes and mount them under the same
+`parent` model.
+
+## `ListingPage`
+
+The `icekit.articles.models.ListingPage` model is a page type that requires
+`get_items()` and `get_visible_items()` to be defined in subclasses.
+When viewed, ListingPage lists the items returned by `get_items()`.
+`get_visible_items()` is necessary because an editor may wish to preview
+unpublished items (that aren't returned by `get_items()`)
+
+## Admins
+
+For normal Articles, inherit from `ArticleAdminBase`. For polymorphic articles,
+inherit from `PolymorphicArticleParentAdmin` and `PolymorphicArticleChildAdmin`
+as shown in the example below.
+
+## Bare-bones example
+
+The following defines a minimal rich content Article, mounted under a
+minimal `ArticleCategoryPage`.
+
+In `models.py`:
+
+    from django.db import models
+    from icekit.abstract_models import FluentFieldsMixin
+    from icekit.articles.abstract_models import ListingPage, ArticleBase
+
+
+    class ArticleCategoryPage(ListingPage):
+        def get_items(self):
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.published().filter(parent_id=unpublished_pk)
+
+        def get_visible_items(self):
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.visible().filter(parent_id=unpublished_pk)
+
+
+    class Article(ArticleBase, FluentFieldsMixin):
+        parent = models.ForeignKey(
+            ArticleCategoryPage,
+            limit_choices_to={'publishing_is_draft': True}
+        )
+
+In `admin.py`:
+
+    from django.contrib import admin
+    from icekit.admin import FluentLayoutsMixin
+    from icekit.articles.admin import ArticleAdminBase
+    from .models import Article
+
+
+    @admin.register(Article)
+    class ArticleAdmin(ArticleAdminBase, FluentLayoutsMixin):
+        pass
+
+In `page_type_plugins.py`:
+
+    from fluent_pages.extensions import page_type_pool
+    from icekit.page_types.layout_page.admin import LayoutPageAdmin
+    from icekit.articles.page_type_plugins import ListingPagePlugin
+    from .models import ArticleCategoryPage
+
+
+    @page_type_pool.register
+    class ArticleCategoryPagePlugin(ListingPagePlugin):
+        model = ArticleCategoryPage
+
+
+## Bare-bones polymorphic example
+
+The following defines a polymorphic structure of minimal rich content Article,
+and a zero-content (except title) `RedirectArticle`.
+
+In `models.py`:
+
+    from django.db import models
+    from django.http import HttpResponseRedirect
+    from fluent_pages.pagetypes.redirectnode.models import RedirectNode
+    from icekit.abstract_models import FluentFieldsMixin
+    from icekit.fields import ICEkitURLField
+    from icekit.articles.abstract_models import ListingPage, PolymorphicArticleBase
+    from django.utils.translation import ugettext_lazy as _
+
+
+    class ArticleCategoryPage(ListingPage):
+        def get_items(self):
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.published().filter(parent_id=unpublished_pk)
+
+        def get_visible_items(self):
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.visible().filter(parent_id=unpublished_pk)
+
+
+    class Article(PolymorphicArticleBase):
+        parent = models.ForeignKey(
+            ArticleCategoryPage,
+            limit_choices_to={'publishing_is_draft': True}
+        )
+
+    class LayoutArticle(Article, FluentFieldsMixin):
+        class Meta:
+            verbose_name = "Article"
+
+
+    class RedirectArticle(Article):
+        new_url = ICEkitURLField(
+            help_text=_('The URL to redirect to.')
+        )
+        redirect_type = models.IntegerField(
+            _("Redirect type"),
+            choices=RedirectNode.REDIRECT_TYPE_CHOICES,
+            default=302,
+            help_text=_(
+                "Use 'normal redirect' unless you want to transfer SEO ranking to the new page."
+            )
+        )
+
+        def get_response(self, request, *args, **kwargs):
+            response = HttpResponseRedirect(self.new_url)
+            response.status_code = self.redirect_type
+            return response
+
+        class Meta:
+            verbose_name = "Redirect"
+
+In `admin.py`:
+
+    from django.contrib import admin
+    from icekit.admin import FluentLayoutsMixin
+    from icekit.articles.admin import PolymorphicArticleParentAdmin, \
+        PolymorphicArticleChildAdmin
+    from .models import Article, LayoutArticle, RedirectArticle
+
+
+    class ArticleChildAdmin(PolymorphicArticleChildAdmin):
+        base_model = Article
+
+
+    class LayoutArticleAdmin(ArticleChildAdmin, FluentLayoutsMixin):
+        base_model=LayoutArticle
+
+
+    class RedirectArticleAdmin(ArticleChildAdmin):
+        base_model=RedirectArticle
+
+
+    @admin.register(Article)
+    class ArticleParentAdmin(PolymorphicArticleParentAdmin):
+        base_model = Article
+        child_models = ((LayoutArticle, LayoutArticleAdmin),
+                        (RedirectArticle, RedirectArticleAdmin),)
+
+
+Finally, `page_type_plugins.py` is identical to the non-polymorphic example above.

docs/topics/portable-apps.md

@@ -63,7 +63,7 @@ In the app whose label is being updated, make the following changes:
     with a deprecation warning.
 
   * Add a `db_table: {old app label}` option to all `CreateModel` operations in
-    existing migrations, if not already defined, giving the current app label
+    existing migrations, if not already defined, giving the previous app label
     as the value.
 
   * Run `manage.py makemigrations {app_label}`. Django will detect that the

icekit/articles/__init__.py

@@ -0,0 +1 @@
+default_app_config = '%s.apps.AppConfig' % __name__

icekit/articles/abstract_models.py

@@ -1,12 +1,12 @@
-from icekit.abstract_models import FluentFieldsMixin
+from urlparse import urljoin
+
+from django.template.response import TemplateResponse
+
 from icekit.publishing.models import PublishingModel
-from django.db import models
+from polymorphic.models import PolymorphicModel
 
-# TODO: this should ideally be in icekit.abstract_models, but doing so
-# creates circular import errors.
-class PublishableFluentModel(FluentFieldsMixin, PublishingModel):
-    class Meta:
-        abstract = True
+from icekit.page_types.layout_page.abstract_models import AbstractLayoutPage
+from django.db import models
 
 class TitleSlugMixin(models.Model):
     # TODO: this should perhaps become part of a wider ICEkit mixin that covers
@@ -22,12 +22,102 @@ def __unicode__(self):
         return self.title
 
 
-class PublishableArticle(PublishableFluentModel, TitleSlugMixin):
-    '''
-    Basic Article type (ie that forms the basis of independent collections of
-    publishable things).
-    '''
+class ListingPage(AbstractLayoutPage):
+    """
+    A Page type that serves lists of things. Good for
+    e.g. PressReleaseListingPage or ArticleCategoryPage.
+    """
+    class Meta:
+        abstract = True
+
+    def get_items(self):
+        """
+        Get the items that are listed on this page.
+        Remember that incoming relations will be on the draft version of
+        the page. Do something like this:
+
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.published().filter(parent_id=unpublished_pk)
+
+        Editors normally expect to only see published() items in a listing, not
+        visible() items, unless clearly marked as such.
+
+        :return: the items that are associated with this page
+        """
+        raise NotImplementedError(
+            "Please implement `get_items()` on your ListingPage model"
+        )
+
+
+    def get_visible_items(self):
+        """
+        Get all items that are associated with this page and can be previewed
+        by the user.
+        Again, incoming relations will be on the draft version of
+        the page. Do something like this:
+
+            unpublished_pk = self.get_draft().pk
+            return Article.objects.visible().filter(parent_id=unpublished_pk)
+
+        Editors normally expect to only see published() items in a listing, not
+        visible() items, unless clearly marked as such.
+
+        :return: the items that are associated with this page
+        """
+        raise NotImplementedError(
+            "Please implement `get_visible_items()` on your ListingPage model"
+        )
+
+class ArticleBase(PublishingModel, TitleSlugMixin):
+    """
+    Articles can be mounted into a publishable listing page,
+    which has the URL returned by `get_parent_url()`.
+
+    Subclasses should define a `parent` attribute, or override either
+    `get_parent_url()` or `get_absolute_url()`.
+
+    Subclasses should also define get_response for rendering itself, or
+    get_layout_template_name() in order to render Rich Content.
+    """
 
     class Meta:
         abstract = True
+        unique_together = (('slug', 'publishing_is_draft', 'parent'),)
+
+    def get_parent_url(self):
+        if not hasattr(self, 'parent'):
+            raise NotImplementedError("PublishableArticle subclasses need to implement `parent` or `get_parent_url`.")
 
+        parent = self.parent.get_published() or self.parent.get_draft()
+        return parent.get_absolute_url()
+
+    def get_absolute_url(self):
+        parent_url = self.get_parent_url()
+        return urljoin(parent_url, self.slug) + "/"
+
+    def is_suppressed_message(self):
+        if not self.parent.has_been_published:
+            return "This article's parent needs to be published before it " \
+                "can be viewed by the public"
+        return None
+
+    def get_response(self, request, parent, *args, **kwargs):
+        context = {
+            'page': self,
+            'title': self.title
+        }
+        try:
+            return TemplateResponse(
+                request,
+                self.get_layout_template_name(),
+                context
+            )
+        except AttributeError:
+            raise AttributeError("You need to define "
+                 "`get_layout_template_name()` on your `ArticleBase` model, "
+                 "or override `get_response()`")
+
+
+class PolymorphicArticleBase(PolymorphicModel, ArticleBase):
+    class Meta:
+        abstract = True