ztm.topiclisting must cover many overlapping use-cases.

Listings are a convoluted pieces of functionality.

Configuring a topiclisting
==========================
Configuration can be stored multiple places and bound to a topic in different
ways.

Following types versus one-offs.

Model
-----

Displaylists are instances of `ztm.topiclisting.psis.displaylisting`[#psi1]_.
You need one for each kind of displaylist.

.. rubric:: Footnotes

..  [#psi1] http://psi.ztmproject.org/ztm.topiclisting/displaylisting

Usecases
--------
* Frontpages
* Topic list to override a query.
* Tied to an interface, tied to a subject identifier


Queries
-------
Associated topics. When adding and removing to this list you may create or remove associations.

Keys
----
'listing.size'
'queries.query'


Source
------
If you want the configuration to be version controlled and created on startup you need to bind the lis

Each displaylist should have

  >>> Listing()
  >>> 
  >>> 

                              , 'query.queries': [[(AssociatedTopicsQuery({ 'associationtype': 'http://example.com/psis/dummytype1'
                                                              , 'roletype': 'http://example.com/psis/dummytype2'
                                                              , 'otherroletype': 'http://example.com/psis/dummytype3'
                                                              , 'sort': 'date'
                                                              , 'reversed': False
                                                              }))]]
  utility.registerList( 'dummytype1'
                      , psis.displaylisting
                      , topicTypeSI
                      , { 'title': u'Sometitle'
                        , 'sort': 'date'
                        , 'reversed': True
                        , 'listing.size':5
                        }
                      )



Manually build list
-------------------
This is the simplest setup. You just create a list and start adding the topics
you want to appear in it.

.. note::

  The list itself is only stored in an occurrence and is not currently portable
  to other topic map engines.


Associated topics
-----------------
A common usecase is 

A query
-------


 /archive # Default view for 
 /archive/<prettyname>  # Overridable/the id of the type.
 /archive/<occurrence_serial>
 /listing # Default view if there is only one.


 listingtopic/ # Default view is overriden by ztm.publishing.topicview
 listingtopic/archive # Archive of topic
 listingtopic/topiclisting # Archive of topic

#TODO Must support disabling listview and archive...archive

Search is updated to use the default ztm.topicmaps interface.

RESTful interface:

 GET  <listing>                   # Default view
 GET  <listing>/slot/             # All the slots
 GET  <listing>/slot/<position>   # A particular slot, 4xx if out of bounds
 PUT  <listing>/slot/             # New list.
 POST <listing>/slot/             # Add and configure new slot
 PUT  <listing>/slot/<position>   # Configure a slot
 
 GET  <listing>/hidden            # list of hidden topics
 GET  <listing>/pinned            # list of pinned topics
 GET  <listing>/configuration     # Code to configure a slot

 Moving a topic from one slot to another is done by putting to a new position:

 DELETE <listing>/slot/<position> # Empties the slot?

{ 'topic': serial|itemidentifier|subjectidentifier|url
, 'configuration': []
}

{ 'type': selector
, 'choices': [] # Can this be dynamic?
, 'default': 'line'
}