From: jlgijsbers Date: Sat, 14 Feb 2004 11:28:07 +0000 (+0000) Subject: Update documentation for the client.py split and add an upgrade notice. X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=11ce0e2b93643a0ae14df1c4dcf0409923a45d2b;p=roundup.git Update documentation for the client.py split and add an upgrade notice. git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@2084 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/customizing.txt b/doc/customizing.txt index f7d1958..18a7f99 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,7 @@ Customising Roundup =================== -:Version: $Revision: 1.113 $ +:Version: $Revision: 1.114 $ .. This document borrows from the ZopeBook section on ZPT. The original is at: http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx @@ -2077,12 +2077,12 @@ templating through the "journal" method of the item*:: Defining new web actions ------------------------ -You may define new actions to be triggered by the ``@action`` form -variable. These are added to the tracker ``interfaces.py`` as methods on -the ``Client`` class. +You may define new actions to be triggered by the ``@action`` form variable. +These are added to the tracker ``interfaces.py`` as ``Action`` classes that get +called by the the ``Client`` class. -Adding action methods takes three steps; first you `define the new -action method`_, then you `register the action method`_ with the cgi +Adding action classes takes three steps; first you `define the new +action class`_, then you `register the action class`_ with the cgi interface so it may be triggered by the ``@action`` form variable. Finally you `use the new action`_ in your HTML form. @@ -2090,41 +2090,41 @@ See "`setting up a "wizard" (or "druid") for controlled adding of issues`_" for an example. -Define the new action method +Define the new action class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The action methods have the following interface:: +The action classes have the following interface:: - def myActionMethod(self): - ''' Perform some action. No return value is required. - ''' + class MyAction(Action): + def handle(self): + ''' Perform some action. No return value is required. + ''' -The *self* argument is an instance of your tracker ``instance.Client`` +The *self.client* attribute is an instance of your tracker ``instance.Client`` class - thus it's mostly implemented by ``roundup.cgi.Client``. See the docstring of that class for details of what it can do. The method will typically check the ``self.form`` variable's contents. It may then: -- add information to ``self.ok_message`` or ``self.error_message`` -- change the ``self.template`` variable to alter what the user will see +- add information to ``self.client.ok_message`` or ``self.client.error_message`` +- change the ``self.client.template`` variable to alter what the user will see next - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect - exceptions + exceptions (import them from roundup.cgi.exceptions) -Register the action method +Register the action class ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The method is now written, but isn't available to the user until you add -it to the `instance.Client`` class ``actions`` variable, like so:: +The class is now written, but isn't available to the user until you add it to +the ``instance.Client`` class ``actions`` variable, like so:: - actions = client.Class.actions + ( - ('myaction', 'myActionMethod'), + actions = client.Client.actions + ( + ('myaction', myActionClass), ) -This maps the action name "myaction" to the action method we defined. - +This maps the action name "myaction" to the action class we defined. Use the new action ~~~~~~~~~~~~~~~~~~ @@ -2748,7 +2748,7 @@ Setting up a "wizard" (or "druid") for controlled adding of issues
- + Category: @@ -2772,7 +2772,7 @@ Setting up a "wizard" (or "druid") for controlled adding of issues Note that later in the form, I test the value of "cat" include form - elements that are appropriate. For example:: + elements that are appropriate. For exsample:: @@ -2789,26 +2789,27 @@ Setting up a "wizard" (or "druid") for controlled adding of issues of 6, 10, 13, 14, 15, 16 or 17. 3. Determine what actions need to be taken between the pages - these are - usually to validate user choices and determine what page is next. Now - encode those actions in methods on the ``interfaces.Client`` class - and insert hooks to those actions in the "actions" attribute on that - class, like so:: + usually to validate user choices and determine what page is next. Now encode + those actions in a new ``Action`` class and insert hooks to those actions in + the "actions" attribute on on the ``interfaces.Client`` class, like so (see + `defining new web actions`_):: + + class Page1SubmitAction(Action): + def handle(self): + ''' Verify that the user has selected a category, and then move + on to page 2. + ''' + category = self.form['category'].value + if category == '-1': + self.error_message.append('You must select a category of report') + return + # everything's ok, move on to the next page + self.template = 'add_page2' actions = client.Client.actions + ( - ('page1_submit', 'page1SubmitAction'), + ('page1_submit', Page1SubmitAction), ) - def page1SubmitAction(self): - ''' Verify that the user has selected a category, and then move - on to page 2. - ''' - category = self.form['category'].value - if category == '-1': - self.error_message.append('You must select a category of report') - return - # everything's ok, move on to the next page - self.template = 'add_page2' - 4. Use the usual "new" action as the ``@action`` on the final page, and you're done (the standard context/submit method can do this for you). diff --git a/doc/upgrading.txt b/doc/upgrading.txt index 31b30ca..eaef20c 100644 --- a/doc/upgrading.txt +++ b/doc/upgrading.txt @@ -3,7 +3,7 @@ Upgrading to newer versions of Roundup ====================================== Please read each section carefully and edit your tracker home files -accordingly. Note that there is informaiton about upgrade procedures in the +accordingly. Note that there is information about upgrade procedures in the `administration guide`_. .. contents:: @@ -11,6 +11,17 @@ accordingly. Note that there is informaiton about upgrade procedures in the Migrating from 0.6 to 0.7 ========================= +0.7.0 Extending the cgi interface +--------------------------------- + +Before 0.7.0 adding or extending web actions was done by overriding or adding +methods on the Client class. Though this approach still works to provide +backwards compatibility, it is recommended you upgrade to the new approach, as +described in the `Defining new web actions`__ section of the customization +documentation. + +__ customizing.html#defining-new-web-actions + 0.7.0 Getting the current user id ---------------------------------