1 #!/usr/bin/python2.5

     2 #

     3 # Copyright 2008 the Melange authors.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 # 

     9 #   http://www.apache.org/licenses/LICENSE-2.0

    10 # 

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """This module contains the Linkable base class Model."""

    18 

    19 __authors__ = [

    20   '"Todd Larsen" <tlarsen@google.com>',

    21 ]

    22 

    23 

    24 from google.appengine.ext import db

    25 

    26 from django.utils.translation import ugettext_lazy

    27 

    28 from soc.models import base

    29 

    30 

    31 class Linkable(base.ModelWithFieldAttributes):

    32   """A base class for Model classes that are "linkable".

    33   

    34   Many entities in Melange are identified by a "link path" that is formed

    35   by two components:  a "link scope" and a "link ID".

    36   

    37   The link scope is a reference to another Linkable entity, but its exact

    38   usage varies depending on:

    39   

    40    * the Model type of the entity

    41    * the "ownership" of the entity

    42    

    43   This scope represents the "context" of the entity and is *not* user-

    44   editable (site Developers will be able to *carefully* edit the scope

    45   of a Linkable entity, but implementing this will be tricky).

    46   

    47   Appended to this "link path prefix" generated from the transitive

    48   closure of the link scopes is a link ID.  Unlike the rest of the link

    49   path, this ID, which must be unique within the scope defined by the link

    50   path, is *not* determined by context and *is* supplied by the user.

    51   

    52   For example, a Document containing containing the FAQs for the

    53   Apache Software Foundation participation in GSoC 2009 program sponsored

    54   by Google could be given a link ID by the Apache organization

    55   administrator of "faqs", but the rest of the link path would be

    56   determined by the transitive closure of the scopes of the Document:

    57   

    58     google/gsoc2009/asf/faqs

    59       ^       ^      ^   ^

    60       |       |      |   +---------  link ID assigned by Apache admin

    61       |       |      |

    62       |       |      +-------------  Apache org link ID (immutable)

    63       |       |

    64       |       +--------------------  GSoC 2009 program link ID (immutable)

    65       |

    66       +----------------------------  Google sponsor link ID (immutable)

    67       

    68   For many entities, link IDs, once specified, are immutable, since

    69   changing them can break bookmarked URLs.  Changing the link IDs of

    70   "leaf" entities (such as the Document in the example above) could

    71   be allowed. 

    72   """

    73   

    74   id = db.StringProperty(required=True,

    75       verbose_name=ugettext_lazy('Link ID'))

    76   id.help_text = ugettext_lazy(

    77       '"ID" used in URLs.'

    78       ' Lower ASCII characters, digits, and underscores only.')

    79 

    80   scope = db.SelfReferenceProperty(required=False,

    81       collection_name='links', verbose_name=ugettext_lazy('Link Scope'))

    82   scope.help_text = ugettext_lazy(

    83       'Reference to another Linkable entity that defines the "scope" of'

    84       ' this Linkable entity.')