1���Introduction

Quixote can be viewed as a simple, easy, quick way to develop front-ends or user interfaces to complex back-end applications and resources. The fact that these applications are delivered via HTTP and may be used remotely is an additional advantage.

This document and the attached sample files are intended to help you construct a Quixote application that connects the user to back-end resources. Quixote turns out to be a very quick and easy way to construct front ends and user interfaces for this style of application. And, for no extra cost, the application you construct can be used remotely, too.

This skeleton will help you to quickly implement a Quixote application that connects to the following back-end resources:

• PostgreSQL using pyPgSQL. But, if you use MySQL and an implementation for the Python DB API, then switching to MySQL and an implementation of the Python DB API for MySQL should be trivial. More information about implementations of the Python DB API is here: http://python.org/sigs/db-sig/.
• XML-RPC using xmlrpclib from the Python standard library.
• SOAP using SOAPpy. It's available from http://pywebsvcs.sourceforge.net/.
• HTTP using several screen scraping techniques to extract data. You can find more information on these techniques here: http://www.rexx.com/~dkuhlman/quixote_htmlscraping.html.

A distribution file containing the skeleton files and this documentation is available here: http://www.rexx.com/~dkuhlman/quixote_skeleton.zip.

Note that my testing is done with Quixote-0.7a3.

2���Install the Skeleton Files

You can obtain the distribution containing the skeleton files at: http://www.rexx.com/~dkuhlman/quixote_skeleton.zip.

Then, follow these steps:

• Create a directory in which to place the skeleton files, for example:

  mkdir Skeleton
  cd Skeleton
  

• Unroll the skeleton files. Something like the following should do it:

  unzip quixote_skeleton.zip
  

• Rename the directory containing the sample files. In what follows, I'm going to explain things as if you had renamed it to "myapp", which, on a UNIX/Linux system, you would do as follows:

  mv skeleton myapp
  

• Add the directory in which you unrolled the sample files to your PYTHONPATH. For example, if, when you unrolled the sample files, you created /aaaa/bbbb/skeleton, then you will need something like the following (or the equivalent):

  export PYTHONPATH=/aaaa/bbbb:$PYTHONPATH
  

The organization of the files in the skeleton is as follows:

skeleton/scripts/

Scripts for starting, restarting, and stoping the application.

skeleton/ui/

The user interface.

skeleton/ui/__init__.py

Parses and handles the URL. Also, exposes static files and directories.

skeleton/ui/servicesui.ptl

Implements the user interface.

skeleton/services/*.py

Implements the model. Provides logic and access to the back-end resources.

skeleton/xmlrpcserver.py

A sample XML-RPC server. It is used by servicesui.ServicesUI.do_temperature.

skeleton/soapserver.py

A sample SOAP server. It is used by servicesui.ServicesUI.do_structures.

3���Modifying the Server Script

The sample files include scripts for the following servers:

• Medusa -- server-medusa.py.
• Apache/SCGI -- server-scgi.py

4���Modifying the Application

In file myapp/ui/__init__.py, do the following:

• Change all occurances of "skeleton" to "myapp" or whatever you have named your applicaton.
• There is code in this file that exposes several static files and directories. Uncomment or comment out this code and modify it as needed.
• This file exposes several classes in myapp/ui/servicesui.ptl.
  • Look at method _q_lookup (in __init__.py). It processes the first component in the URL. Remove and add a clause to the if statement to handle the component you need.
  • Create a class to handle the next component of the URL. You can use classes InfoHandler, ServiceHandler, MeerkatHandler, and ZipfileHandler as examples.

In file myapp/ui/servicesui.ptl, do the following:

• Add the classes required by your additions to myapp/ui/__init__.py.
• Use the existing classes (for example, InfoUI, ServicesUI, MeerkatUI, ZipfileUI) as examples. Here are a few notes and suggestions:
  • As much as possible, put only user interface code in this module. We'll discuss the code that does the rest of the work when we get to myapp/services/.
  • You can find examples in this module for creating user interfaces with each of the following:
    • Plain PTL strings and request.get_form_var() to get values entered at the browser.
    • Module form.widget, without the form object.
    • Modules form2.form and form2.widget``.

5���Start Your Server

python server-medusa.py

python server-scgi.py -p 3001 -l tmp.log

$ python server-scgi.py --help
option --help not recognized
Usage: server-scgi.py [options]

    -F -- stay in foreground (don't fork)
    -P -- PID filename
    -l -- log filename
    -m -- max children
    -p -- TCP port to listen on
    -u -- user id to run under

kill -HUP `cat /var/tmp/quixote-scgi.pid`

$ kill `cat /var/tmp/quixote-scgi.pid`

6���Adding New Functionality to the Application

These instructions assume that you will add a new module to the model (i.e. in directory myapp/services/). If instead, you add your new functionality to an existing module, you will need to modify the following instructions slightly.

In order to add a new capability to the skeleton application, do the following:

http://host:8081/mycapability/myfunction1
http://host:8081/mycapability/myfunction2
http://host:8081/mycapability/myfunction3

7���Customizing the form2 User Interface

The form2 module generates a user interface automatically. All your code needs to do is to add widgets to the form and then render the form (call the form's render method).

However, there are some things that you can do to customize the the look of the user interface. This section gives you a bit of guidance in doing so.

zipForm.add(form2.StringWidget, 'user_name', '[enter user name]',
    title='User name:',
    hint='Enter your name',
    size=40,
    required=False)

class MyForm(form2.Form):
    def _render_body(self):
        r = TemplateIO(html=True)
        r += htmltext('<table border="0" width="100%">')
        r += self._render_error_notice()
        r += self._render_components()
        r += self._render_button_widgets()
        r += htmltext('</table>')
        return r.getvalue()

    def render_sep(self):
        return htmltext('<tr><td colspan="3"><hr/></td></tr>')

    def _render_components(self):
        r = TemplateIO(html=True)
        firstTime = True
        for component in self.components:
            if not firstTime:
                r += self.render_sep()
            firstTime = False
            r += component.render()
        return r.getvalue()

class MyWidgetRow(form2.WidgetRow):
    def render(self):
        title = self.title or ''
        if title and self.required:
            title = title + htmltext(' *')
        r = TemplateIO(html=True)
        r += htmltext('<tr><th width="15%" align="left">')
        r += title
        r += htmltext('</th><td>')
        r += self.widget.render()
        r += htmltext('</td><td>')
        r += self._render_error()
        r += self._render_hint()
        r += htmltext('</td></tr>')
        return r.getvalue()

aSimpleForm = form2.Form(name='simple_form',
    action_url='show_contents',
    component_class=MyWidgetRow
    )

8���The Widgets -- Examples

Documentation on form2 is a bit slight. Here are examples of how to create and use the widgets in the form2 module:

from quixote.form2.widget import ButtonWidget    # [1]

class TestsUI:

    _q_exports = []
    
    def do_test_form2  [html](self, request):
        testForm = form2.Form(name='test_form',
            action_url='test_form2',
            )
        testForm.add(form2.StringWidget, 'string_widget', '[default string]',
            title='String widget:',
            hint='Enter a string.',
            size=40,                    # [2]
            required=False)
        testForm.add(form2.PasswordWidget, 'password_widget', '',
            title='Password widget:',
            hint='Enter a password.',
            size=40,
            required=False)
        testForm.add(form2.SingleSelectWidget, 'singleselect_widget', 'value2',
            title='Single select widget:',
            hint='Select a single value.',
            options=[
                ('value1', 'Value #1', 'key1'),                      # [3]
                ('value2', 'Value #2', 'key2'),
                ('value3', 'Value #3', 'key3'),
                ('value4', 'Value #4', 'key4'),
                ],
            sort=False)
        testForm.add(form2.MultipleSelectWidget, 'multipleselect_widget', ('value3', 'value5'),
            title='Multiple select widget:',
            hint='Select multiple values.',
            options=[
                ('value1', 'Value #1', 'key1'),                       # [3]
                ('value2', 'Value #2', 'key2'),
                ('value3', 'Value #3', 'key3'),
                ('value4', 'Value #4', 'key4'),
                ('value5', 'Value #5', 'key5'),
                ('value6', 'Value #6', 'key6'),
                ],
            sort=False)
        testForm.add(form2.RadiobuttonsWidget, 'radiobuttons_widget', 'value3',
            title='Radiobuttons widget:',
            hint='Select a radiobutton',
            options=[
                ('value1', 'Value #1', 'key1'),                      # [3]
                ('value2', 'Value #2', 'key2'),
                ('value3', 'Value #3', 'key3'),
                ('value4', 'Value #4', 'key4'),
                ],
            sort=False)
        testForm.add(form2.CheckboxWidget, 'checkbox_widget1', 1,    # [4]
            title='Checkbox widget 1:',
            hint='Unselected checkbox')
        testForm.add(form2.CheckboxWidget, 'checkbox_widget2', 0,    # [4]
            title='Checkbox widget 2:',
            hint='Selected checkbox')
        testForm.add(form2.TextWidget, 'textblock_widget', 0,
            title='Text block widget 2:',
            hint='Enter text in text block.',
            rows= 6,                                                 # [5]
            cols=60,
            )
        testForm.add_component(MyWidgetList, 'list_widget',
            value=['value1', 'value2', 'value3', 'value4'],
            title='List widget:',
            hint='WidgetList for test only',
            )
        testForm.add(ButtonWidget, 'button_widget', 'Say hello',
            onClick='javascript: alert(\'Hello\')',                  # [6]
            )
        testForm.add_submit('Submit', 'Submit')
        stringValue = testForm['string_widget']                      # [7]
        passwordValue = testForm['password_widget']
        singleselectValue = testForm['singleselect_widget']
        multipleselectValue = testForm['multipleselect_widget']
        radiobuttonsValue = testForm['radiobuttons_widget']
        checkboxValue1 = testForm['checkbox_widget1']
        checkboxValue2 = testForm['checkbox_widget2']
        textblockValue = testForm['textblock_widget']
        listValue = testForm['list_widget']
        header('Zip File Display')
        '<table border="2" width="100%">'
        '<tr><td>'
        '<p>String value: "'                                         # [8]
        stringValue
        '"</p><hr/>\n'
        '<p>Password value: "'
        passwordValue
        '"</p><hr/>\n'
        '<p>Single select value:'
        singleselectValue
        '</p><hr/>\n'
        '<p>Multiple select value:'
        multipleselectValue
        '</p><hr/>\n'
        '<p>Radiobuttons value:'
        radiobuttonsValue
        '</p><hr/>\n'
        '<p>Checkbox 1 value:'
        checkboxValue1
        '</p><hr/>\n'
        '<p>Checkbox 2 value:'
        checkboxValue2
        '</p><hr/>\n'
        '<p>Text block value: "'
        textblockValue
        '"</p><hr/>\n'
        '<p>List value:'
        listValue
        '</p>\n'
        '</td></tr>'
        '<tr><td>'
        testForm.render()                                            # [9]
        '</td></tr>'
        '</table>'
        footer()

Notes (see numbered references above):

1. The Button widget is not automatically exposed by the form2 module, so we import it explicitly.
2. The size argument is passed through to the StringWidget class. It is attached to the input item as a "size" attribute.
3. Because, when we create SingleSelectWidget, MultipleSelectWidget, we create each option with a tuple that contains (1) a value, (2) a description, and (3) a key, the following happens:
   • The widget (the HTML input item) displays each description (not the value).
   • When we request the value of the widget from the form, we get the value (not the description).
4. On check boxes, a true value causes the check box to be checked by default and a false value causes the check box to be un-checked by default.
5. We can pass through rows and cols arguments to control the size of the text block.
6. For a ButtonWidget, we pass through an onClick argument in order to attach JavaScript to the button.
7. We retrieve the value entered or selected for each input item (widget).
8. And, we display the values.
9. Finally, we render the form.

9���See Also

http://www.mems-exchange.org/software/quixote/: The Quixote support Web site.

Support for Quixote Etc: A variety of helpful documents on Quixote.