# HG changeset patch # User Sverre Rabbelier # Date 1227979252 0 # Node ID e0bd276ffd82e1f995c379984627ff19b2d5d3c6 # Parent 45bc26f48090c6638c4d68b277fc1f9bb07f16f7 Documented params usage in soc/views/models/base.py Patch by: Sverre Rabbelier diff -r 45bc26f48090 -r e0bd276ffd82 app/soc/views/models/base.py --- a/app/soc/views/models/base.py Sat Nov 29 14:41:43 2008 +0000 +++ b/app/soc/views/models/base.py Sat Nov 29 17:20:52 2008 +0000 @@ -66,28 +66,8 @@ Args: params: This dictionary should be filled with the parameters - specific to this entity, required fields are: - rights: This dictionary should be filled with the access check - 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 + specific to this entity. See the methods in this class on + the fields it should contain, and how they are used. """ rights = {} @@ -211,6 +191,19 @@ 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 @@ -221,7 +214,7 @@ 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) @@ -253,6 +246,10 @@ 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 @@ -278,6 +275,24 @@ 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 @@ -316,7 +331,32 @@ 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) @@ -353,7 +393,31 @@ 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) @@ -374,8 +438,10 @@ # 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: @@ -394,12 +460,24 @@ 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) @@ -416,6 +494,15 @@ 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) @@ -437,12 +524,24 @@ 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) @@ -533,10 +632,22 @@ 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) @@ -562,6 +673,18 @@ 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 @@ -577,7 +700,7 @@ 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 @@ -589,6 +712,12 @@ 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 = {} @@ -603,7 +732,11 @@ 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() @@ -617,9 +750,22 @@ 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 + + Params usage: + The params dictionary is provided to the menu_text's format. - If params['sidebar'] is None default entries will be constructed + 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 @@ -644,8 +790,31 @@ def getSidebarLinks(self, request, params=None): """Returns an dictionary with one sidebar entry. + Calls _getSidebarItems to retrieve the items that should be in the + 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: - params: see __init__ + 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) @@ -678,6 +847,24 @@ 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)