app/soc/views/sitemap/sidebar.py

   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 """Module contains sidebar related functions.
  18 """
  19
  20 __authors__ = [
  21     '"Sverre Rabbelier" <sverre@rabbelier.nl>',
  22   ]
  23
  24
  25 from soc.views import out_of_band
  26 from soc.views.helper import access
  27
  28
  29 SIDEBAR = []
  30
  31
  32 def addMenu(callback):
  33   """Adds a callback to the menu builder.
  34
  35   The callback should return a list of menu's when called.
  36   """
  37
  38   global SIDEBAR
  39   SIDEBAR.append(callback)
  40
  41 def getSidebar(request):
  42   """Constructs a sidebar for the specified request.
  43   """
  44
  45   sidebar = []
  46
  47   for callback in SIDEBAR:
  48     menus = callback(request)
  49
  50     for menu in (menus if menus else []):
  51       sidebar.append(menu)
  52
  53   return sidebar
  54
  55
  56 def getSidebarItems(params):
  57   """Retrieves a list of sidebar entries for this view.
  58
  59   Params usage:
  60     The params dictionary is provided to the menu_text's format.
  61
  62     sidebar: The sidebar value is returned directly if non-False
  63     sidebar_defaults: The sidebar_defaults are used to construct the
  64       sidebar items for this View. It is expected to be a tuple of
  65       three items, the item's url, it's menu_text, and it's
  66       access_type, see getSidebarMenus on how access_type is used.
  67     sidebar_additional: The sidebar_additional values are appended
  68       to the list of items verbatim, and should be in the format
  69       expected by getSidebarMenus.
  70
  71   Args:
  72     params: a dict with params for this View.
  73   """
  74
  75   # Return the found result
  76   if params['sidebar']:
  77     return params['sidebar']
  78
  79   # Construct defaults manualy
  80   defaults = params['sidebar_defaults']
  81
  82   result = []
  83
  84   for item in params['sidebar_additional']:
  85     result.append(item)
  86
  87   for url, menu_text, access_type in defaults:
  88     url = url % params['url_name'].lower()
  89     item = (url, menu_text % params, access_type)
  90     result.append(item)
  91
  92   return result
  93
  94
  95 def getSidebarMenu(request, items, params):
  96   """Returns an dictionary with one sidebar entry.
  97
  98   Items is expected to be a tuple with an url, a menu_text, and an
  99   access_type. The access_type is then passed to checkAccess, if it
 100   raises out_of_band.Error, the item will not be added.
 101
 102   Args:
 103     request: the django request object
 104     items: see above
 105     params: a dict with params for this View
 106
 107   Params usage:
 108     The params dictionary is passed as argument to getSidebarItems,
 109     see the docstring of getSidebarItems on how it uses it.
 110
 111     rights: The rights dictionary is used to check if the user has
 112       the required rights to see a sidebar item.
 113       See checkAccess for more details on how the rights dictionary
 114       is used to check access rights.
 115     sidebar_heading: The sidebar_heading value is used to set the
 116       heading variable in the result.
 117     name: The name value is used if sidebar_heading is not present.
 118
 119   Returns:
 120     A dictionary is returned with it's 'heading' value set as explained above.
 121     It's 'items' value is constructed by calling _getSidebarItems. It constists
 122     of dictionaries with a url and a title field.
 123   """
 124
 125   rights = params['rights']
 126
 127   submenus = []
 128
 129   for url, menu_text, access_type in items:
 130     try:
 131       access.checkAccess(access_type, request, rights)
 132       submenus.append({'url': url, 'title': menu_text})
 133     except out_of_band.Error:
 134       pass
 135
 136   return submenus
 137
 138
 139 def getSidebarMenus(request, params=None):
 140   """Constructs the default sidebar menu for a View.
 141
 142   Calls getSidebarItems to retrieve the items that should be in the
 143   menu. Then passes the result to getSidebarMenu. See the respective
 144   docstrings for an explanation on what they do.
 145
 146   Args:
 147     request: the django request object
 148     params: a dict with params for this View
 149   """
 150
 151   items = getSidebarItems(params)
 152   submenus = getSidebarMenu(request, items, params)
 153
 154   if not submenus:
 155     return
 156
 157   menu = {}
 158
 159   if 'sidebar_heading' not in params:
 160     params['sidebar_heading'] = params['name']
 161
 162   menu['heading'] = params['sidebar_heading']
 163   menu['items'] = submenus
 164
 165   menus = [menu]
 166
 167   return menus