armstrong.core.arm_wells 1.6.1

Ordering Arbitrary Content

The simplest way to use wells is with just one Well object associated with a WellType. Changing the content of that Well or how that content is ordered will immediately change what is displayed on the site.

The use of GenericForeignKeys to link Node objects to content gives you a lot of flexibility. Wells make it easy to feature data apps, videos, audio clips, photo galleries and liveblogs all in one well even if there is no common base class for all their object.

The challenge of laying out various content objects with different styling and fields spurred the development of armstrong.core.arm_layout which provides a framework for specifying named layouts for your various content objects.

By thinking of wells as just simple tools for ordering content, you’ll start seeing other places on your site where they’re a good fit. Anything that has objects in the database that the writing or editorial staff would like to reorder on the site is a good candidate for wells.

Scheduling

The other major aspect to Wells is scheduling. If the editorial staff wants to plan the front page for Thursday at 5pm, they can create a new Well with the ‘front_page’ WellType and the content they want displayed. By setting the new Well’s pub_date for 5pm Thursday, no action will need to be taken at that time, the site will just start using the new Well.

Similarly Well’s have an expires field if content should only be scheduled for a certain period of time and then revert to an earlier well. We recommend that every WellType have an empty Well object that never expires to provide a sane fallback.

The WellManager has a convenience method, get_current, that takes in a WellType name and fetches the Well associated with that WellType, has the most recent pub_date in the past and doesn’t have an expires in the past.

Using a QuerySetBackedWellView

Wells can also be backed by a queryset which will be used as a source of additional content after all items have been exhausted. Currently, this is not configurable via the admin, but can be easily accomplished by using the QuerySetBackedWellView. For example, in a urls.py:

url(r'^$', QuerySetBackedWellView.as_view(well_title='front_page',
                                          template_name="index.html",
                                          queryset=Article.published.all()),
        name='front_page'),
# get's the current 'front_page' well, backs it with Article.published.all()
# and renders the index.html page

To render a well we recommend using the armstrong.core.arm_layout module. This will allow simple templates to handle heterogenous content. For instance, to render every item in a well using the ‘standard’ layout:

{% load layout_helpers %}
{% for content in well.items %}
    {% render_model content 'standard' %}
{% endfor %}

Admin Customization

The admin view for modifying a well has been customized to provide a drag and drop interface for ordering Node’s. To add a Node to a well, use the VisualSearch box to first search for a ContentType and then for the title of the object you want to use. For instance, in the demo, type ‘art’ into the box which will provide ‘ARTICLE’, press enter and search for articles with ‘Perry’ in the title. The VisualSearch widget is from armstrong.hatband, which provides more information about customizing that process.

When a node is added, it displays simple (and not particularly helpful) information about it’s ContentType id and object id. It also sends a request to the server for the html result of a render_model call with the ‘preview’ name. This allows you to easily display the nodes in a manner similar to how those objects will display on the site.