root/cpsskins/branches/jmo-perspectives/browser/negotiation/README.txt

===========
NEGOTIATION
===========

The negotiation process takes place between the client (browser) and the server
to determine the parameters required for delivering a rendered page to the
user.

The negotiation strategy is fixed and is deterministic, which means that under
the same premises the outcome of the negotiation will always be the same.

In particular, the renderer needs to know:

- what *theme* to use

- what *page* to render

- which rendering *engine* to use

- from which *perspective* to render the page


Hence the entire negotiation process is split into 4 phases:

1) the 'theme negotiation' phase

2) the 'page negotiation' phase

3) the 'engine negotiation' phase

4) the 'perspective negotiation' phase


By design, the phases are independent of one another. To each phase
corresponds a *negotiation chain*.


Negotiation chains
------------------

A negotiation *chain* is a series of steps under which the client requests an
object from the server using various schemes (passing a URL parameter,
looking for a cookie variable, looking for a session or request variable, ...).

For each step, the server either responds with the requested object if it
is available or with nothing.

The first available object will be the result of the negotiation for that
particular chain.


Negotiation strategy
--------------------

A negotiation *strategy* is a set of negotiation chains.

Each *theme management folder* can have its own negotiation strategy.


Test setup:

    >>> from zope.publisher.browser import TestRequest
    >>> request = TestRequest()

    >>> root = getRootFolder()
    >>> from cpsskins.tests.setup import addThemeSkeleton, addThemeManager
    >>> manager = addThemeManager(root)
    >>> theme1 = addThemeSkeleton(manager, u'Theme 1')
    >>> theme2 = addThemeSkeleton(manager, u'Theme 2')
    >>> theme3 = addThemeSkeleton(manager, u'Theme 3')

    >>> from zope.app import zapi
    >>> from cpsskins.browser.negotiation.interfaces import INegotiation
    >>> negotiation = zapi.getMultiAdapter((root, request), INegotiation,
    ...                                    'negotiation')

Themes
------

To obtain the theme as a result of the negotiation the 'getTheme' method is
used.

If nothing is specified, the default theme is returned:

    >>> theme = negotiation.getTheme()
    >>> theme.name
    'Theme'

    >>> manager.isDefault(theme)
    True


The theme's name can be specified in the URL, by writing ...?theme=Theme-2

    >>> request.form[u'theme'] = u'Theme-2'
    >>> theme = negotiation.getTheme()
    >>> theme.name
    u'Theme-2'

    >>> del request.form[u'theme']


The theme's name can also be specified in a cookie:

    >>> request.response.setCookie('cpsskins_theme', u'Theme-3')
    >>> theme = negotiation.getTheme()

    TODO

    >>> request.response.expireCookie('cpsskins_theme')