Mercurial Repository: p/roundup/code: doc/customizing.txt comparison

comparison doc/customizing.txt @ 2915:7d97c75e7cba

more docs

author	Richard Jones <richard@users.sourceforge.net>
date	Tue, 16 Nov 2004 23:36:59 +0000
parents	c75a19894d3e
children	ad4fb8a14a97

comparison

equal deleted inserted replaced

-:c75a19894d3e
+:7d97c75e7cba
 ===================
 Customising Roundup
 ===================
-:Version: $Revision: 1.156 $
+:Version: $Revision: 1.157 $
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
 .. contents::
 The web interface is provided by the ``roundup.cgi.client`` module and
 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
 (``ZRoundup``  is broken, until further notice). In all cases, we
 determine which tracker is being accessed (the first part of the URL
 path inside the scope of the CGI handler) and pass control on to the
-tracker ``interfaces.Client`` class - which uses the ``Client`` class
+``roundup.cgi.client.Client`` class - which handles the rest of the
-from ``roundup.cgi.client`` - which handles the rest of the access
+access through its ``main()`` method. This means that you can do pretty
-through its ``main()`` method. This means that you can do pretty much
+much anything you want as a web interface to your tracker.
-anything you want as a web interface to your tracker.
 Repercussions of changing the tracker schema
 ---------------------------------------------
 - Also handle the ":queryname" variable and save off the query to the
 user's query list.
 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
-These classes are registered with ``roundup.cgi.client.Client`` which also
+These classes are registered with ``roundup.cgi.client.Client``. If you need
-happens to be available in your tracker instance as ``interfaces.Client``. So
+to define new actions, you may add them there (see `defining new
-if you need to define new actions, you may add them there (see `defining new
 web actions`_).
 Each action class also has a ``*permission*`` method which determines whether
 the action is permissible given the current user. The base permission checks
 are:
 url_quote       quote some text as safe for a URL (ie. space, %, ...)
 html_quote      quote some text as safe in HTML (ie. <, >, ...)
 =============== ========================================================
 You may add additional utility methods by writing them in your tracker
-``extensions`` directory and registering them with the templating system.
+``extensions`` directory and registering them with the templating system
+using ``instance.registerUtil`` (see `adding a time log to your issues`_ for
+an example of this).
 Batching
 ::::::::
 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 ``Action`` classes that get
+These are added to the tracker ``extensions`` directory and registered
-called by the the ``Client`` class.
+using ``instance.registerAction``.
+All the existing Actions are defined in ``roundup.cgi.actions``.
 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.
 Define the new action class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The action classes have the following interface::
+Create a new action class in your tracker's ``extensions`` directory, for
+example ``myaction.py``::
 class MyAction(Action):
 def handle(self):
 ''' Perform some action. No return value is required.
 '''
-The *self.client* attribute is an instance of your tracker ``instance.Client``
+The *self.client* attribute is an instance of ``roundup.cgi.client.Client``.
-class - thus it's mostly implemented by ``roundup.cgi.client.Client``. See the
+See the docstring of that class for details of what it can do.
-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.client.ok_message`` or ``self.client.error_message``
 Register the action class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-XXX update for new extensions setup (then search for interfaces.py and make
+The class is now written, but isn't available to the user until you register
-sure there's no examples that use the old style)
+it with the following code appended to your ``myaction.py`` file::
-The class is now written, but isn't available to the user until you add it to
+def init(instance):
-the ``instance.Client`` class ``actions`` variable, like so::
+instance.registerAction('myaction', myActionClass)
-actions = client.Client.actions + (
-('myaction', myActionClass),
-)
 This maps the action name "myaction" to the action class we defined.
 Use the new action
 ~~~~~~~~~~~~~~~~~~
 In your HTML form, add a hidden form element like so::
 added to it.
 4. We want to display a total of the time log times that have been
 accumulated for an issue. To do this, we'll need to actually write
 some Python code, since it's beyond the scope of PageTemplates to
-perform such calculations. We do this by adding a method to the
+perform such calculations. We do this by adding a module ``timespent.py``
-TemplatingUtils class in our tracker ``interfaces.py`` module::
+to the ``extensions`` directory in our tracker::
-class TemplatingUtils:
+def totalTimeSpent(times):
-''' Methods implemented on this class will be available to HTML
+''' Call me with a list of timelog items (which have an
-templates through the 'utils' variable.
+Interval "period" property)
 '''
-def totalTimeSpent(self, times):
+total = Interval('0d')
-''' Call me with a list of timelog items (which have an
+for time in times:
-Interval "period" property)
+total += time.period._value
-'''
+return total
-total = Interval('0d')
-for time in times:
+def init(instance):
-total += time.period._value
+instance.registerUtil('totalTimeSpent', totalTimeSpent)
-return total
+We will now be able to access the ``totalTimeSpent`` function via the
-XXX update this example for TemplatingUtils -> extensions
+``utils`` variable in our templates, as shown in the next step.
-Replace the ``pass`` line if one appears in your TemplatingUtils
-class. As indicated in the docstrings, we will be able to access the
-``totalTimeSpent`` method via the ``utils`` variable in our templates.
 5. Display the time log for an issue::
 <table class="otherinfo" tal:condition="context/times">
 <tr><th colspan="3" class="header">Time Log
 admin:aamrgyQfDFSHw
 Each user of Roundup must still have their information stored in the Roundup
 database - we just use the passwd file to check their password. To do this, we
 need to override the standard ``verifyPassword`` method defined in
-``roundup.cgi.actions.LoginAction`` and register the new class with our
+``roundup.cgi.actions.LoginAction`` and register the new class. The
-``Client`` class in the tracker home ``interfaces.py`` module::
+following is added as ``externapassword.py`` in the tracker ``extensions``
+directory::
 from roundup.cgi.actions import LoginAction
 class ExternalPasswordLoginAction(LoginAction):
 def verifyPassword(self, userid, password):
+'''Look through the file, line by line, looking for a
+name that matches.
+'''
 # get the user's username
 username = self.db.user.get(userid, 'username')
 # the passwords are stored in the "passwd.txt" file in the
 # tracker home
 return crypt.crypt(password, ent[1][:2]) == ent[1]
 # user doesn't exist in the file
 return 0
-class Client(client.Client):
+def init(instance):
-actions = (
+instance.registerAction('login', ExternalPasswordLoginAction)
-('login', ExternalPasswordLoginAction),
-) + client.Client.actions
+You should also remove the redundant password fields from the ``user.item``
-What this does is look through the file, line by line, looking for a
-name that matches.
-We also remove the redundant password fields from the ``user.item``
 template.
 Using a UN*X passwd file as the user database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ... the above section will only be displayed if the category is one
 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 a new ``Action`` class and insert hooks to those actions in
+those actions in a new ``Action`` class (see `defining new web actions`_)::
-the "actions" attribute on on the ``interfaces.Client`` class, like so (see
-`defining new web actions`_)::
+from roundup.cgi.actions import Action
 class Page1SubmitAction(Action):
 def handle(self):
 ''' Verify that the user has selected a category, and then move
 on to page 2.
 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 + (
+def init(instance):
-('page1_submit', Page1SubmitAction),
+instance.registerAction('page1_submit', Page1SubmitAction)
-)
 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).

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 2915:7d97c75e7cba