root/cpsskins/branches/paris-sprint-2006/locations/README.txt

$Id$

=========
LOCATIONS
=========

Locations are used to store local site data in a central place.

Background
----------

By design, themes are stored entirely in a Theme Management Folder.

This has the following advantages:

- the application can run on virtually all zope-based platforms since the
  contact surface against the underlying application is limited to a single
  folder.

- themes can be designed and tested before the actual site exists.

- theme-related security policy is kept entirely separate from the
  application's own security policy.

- high performance since the data is directly available (no traversals, or
  complex catalog queries are necessary)

- the import and export of data is very straightforward (see cpsskins.setup.io)


The downsides are:

- all "local" information must also be stored in a central location.

- all locations used by the underlying application must be identifiable, and
  modifications must be monitored.


Design
------

We have to maintain a mapping between locations and some data.

We assume that objects are locatable, i.e. by knowing the object we can know its
location reliably.


Containment
...........

Given a location we can find the set of locations that are contained in it and
another set of locations that it contains.

Locations contained in a given location are called 'sublocations'.

Since we can't keep information about *all* the locations of a site we
must store some information about how locations and related to sublocations


Rules of inheritence
....................

The "standard" behaviour for locations is to follow some sort of inheritence,
i.e. what is true of a given location is also true of its sublocations.

This behaviour can be declined into various rules:

- what is true of a location applies only to the location itself

- what is true of a location applies only to its sublocations

- what is true of a location applies only to the parent location

- ...

For each rule we have a location, a scope and some data. The scope determines
the locations to which the rule applies.

In order to avoid conflicting statements we must assume that some rules
have precedence over others. To determine the order in which rules are to be
applied in a given location context we look for the nearest locations first.


Nearest location in a context
.............................

All location information will be looked up from a given context which can
considered as the sublocation of a nearest location.

For instance in the context of folder1/folder2/folder3/, among the following
locations:

 - /folder1/

 - /folder1/folder2/

the former is the nearest location, because the location context is contained
in it and because it is contained in all other locations.

We can sort locations as:

 /folder1/ > /folder1/folder2/ > /folder1/folder2/folder3/

 (with '>' meaning 'contains')

the rules associated with the location 'folder1' will shadow the rules
of associated with '/folder1/folder2/'

If no nearest locations can be found in a given context then no rules will be
applied, and the context will contain no local information.


Applying rules
..............

Rules are applied starting from the one that has the nearest location until
its scope covers the location context. The rule's data can then be associated
to the location context.

Implementation
--------------

We create 2 locations:

    >>> from cpsskins.locations import Location

    >>> l1 = Location(path=u'/f1/', data=u'd1')
    >>> l1
    <Location at /f1/>

    >>> l2 = Location(path=u'/f1/f2/', data=u'd1/2')
    >>> l2
    <Location at /f1/f2/>

to get the location's data, we call the location:

    >>> l1()
    u'd1'

    >>> l2()
    u'd1/2'

the two locations can be compared:

    >>> l1 == l2
    False

    >>> l1 > l2
    True

    >>> l2 < l1
    True

if two locations have a same path, they are equal:

    >>> lA = Location(path=u'/f1/f2/', data=u'A')
    >>> lB = Location(path=u'/f1/f2/', data=u'B')

    >>> lA == lB
    True

We create a location storage:

    >>> from cpsskins.storage.locations import LocationStorage
    >>> locations = LocationStorage()

we add the locations to the storage:

    >>> locations.add(l1)
    >>> locations.add(l2)

    >>> from pprint import pprint
    >>> pprint(dict(locations))
    {(u'', u'', u'', u'f1'): <Location at /f1/>,
     (u'', u'', u'', u'f1', u'f2'): <Location at /f1/f2/>}

we can obtain the list of locations with:

    >>> locations.getPaths()
    [(u'', u'f1'), (u'', u'f1', u'f2')]


now we want to find the location of '/f1/f2/f3':

    >>> locations.find(u'/f1/f2/f3/')
    <Location at /f1/f2/>

or get the location of '/f1/f2/'

    >>> locations.find(u'/f1/f2/')
    <Location at /f1/f2/>

or '/f1':

    >>> locations.find(u'/f1/')
    <Location at /f1/>

    >>> locations.find(u'/f2/') is None
    True

scopes
......

so far the locations that we have created did not specify any scope. By
default their scope was (0, 0), meaning:

- starting from the location's path to all sublocations

By specifying a scope we can restrict the paths covered by a location, for
instance:

    >>> l3 = Location(path=u'/f1/f3/', data=u'C', scope=(0, 1))
    >>> locations.add(l3)

    >>> l3
    <Location at /f1/f3/>

- the first element of the couple is the position starting from the location.
- the second element of the couple is the end position relative to the
  location. 1 is the level of the location, 2 is the level of immediate
  sublocation, 0 means no limit.

(0, 1) means that the 'l3' location at /f1/f3/ has a scope covering /f1/f3/
only.


    >>> locations.find(u'/f1/f3/')
    <Location at /f1/f3/>

    >>> locations.find(u'/f1/f3/f4/')
    <Location at /f1/>

    >>> locations.find(u'/f1/f3/f4/f5/')
    <Location at /f1/>


l4 has a scope (1, 0) covering all sublocations of '/f1/f4/'.

    >>> l4 = Location(path=u'/f1/f4/', data=u'D', scope=(1, 0))
    >>> locations.add(l4)

    >>> locations.find(u'/f1/f4/')
    <Location at /f1/>

    >>> locations.find(u'/f1/f4/f5/')
    <Location at /f1/f4/>

    >>> locations.find(u'/f1/f4/f5/f6/')
    <Location at /f1/f4/>

    >>> locations.find(u'/f1/f4/f5/f6/f7/')
    <Location at /f1/f4/>


l5 has a scope (1, 2) covering the immediate sublocations of '/f1/f5' only:

    >>> l5 = Location(path=u'/f1/f5/', data=u'E', scope=(1, 2))
    >>> locations.add(l5)

    >>> locations.find(u'/f1/f5/')
    <Location at /f1/>

    >>> locations.find(u'/f1/f5/f6/')
    <Location at /f1/f5/>

    >>> locations.find(u'/f1/f5/f6/f7/')
    <Location at /f1/>


l6 has a scope (2, 0) covering the '/f1/f6/' location's sublocations of level
2 or more:

    >>> l6 = Location(path=u'/f1/f6/', data=u'F', scope=(2, 0))
    >>> locations.add(l6)

    >>> locations.find(u'/f1/f6/')
    <Location at /f1/>

    >>> locations.find(u'/f1/f6/f7/')
    <Location at /f1/>

    >>> locations.find(u'/f1/f6/f7/f8/')
    <Location at /f1/f6/>

    >>> locations.find(u'/f1/f6/f7/f8/f9/')
    <Location at /f1/f6/>

    >>> locations.find(u'/f1/f6/f7/f8/f9/f10/')
    <Location at /f1/f6/>


namespaces
..........

Namespaces can be created by specifying a location root:

    >>> l7 = Location(path=u'/f1/', data=u'G', root=u'pages')
    >>> locations.add(l7)

    >>> locations.find(u'/f1/', root=u'pages')
    <Location at /f1/ for 'pages'>

    >>> l8 = Location(path=u'/f1/', data=u'H', root=u'engines')
    >>> locations.add(l8)

    >>> locations.find(u'/f1/', root=u'engines')
    <Location at /f1/ for 'engines'>

we get the list of roots with:

    >>> locations.getRoots()
    [u'', u'pages', u'engines']

we get the list of location paths with:

    >>> locations.getPaths(u'pages')
    [(u'', u'f1')]

or with:

    >>> locations.getPaths(u'engines')
    [(u'', u'f1')]


to obtain all the paths we use:

    >>> locations.getAllPaths() # doctest: +NORMALIZE_WHITESPACE
    [(u'', u'f1', u'f2', u''), (u'', u'f1', u'f3', u''),
     (u'', u'f1', u'f6', u''), (u'', u'f1', u''), (u'', u'f1', u'f4', u''),
     (u'', u'f1', u'f5', u'')]

view names
...........

View or method names can be included in paths:

if a location has a /f10/ path, all locations such as /f10/_____ will
match the location:

    >>> l10 = Location(path=u'/f10/', data=u'any')
    >>> locations.add(l10)

    >>> locations.find(u'/f10/edit.html')
    <Location at /f10/>

    >>> locations.find(u'/f10/view.html')
    <Location at /f10/>

but if we add a location where the method name is explicitly specified we
get that location instead:

    >>> l10b = Location(path=u'/f10/edit.html', data=u'edit')
    >>> locations.add(l10b)

    >>> locations.find(u'/f10/edit.html')
    <Location at /f10/edit.html>

    >>> locations.find(u'/f10/view.html')
    <Location at /f10/>


if only the method name is specified, all paths that have a method with that
name will match:

    >>> l11 = Location(path=u'view.html', data=u'view')
    >>> locations.add(l11)

    >>> locations.find(u'/f10/view.html')
    <Location at view.html>

    >>> locations.find(u'/f10/f11/view.html')
    <Location at view.html>


in order to register a location with only a method name as the path no other
location must have been registered with the same name already:

    >>> l12 = Location(path=u'edit.html', data=u'edit')
    >>> locations.add(l12) # doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    KeyError: u"The 'edit.html' method name is already registered ..."


we purge the entire storage:

    >>> locations.purge()

    >>> list(locations)
    []