Package: armstrong.core.arm_wells
Provides the basic content well code necessary for scheduling and arranging
models inside Armstrong.You can use wells to change the order of content.  They are meant to be
combined with querysets to allow your users to control what appears first in a
list of content.UsageWells are one of the most powerful components in Armstrong; they are
fundamentally about the ordering and structuring of content.Frequently there are parts of the site that simply display the most recently
published stories that belong to some grouping (a section or tag for
instance), but when there are big stories, editorial staff wants to feature
them by placing them at the top. Wells allow editorial staff to pin stories
through the admin. The demo project uses a QuerysetBackedWellView to accomplish
this use case with the ‘front_page’ WellType.armstrong.core.arm_wellsprovides 3 primary objects to work with. The
highest level is a WellType, which is generally a specific location on your
site where you’d like to order content. Each WellType has a number of Well
objects. A Well object represents a specific ordering of content for that
WellType for a certain period of time. Every Well has a number of Node objects
each of which relates the Well to an object in the database through a
GenericForeignKey.Ordering Arbitrary ContentThe 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 ofarmstrong.core.arm_layoutwhich 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.SchedulingThe 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 QuerySetBackedWellViewWells 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 theQuerySetBackedWellView. 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 pageTo render a well we recommend using thearmstrong.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 CustomizationThe 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 fromarmstrong.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.Installation & ConfigurationYou can install the latest release ofarmstrong.core.arm_wellsusingpip:pip install armstrong.core.arm_wellsMake sure to addarmstrong.core.arm_wellsto yourINSTALLED_APPS.  You
can add this however you like.  This works as a copy-and-paste solution:INSTALLED_APPS += ["armstrong.core.arm_wells", ]Once installed, you have to run eithersyncdbormigrateif you are
usingSouth.Notearmstrong.core.arm_wellsrequires the packagedjango-reversionwhich does not support multiple versions of Django.  Because of this,
we can’t specify a version of django-reversion for you to use.  Please
consult thewiki pageto determine which version you should use.ContributingCreate something awesome – make the code better, add some functionality,
whatever (this is the hardest part).Fork itCreate a topic branch to house your changesGet all of your commits in the new topic branchSubmit apull requestState of ProjectArmstrong is an open-source news platform that is freely available to any
organization.  It is the result of a collaboration between theTexas TribuneandBay Citizen, and a grant from theJohn S. and James L. Knight
Foundation.To follow development, be sure to join theGoogle Group.armstrong.core.arm_wellsis part of theArmstrongproject.  You’re
probably looking for that.LicenseCopyright 2011-2012 Bay Citizen and Texas TribuneLicensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.