py_tasks_melange: comparison app/soc/views/models/base.py

equal deleted inserted replaced

-:45bc26f48090
+:e0bd276ffd82
 def __init__(self, params=None):
 """
 Args:
 params: This dictionary should be filled with the parameters
-specific to this entity, required fields are:
+specific to this entity. See the methods in this class on
-rights: This dictionary should be filled with the access check
+the fields it should contain, and how they are used.
-functions that should be called
-name: the name of the entity (names should have sentence-style caps)
-name_short: the short form name of the name ('org' vs 'organization')
-name_plural: the plural form of the name
-url_name: the name of the entity used in urls
-edit_form: the class of the Django form to be used when editing
-create_form: the class of the Django form to be used when creating
-edit_template: the Django template to be used for editing
-public_template: the Django template to be used as public page
-list_template: the Django template to be used as list page
-lists_template: the Django templates to search for the list page
-delete_redirect: the Django template to redirect to on delete
-create_redirect: the Django template to redirect to after creation
-save_message: the message to display when the entity is saved
-edit_params: the params to use when editing
-sidebar: the sidebar menu items for this view
-sidebar_defaults: a dictionary with defaults for the sidebar; each
-value in the dict is a two-tuple:
-(url_format,       # supplied a single positional url_name
-menu_text_format) # supplied the params dict
 """
 rights = {}
 rights['unspecified'] = []
 rights['any_access'] = [access.checkIsLoggedIn]
 )
 def public(self, request, page_name=None, params=None, **kwargs):
 """Displays the public page for the entity specified by **kwargs.
+Params usage:
+rights: The rights dictionary is used to check if the user has
+the required rights to view the public page for this entity.
+See checkAccess for more details on how the rights dictionary
+is used to check access rights.
+error_public: The error_public value is used as template when
+the key values (as defined by the page's url) do not
+correspond to an existing entity.
+name: The name value is used to set the entity_type in the
+context so that the template can refer to it.
+public_template: The public_template value is used as template
+to display the public page of the found entity.
 Args:
 request: the standard Django HTTP request object
 page_name: the page name displayed in templates as page and header title
 params: a dict with params for this View
 kwargs: the Key Fields for the specified entity
 """
 params = dicts.merge(params, self._params)
 try:
-self.checkAccess('public', request)
+self.checkAccess('public', request, rights=params['rights'])
 except out_of_band.Error, error:
 return error.response(request)
 # create default template context for use with any templates
 context = helper.responses.getUniversalContext(request)
 return helper.responses.respond(request, template, context)
 def create(self, request, page_name=None, params=None, **kwargs):
 """Displays the create page for this entity type.
+Params usage:
+The params dictionary is passed on to edit, see the docstring
+for edit on how it uses it.
 Args:
 request: the standard Django HTTP request object
 page_name: the page name displayed in templates as page and header title
 params: a dict with params for this View
 kwargs: not used for create()
 return self.edit(request, page_name=page_name, params=params,
 seed=kwargs, **empty_kwargs)
 def edit(self, request, page_name=None, params=None, seed=None, **kwargs):
 """Displays the edit page for the entity specified by **kwargs.
+Params usage:
+The params dictionary is passed on to either editGet or editPost
+depending on the method type of the request. See the docstring
+for editGet and editPost on how they use it.
+rights: The rights dictionary is used to check if the user has
+the required rights to edit (or create) a new entity.
+See checkAccess for more details on how the rights dictionary
+is used to check access rights.
+name: The name value is used to construct the message_fmt of the
+raised error when there key_values do not define an existing
+entity. See DEF_CREATE_NEW_ENTITY_MSG_FMT on how the name
+(and the lower() version of it) is used.
+missing_redirect: The missing_redirect value is also used to
+construct the message_fmt mentioned above.
+error_public: The error_public value is used as the template for
+the error response mentioned above.
 Args:
 request: the standard Django HTTP request object
 page_name: the page name displayed in templates as page and header title
 params: a dict with params for this View
 return self.editPost(request, entity, context, params)
 else:
 return self.editGet(request, entity, context, seed, params)
 def editPost(self, request, entity, context, params):
-"""Same as edit, but on POST.
+"""Processes POST requests for the specified entity
+Params usage:
+The params dictionary is passed to _constructResponse when the
+form is not valid (see edit_form and create_form below). See
+the docstring of _constructResponse on how it uses it.
+edit_form: The edit_form value is used as form when there is an
+existing entity. It is provided with with the request.POST
+dictionary on construction. The collectCleanedFields method
+is called with the newly constructed form. If the form is
+not valid, it is passed as argument to _constructResponse.
+create_form: The create_form value is used in a similar way to
+edit_form, only it is used when there is no existing entity.
+edit_redirect: The edit_redirect value is used as the first part
+of the url if the form was valid. The last part of the url is
+created using the getKeySuffix method of the _logic object.
+edit_params: The edit_params dictionary is used as argument to
+redirectToChangedSuffix, it will be appended to the url in the
+standard ?key=value format.
+Args:
+request: a django request object
+entity: the entity that will be modified or created, may be None
+context: the context dictionary that will be provided to Django
+params: a dict with params for this View
 """
 params = dicts.merge(params, self._params)
 if entity:
 return helper.responses.redirectToChangedSuffix(
 request, None, new_suffix,
 params=page_params)
 def editGet(self, request, entity, context, seed, params):
-"""Same as edit, but on GET.
+"""Processes GET requests for the specified entity
+Params usage:
+The params dictionary is passed to _constructResponse, see the
+docstring  of _constructResponse on how it uses it.
+save_message: The save_message list is used as argument to
+getSingleIndexedParamValue when an existing entity was saved.
+edit_form: The edit_form is used as form if there is an existing
+entity. The existing entity is passed as instance to it on
+construction. If key_name is part of it's fields it will be
+set to the entity's key().name() value. It is also passed as
+argument to the _editGet method. See the docstring for
+_editGet on how it uses it.
+create_form: The create_form is used as form if there was no
+existing entity. If the seed argument is present, it is passed
+as the 'initial' argument on construction. Otherwise, it is
+called with no arguments.
+Args:
+request: the django request object
+entity: the entity that will be edited, may be None
+context: the context dictionary that will be provided to django
+seed: if no entity is provided, the initial values for the new entity
+params: a dict with paras for this View
 """
 params = dicts.merge(params, self._params)
 suffix = self._logic.getKeySuffix(entity)
 request, self.DEF_SUBMIT_MSG_PARAM_NAME,
 values=params['save_message'])
 # populate form with the existing entity
 form = params['edit_form'](instance=entity)
 if 'key_name' in form.fields:
 form.fields['key_name'].initial = entity.key().name()
 self._editGet(request, entity, form)
 else:
 if seed:
 self._editSeed(request, seed)
 form = params['create_form'](initial=seed)
 Args:
 request: the standard Django HTTP request object
 page_name: the page name displayed in templates as page and header title
 params: a dict with params for this View
 filter: a dict for the properties that the entities should have
+Params usage:
+The params dictionary is passed as argument to getListContent in
+the soc.views.helper.list module. See the docstring for
+getListContent on how it uses it.
+The params dictionary is also passed as argument to the _list
+method. See the docstring for _list on how it uses it.
+rights: The rights dictionary is used to check if the user has
+the required rights to list all entities of this View's type.
+See checkAccess for more details on how the rights dictionary
+is used to check access rights.
 """
 params = dicts.merge(params, self._params)
 try:
-self.checkAccess('list', request)
+self.checkAccess('list', request, rights=params['rights'])
 except out_of_band.Error, error:
 return error.response(request)
 content = helper.lists.getListContent(request, params, self._logic, filter)
 contents = [content]
 Args:
 request: the standard Django HTTP request object
 params: a dict with params for this View
 contents: a list of content dicts
 page_name: the page name displayed in templates as page and header title
+Params usage:
+name: The name value is used to set the entity_type in the
+context so that the template can refer to it.
+name_plural: The name_plural value is used to set
+the entity_type_plural value in the context so that the
+template can refer to it.
+list_template: The list_template value is used as template for
+to display the list of all entities for this View.
 """
 context = helper.responses.getUniversalContext(request)
 context['page_name'] = page_name
 context['list'] = soc.logic.lists.Lists(contents)
 Args:
 request: the standard Django HTTP request object
 page_name: the page name displayed in templates as page and header title
 params: a dict with params for this View
 kwargs: The Key Fields for the specified entity
+Params usage:
+rights: The rights dictionary is used to check if the user has
+the required rights to delete the specified entity.
+See checkAccess for more details on how the rights dictionary
+is used to check access rights.
+name: used in the same way as in edit(), see it's docstring for
+a more detailed explanation on how it is used.
+missing_redirect: see name
+error_edit: see name
+delete_redirect: The delete_redirect value is used as the url to
+redirect to after having successfully deleted the entity.
 """
 params = dicts.merge(params, self._params)
 try:
-self.checkAccess('delete', request)
+self.checkAccess('delete', request, rights=params['rights'])
 except out_of_band.Error, error:
 return error.response(request)
 # create default template context for use with any templates
 context = helper.responses.getUniversalContext(request)
 def _constructResponse(self, request, entity, context, form, params):
 """Updates the context and returns a response for the specified arguments.
 Args:
 request: the django request object
-entity: the entity that is used
+entity: the entity that is used and set in the context
 context: the context to be used
-form: the form that will be used
+form: the form that will be used and set in the context
 params: a dict with params for this View
+Params usage:
+name: The name_plural value is used to set the entity_type
+value in the context so that the template can refer to it.
+name_plural: same as name, but used to set entity_type_plural
+name_short: same as name, but used to set entity_type_short
+url_name: same as name, but used to set entity_type_url
+edit_template: The edit_template value is used as template when
+there is an existing entity to display the edit page for the
+specified entity.
+create_template: similar to edit_template, but is used when
+there is no existing entity.
 """
 suffix = self._logic.getKeySuffix(entity)
 context['form'] = form
 """Runs all the defined checks for the specified type
 Args:
 access_type: the type of request (such as 'list' or 'edit')
 request: the Django request object
+rights: A dictionary containing access check functions
+Rights usage: The rights dictionary is used to check if the
+current user is allowed to view the page specified. The
+functions defined in this dictionary are always called with the
+django request object as argument.
+On any request, regardless of what type, the functions in the
+'any_access' value are called.
+If the specified type is not in the rights dictionary, all the
+functions in the 'unspecified' value are called.
+When the specified type _is_ in the rights dictionary, all the
+functions in that access_type's value are called.
 Returns:
 True: If all the required access checks have been made successfully
 False: If a check failed, in this case self._response will contain
 the response provided by the failed access check.
 for check in rights['any_access']:
 check(request)
 if access_type not in rights:
 for check in rights['unspecified']:
-# No checks defined, so do the 'generic check' and bail out
+# No checks defined, so do the 'generic' checks and bail out
 check(request)
 return
 for check in rights[access_type]:
 check(request)
 def collectCleanedFields(self, form):
 """Collects all cleaned fields and returns them with the key_name.
 Args:
 form: The form from which the cleaned fields should be collected
+Returns: All the fields that are in the form's cleaned_data
+property are returned. If there is a key_name field, it is not
+included in the returend fields, instead, it is returned as the
+first element in the returned tuple. If no key_name field is
+present, None is returned as first value instead.
 """
 fields = {}
 key_name = None
 fields[field] = value
 return key_name, fields
 def getKeyFieldsPattern(self, params):
-"""
+"""Returns the Django pattern for this View's entity
+Params usage:
+key_fields_prefix: The key_fields_prefix value is used as the
+first part of the returned pattern.
 """
 names = self._logic.getKeyFieldNames()
 patterns = params['key_fields_prefix']
 result = '/'.join(patterns)
 return result
 def _getSidebarItems(self, params):
-"""Retrieves a list of sidebar entries for this view from self._params.
+"""Retrieves a list of sidebar entries for this view
-If params['sidebar'] is None default entries will be constructed
+Params usage:
+The params dictionary is provided to the menu_text's format.
+sidebar: The sidebar value is returned directly if non-False
+sidebar_defaults: The sidebar_defaults are used to construct the
+sidebar items for this View. It is expected to be a tuple of
+three items, the item's url, it's menu_text, and it's
+access_type, see getSidebarLinks on how access_type is used.
+sidebar_additional: The sidebar_additional values are appended
+to the list of items verbatim, and should be in the format
+expected by getSidebarLinks.
+Args:
+params: a dict with params for this View.
 """
 # Return the found result
 if params['sidebar']:
 return params['sidebar']
 return result
 def getSidebarLinks(self, request, params=None):
 """Returns an dictionary with one sidebar entry.
-Args:
+Calls _getSidebarItems to retrieve the items that should be in the
-params: see __init__
+menu. Expected is a tuple with an url, a menu_text, and an
+access_type. The access_type is then passed to checkAccess, if it
+raises out_of_band.Error, the item will not be added.
+Args:
+request: the django request object
+params: a dict with params for this View
+Params usage:
+The params dictionary is passed as argument to _getSidebarItems,
+see the docstring of _getSidebarItems on how it uses it.
+rights: The rights dictionary is used to check if the user has
+the required rights to see a sidebar item.
+See checkAccess for more details on how the rights dictionary
+is used to check access rights.
+sidebar_heading: The sidebar_heading value is used to set the
+heading variable in the result.
+name: The name value is used if sidebar_heading is not present.
+Returns: A dictionary is returned with it's 'heading' value set
+as explained above. It's 'items' value is constructed by
+calling _getSidebarItems. It constists of dictionaries with a
+url and a title field.
 """
 params = dicts.merge(params, self._params)
 rights = params['rights']
 def getDjangoURLPatterns(self, params=None):
 """Retrieves a list of sidebar entries for this view from self._params.
 If self._params['django_patterns'] is None default entries will be
 constructed.
+Params usage:
+The params dictionary is passed to the getKeyFieldsPatterns
+method, see it's docstring on how it is used.
+django_patterns: The django_patterns value is returned directly
+if it is non-False.
+django_patterns_defaults: The dajngo_patterns_defaults value is
+used to construct the url patterns. It is expected to be a
+list of tuples. The tuples should contain an url, a module
+name, and the name of the url. The name is used as the
+page_name passed as keyword argument, but also as the name
+by which the url is known to Django internally.
+url_name: The url_name argument is passed as argument to each
+url, together with the link_id pattern, the link_id core
+pattern, and the key fields for this View.
+Args:
+params: a dict with params for this View
 """
 params = dicts.merge(params, self._params)
 # Return the found result

changeset 610	e0bd276ffd82
parent 606	65d35584ee31
child 611	2ec30182e5f1