Update of /cvsroot/webware/Webware/WebKit/Docs
In directory sc8-pr-cvs1:/tmp/cvs-serv32091
Modified Files:
Configuration.html Configuration.txt Developing.html
Developing.txt UsersGuide.html UsersGuide.txt
Added Files:
ApplicationDevelopment.html ApplicationDevelopment.txt
Log Message:
Added new document: Application Development with Webware
This covers some basics in setting up an application with
webware. Right now it mostly covers MakeAppWorkDir, with
some CVS advice.
Minor updates to other documents. Regenerated HTML.
--- NEW FILE: ApplicationDevelopment.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<title>Application Development With Webware</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="application-development-with-webware">
<h1 class="title">Application Development With Webware</h1>
<p>Version 0.7, Webware for Python 0.7</p>
<div class="contents topic" id="contents">
<p class="topic-title"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#synopsis" id="id1" name="id1">Synopsis</a></li>
<li><a class="reference" href="#setting-up-your-application" id="id2" name="id2">Setting up your application</a><ul>
<li><a class="reference" href="#creating-a-working-directory" id="id3" name="id3">Creating a Working Directory</a></li>
<li><a class="reference" href="#using-cvs-for-your-application" id="id4" name="id4">Using CVS for your application</a></li>
<li><a class="reference" href="#using-the-working-directory-from-multiple-accounts" id="id5" name="id5">Using the working directory from multiple accounts</a></li>
</ul>
</li>
<li><a class="reference" href="#structuring-your-code" id="id6" name="id6">Structuring your Code</a><ul>
<li><a class="reference" href="#sitepage" id="id7" name="id7">SitePage</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="synopsis">
<h1><a class="toc-backref" href="#id1" name="synopsis">Synopsis</a></h1>
<p>Here we describe best practices for developing a web application using Webware.</p>
</div>
<div class="section" id="setting-up-your-application">
<h1><a class="toc-backref" href="#id2" name="setting-up-your-application">Setting up your application</a></h1>
<p>The first task in developing an application is to set up the file structure in which you will be working.</p>
<p>It is possible to put your application in a subdirectory under <tt class="literal"><span class="pre">WebKit/</span></tt> and change <tt class="literal"><span class="pre">WebKit/Configs/Application.config</span></tt> to add another context. But <em>do not do this</em>. Your application will be entwined with the Webware installation, making it difficult to upgrade Webware, and difficult to identify your own files from Webware files.</p>
<div class="section" id="creating-a-working-directory">
<h2><a class="toc-backref" href="#id3" name="creating-a-working-directory">Creating a Working Directory</a></h2>
<p>Instead you should use the script <tt class="literal"><span class="pre">bin/MakeAppWorkDir.py</span></tt>. You should run it like:</p>
<pre class="literal-block">
$ python Webware/bin/MakeAppWorkDir -l --cvsignore -c context DIRECTORYNAME
</pre>
<p>This will create a directory DIRECTORYNAME that will contain a directory structure for your application. The options are:</p>
<dl>
<dt><tt class="literal"><span class="pre">-l</span></tt>:</dt>
<dd>Create a <tt class="literal"><span class="pre">lib/</span></tt> directory which will be added to the Python path.</dd>
<dt><tt class="literal"><span class="pre">--cvsignore</span></tt>:</dt>
<dd>Create <tt class="literal"><span class="pre">.cvsignore</span></tt> files.</dd>
<dt><tt class="literal"><span class="pre">-c</span> <span class="pre">CONTEXTNAME</span></tt>:</dt>
<dd>Use CONTEXTNAME for the application context instead of <tt class="literal"><span class="pre">MyContext</span></tt> (there
will be a directory CONTEXTNAME/ in the work dir). I like the name
<tt class="literal"><span class="pre">context</span></tt> for all my applications.</dd>
<dt><tt class="literal"><span class="pre">DIRECTORYNAME</span></tt>:</dt>
<dd>The files will be put here. Name if after your application, place it where
it is convenient for you -- it doesn't need to be located close to the
Webware installation.</dd>
</dl>
<p>When you do this, you'll see this directory structure:</p>
<pre class="literal-block">
404Text.txt Cache/ ErrorMsgs/ Logs/ WebKit.cgi lib/
AppServer* Configs/ Launch.py Sessions/ context/
</pre>
<p>Here's what the files and directories are for:</p>
<dl>
<dt><tt class="literal"><span class="pre">404Text.txt</span></tt>:</dt>
<dd>The text when a page is not found (actually the HTML from <body> to
</body>).</dd>
<dt><tt class="literal"><span class="pre">AppServer</span></tt>:</dt>
<dd>The script to start up the AppServer for this application. Each application
will have its own AppServer, and its own process.</dd>
<dt><tt class="literal"><span class="pre">Cache</span></tt>:</dt>
<dd>A directory containing cache files. You won't need to look in here.</dd>
<dt><tt class="literal"><span class="pre">Configs</span></tt>:</dt>
<dd>Configuration files for the application. These files are taken from
<tt class="literal"><span class="pre">WebKit/Configs</span></tt>, but are specific to this application/AppServer.</dd>
<dt><tt class="literal"><span class="pre">ErrorMsgs</span></tt>:</dt>
<dd>HTML pages for any errors that occur. These can pile up and take up
considerable size (even just during development), so you'll want to purge
these every so often.</dd>
<dt><tt class="literal"><span class="pre">Launch.py</span></tt>:</dt>
<dd>Called by the <tt class="literal"><span class="pre">AppServer</span></tt> script to launch the AppServer.</dd>
<dt><tt class="literal"><span class="pre">Logs</span></tt>:</dt>
<dd>Logs of accesses.</dd>
<dt><tt class="literal"><span class="pre">Sessions</span></tt>:</dt>
<dd>Users sessions. These should be cleaned out automatically, you won't
have to look in this directory.</dd>
<dt><tt class="literal"><span class="pre">WebKit.cgi</span></tt>:</dt>
<dd>A CGI script/adapter for accessing the AppServer here. You can still use
the other adapters, but most of them don't need to be configured for the
individual applications. I still recommend mod_webkit or wkcgi.</dd>
<dt><tt class="literal"><span class="pre">context</span></tt>:</dt>
<dd>The directory (given with the <tt class="literal"><span class="pre">-c</span></tt> switch) for your default context. This
is where you put your servlets.</dd>
<dt><tt class="literal"><span class="pre">lib</span></tt>:</dt>
<dd>An application-specific library package, created if you give the <tt class="literal"><span class="pre">-l</span></tt>
switch. Import from this like <tt class="literal"><span class="pre">from</span> <span class="pre">lib.SitePage</span> <span class="pre">import</span> <span class="pre">SitePage</span></tt></dd>
</dl>
</div>
<div class="section" id="using-cvs-for-your-application">
<h2><a class="toc-backref" href="#id4" name="using-cvs-for-your-application">Using CVS for your application</a></h2>
<p>CVS is a useful tool for managing your application. It handles versioning, but it also makes it possible for other people to see snapshots of your progress, for multiple developers to collaborate and work on an application simultaneously, and it creates a sort of implicit file share. Even if you are the only developer on an application, CVS can be very helpful.</p>
<p>The working directory is a good place to start for creating a CVS module. Assuming you've set up cvs, you can get started simply by running:</p>
<pre class="literal-block">
$ cd WorkingDir
$ cvs import -d 'initial import' WorkingDir ianb start
@@ ib: check this command
</pre>
<p>You should use <tt class="literal"><span class="pre">--cvsignore</span></tt> if you plan to do this. If you do then <tt class="literal"><span class="pre">.cvsignore</span></tt> files will be added to each directory. These tell <tt class="literal"><span class="pre">cvs</span></tt> to ignore certain files -- <tt class="literal"><span class="pre">.pyc</span></tt> files, and all the files in certain directories (<tt class="literal"><span class="pre">Cache</span></tt>, <tt class="literal"><span class="pre">ErrorMsgs</span></tt>, <tt class="literal"><span class="pre">Logs</span></tt>, and <tt class="literal"><span class="pre">Sessions</span></tt>). You shouldn't otherwise notice these files, even if you aren't using CVS.</p>
</div>
<div class="section" id="using-the-working-directory-from-multiple-accounts">
<h2><a class="toc-backref" href="#id5" name="using-the-working-directory-from-multiple-accounts">Using the working directory from multiple accounts</a></h2>
<p>If you are using CVS or otherwise distributing your application code, you may find that it is difficult to manage the differences between accounts. For instance, in different accounts on different machines Webware may be installed in different locations. You may have the actual directory in a different location as well -- it may be in <tt class="literal"><span class="pre">~/webware/WorkingDir</span></tt> for your active development, but <tt class="literal"><span class="pre">/var/webware/WorkingDir</span></tt> for the production version. And if there are multiple development copies on the same machine, you have to be sure they each use different adapter ports.</p>
<p>To solve these problems I recommend creating a shell script to handle startup. I generally call this script <tt class="literal"><span class="pre">start</span></tt>, and it looks something like this:</p>
<pre class="literal-block">
#!/bin/sh
# lothlorien.colorstudy.com is my development machine
if [ `hostname` = lothlorien.colorstudy.com ] ; then
WORKING=$HOME/prog/webware/WorkingDir
WEBWARE=$HOME/prog/webware/Webware
OPS="--AppServer.AutoReload=1"
fi
# this is my production environment
if [ `hostname` = color.colorstudy.com && `whoami` = webware ] ; then
WORKING=/www/WorkingDir
WEBWARE=/www/Webware
OPS=""
fi
if [ "$WORKING" = "" ] ; then
echo I do not recognize this environment
exit 1
fi
cd $WORKING
./AppServer --working-path=$WORKING --webware-path=$WEBWARE $OPS $*
</pre>
<p>You can add this to CVS, and the script should automatically detect what environment it is being used in. You can use options to change configuration parameters, like setting some parameters depending on whether the environment is a development or production environment. (@@ ib: add link to command line options)</p>
<p>Some options that you may be particularly interested in:</p>
<dl>
<dt><tt class="literal"><span class="pre">--AppServer.AutoReload</span></tt>:</dt>
<dd>Setting this to <tt class="literal"><span class="pre">1</span></tt> will make the AppServer restart if there have been
changes to any loaded files. This is very nice during development.</dd>
<dt><tt class="literal"><span class="pre">--AppServer.Port</span></tt>:</dt>
<dd>If you want multiple applications running on the same machine (e.g., one
for development, one for production), you have to use different ports.</dd>
<dt><tt class="literal"><span class="pre">--Application.ShowDebugInfoOnErrors</span></tt>:</dt>
<dd>You probably don't want to have this on in production, but it's nice
during development.</dd>
<dt><tt class="literal"><span class="pre">--Application.SaveErrorMessages</span></tt>:</dt>
<dd>During development you probably want this off.</dd>
<dt><tt class="literal"><span class="pre">--Application.EmailErrors</span></tt>:</dt>
<dd>Turn on for production.</dd>
</dl>
<p>For more settings, see the <a class="reference" href="Configuration.html">Configuration</a> document.</p>
</div>
</div>
<div class="section" id="structuring-your-code">
<h1><a class="toc-backref" href="#id6" name="structuring-your-code">Structuring your Code</a></h1>
<p>Once you've got the basic files and directories in place, you're ready to go in and write some code. Don't let this document get in the way of developing the application how you choose, but here are some common patterns that have proven useful for Webware applications.</p>
<div class="section" id="sitepage">
<h2><a class="toc-backref" href="#id7" name="sitepage">SitePage</a></h2>
<p>Subclass <tt class="literal"><span class="pre">WebKit.Page</span></tt> for your application. This subclass will change some methods and add some new methods. It serves as the basis of all the pages that follow.</p>
<p>Some code you may wish to include in your SitePage:</p>
<ul class="simple">
<li>Authentication and security</li>
<li>Accessing common objects (e.g., a user object, or a document object)</li>
<li>Page header and footer</li>
<li>Common layout commands, like <tt class="literal"><span class="pre">writeHeader</span></tt></li>
</ul>
<p>I also typically add other functions to the SitePage module, and then do <tt class="literal"><span class="pre">from</span> <span class="pre">lib.SitePage</span> <span class="pre">import</span> <span class="pre">*</span></tt> in each servlet -- this might include functions like htmlEncode, or some other select functions that I use constantly in web applications. Whether you want to use functions or methods is up to you -- in many cases methods can be more easily extended or customized later, but sometimes method use can become excessive and create unnecessary dependences in your code.</p>
<p>A basic framework for your SitePage might be:</p>
<pre class="literal-block">
from WebKit.Page import Page
class SitePage(Page):
def respond(self, trans):
if self.securePage():
if not self.session().value('username', False):
self.respondLogIn()
return
def securePage(self):
"""Override this method in your servlets to return True if the
page should only be accessible to logged-in users -- by default
pages are publically viewable"""
return False
def respondLogin(self):
# Here we should deal with logging in...
pass
</pre>
<p>Obviously there are a lot of details to add in on your own which are specific to your application and the security and user model you are using.</p>
</div>
</div>
</div>
</body>
</html>
--- NEW FILE: ApplicationDevelopment.txt ---
Application Development With Webware
++++++++++++++++++++++++++++++++++++
Version 0.7, Webware for Python 0.7
.. contents::
Synopsis
========
Here we describe best practices for developing a web application using Webware.
Setting up your application
===========================
The first task in developing an application is to set up the file structure in which you will be working.
It is possible to put your application in a subdirectory under ``WebKit/`` and change ``WebKit/Configs/Application.config`` to add another context. But *do not do this*. Your application will be entwined with the Webware installation, making it difficult to upgrade Webware, and difficult to identify your own files from Webware files.
Creating a Working Directory
----------------------------
Instead you should use the script ``bin/MakeAppWorkDir.py``. You should run it like::
$ python Webware/bin/MakeAppWorkDir -l --cvsignore -c context DIRECTORYNAME
This will create a directory DIRECTORYNAME that will contain a directory structure for your application. The options are:
``-l``:
Create a ``lib/`` directory which will be added to the Python path.
``--cvsignore``:
Create ``.cvsignore`` files.
``-c CONTEXTNAME``:
Use CONTEXTNAME for the application context instead of ``MyContext`` (there
will be a directory CONTEXTNAME/ in the work dir). I like the name
``context`` for all my applications.
``DIRECTORYNAME``:
The files will be put here. Name if after your application, place it where
it is convenient for you -- it doesn't need to be located close to the
Webware installation.
When you do this, you'll see this directory structure::
404Text.txt Cache/ ErrorMsgs/ Logs/ WebKit.cgi lib/
AppServer* Configs/ Launch.py Sessions/ context/
Here's what the files and directories are for:
``404Text.txt``:
The text when a page is not found (actually the HTML from <body> to
</body>).
``AppServer``:
The script to start up the AppServer for this application. Each application
will have its own AppServer, and its own process.
``Cache``:
A directory containing cache files. You won't need to look in here.
``Configs``:
Configuration files for the application. These files are taken from
``WebKit/Configs``, but are specific to this application/AppServer.
``ErrorMsgs``:
HTML pages for any errors that occur. These can pile up and take up
considerable size (even just during development), so you'll want to purge
these every so often.
``Launch.py``:
Called by the ``AppServer`` script to launch the AppServer.
``Logs``:
Logs of accesses.
``Sessions``:
Users sessions. These should be cleaned out automatically, you won't
have to look in this directory.
``WebKit.cgi``:
A CGI script/adapter for accessing the AppServer here. You can still use
the other adapters, but most of them don't need to be configured for the
individual applications. I still recommend mod_webkit or wkcgi.
``context``:
The directory (given with the ``-c`` switch) for your default context. This
is where you put your servlets.
``lib``:
An application-specific library package, created if you give the ``-l``
switch. Import from this like ``from lib.SitePage import SitePage``
Using CVS for your application
------------------------------
CVS is a useful tool for managing your application. It handles versioning, but it also makes it possible for other people to see snapshots of your progress, for multiple developers to collaborate and work on an application simultaneously, and it creates a sort of implicit file share. Even if you are the only developer on an application, CVS can be very helpful.
The working directory is a good place to start for creating a CVS module. Assuming you've set up cvs, you can get started simply by running::
$ cd WorkingDir
$ cvs import -d 'initial import' WorkingDir ianb start
@@ ib: check this command
You should use ``--cvsignore`` if you plan to do this. If you do then ``.cvsignore`` files will be added to each directory. These tell ``cvs`` to ignore certain files -- ``.pyc`` files, and all the files in certain directories (``Cache``, ``ErrorMsgs``, ``Logs``, and ``Sessions``). You shouldn't otherwise notice these files, even if you aren't using CVS.
Using the working directory from multiple accounts
--------------------------------------------------
If you are using CVS or otherwise distributing your application code, you may find that it is difficult to manage the differences between accounts. For instance, in different accounts on different machines Webware may be installed in different locations. You may have the actual directory in a different location as well -- it may be in ``~/webware/WorkingDir`` for your active development, but ``/var/webware/WorkingDir`` for the production version. And if there are multiple development copies on the same machine, you have to be sure they each use different adapter ports.
To solve these problems I recommend creating a shell script to handle startup. I generally call this script ``start``, and it looks something like this::
#!/bin/sh
# lothlorien.colorstudy.com is my development machine
if [ `hostname` = lothlorien.colorstudy.com ] ; then
WORKING=$HOME/prog/webware/WorkingDir
WEBWARE=$HOME/prog/webware/Webware
OPS="--AppServer.AutoReload=1"
fi
# this is my production environment
if [ `hostname` = color.colorstudy.com && `whoami` = webware ] ; then
WORKING=/www/WorkingDir
WEBWARE=/www/Webware
OPS=""
fi
if [ "$WORKING" = "" ] ; then
echo I do not recognize this environment
exit 1
fi
cd $WORKING
./AppServer --working-path=$WORKING --webware-path=$WEBWARE $OPS $*
You can add this to CVS, and the script should automatically detect what environment it is being used in. You can use options to change configuration parameters, like setting some parameters depending on whether the environment is a development or production environment. (@@ ib: add link to command line options)
Some options that you may be particularly interested in:
``--AppServer.AutoReload``:
Setting this to ``1`` will make the AppServer restart if there have been
changes to any loaded files. This is very nice during development.
``--AppServer.Port``:
If you want multiple applications running on the same machine (e.g., one
for development, one for production), you have to use different ports.
``--Application.ShowDebugInfoOnErrors``:
You probably don't want to have this on in production, but it's nice
during development.
``--Application.SaveErrorMessages``:
During development you probably want this off.
``--Application.EmailErrors``:
Turn on for production.
For more settings, see the Configuration_ document.
.. _Configuration: Configuration.html
Structuring your Code
=====================
Once you've got the basic files and directories in place, you're ready to go in and write some code. Don't let this document get in the way of developing the application how you choose, but here are some common patterns that have proven useful for Webware applications.
SitePage
--------
Subclass ``WebKit.Page`` for your application. This subclass will change some methods and add some new methods. It serves as the basis of all the pages that follow.
Some code you may wish to include in your SitePage:
* Authentication and security
* Accessing common objects (e.g., a user object, or a document object)
* Page header and footer
* Common layout commands, like ``writeHeader``
I also typically add other functions to the SitePage module, and then do ``from lib.SitePage import *`` in each servlet -- this might include functions like htmlEncode, or some other select functions that I use constantly in web applications. Whether you want to use functions or methods is up to you -- in many cases methods can be more easily extended or customized later, but sometimes method use can become excessive and create unnecessary dependences in your code.
A basic framework for your SitePage might be::
from WebKit.Page import Page
class SitePage(Page):
def respond(self, trans):
if self.securePage():
if not self.session().value('username', False):
self.respondLogIn()
return
def securePage(self):
"""Override this method in your servlets to return True if the
page should only be accessible to logged-in users -- by default
pages are publically viewable"""
return False
def respondLogin(self):
# Here we should deal with logging in...
pass
Obviously there are a lot of details to add in on your own which are specific to your application and the security and user model you are using.
Index: Configuration.html
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/Configuration.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** Configuration.html 30 Oct 2002 23:19:39 -0000 1.1
--- Configuration.html 25 Dec 2002 04:44:18 -0000 1.2
***************
*** 1,8 ****
! <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.7: http://docutils.sourceforge.net/" />
<title>Configuration Guide</title>
<link rel="stylesheet" href="default.css" type="text/css" />
--- 1,8 ----
! <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<title>Configuration Guide</title>
<link rel="stylesheet" href="default.css" type="text/css" />
***************
*** 11,71 ****
<div class="document" id="configuration-guide">
<h1 class="title">Configuration Guide</h1>
! <p>@@ ib: order/group these in a more sensible way</p>
! <div class="section" id="appserver-config">
! <h1><a name="appserver-config">AppServer.config</a></h1>
! <dl>
! <dt><tt class="literal"><span class="pre">PrintConfigAtStartUp</span></tt>:</dt>
! <dd>Prints configuration to console at startup. Default <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
! <dt><tt class="literal"><span class="pre">Verbose</span></tt>:</dt>
! <dd>If true, then additional messages are printed while the AppServer
! runs, most notably information about each request such as size and
! response time. Default <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
! <dt><tt class="literal"><span class="pre">Host</span></tt>:</dt>
! <dd>The host the server runs on. There is little reason to change
! this. Default <tt class="literal"><span class="pre">127.0.0.1</span></tt>. @@ ib: if no reason to change, why
! do we have it?</dd>
! <dt><tt class="literal"><span class="pre">Port</span></tt>:</dt>
! <dd>The port the application server listens to for requests from the
! adapter. You cannot point a browser to this port. You may wish
! to change this if you have another application running at this
! port, or if you are running more than one AppServer they must each
! be listening at a different port. Default: <tt class="literal"><span class="pre">8086</span></tt>.</dd>
! <dt><tt class="literal"><span class="pre">PlugIns</span></tt>:</dt>
! <dd>Loads the plug-ins from the given locations when starting the
! AppServer. You must add a directory to the list for every plug-in
! you use -- <tt class="literal"><span class="pre">PlugInDirs</span></tt> is usually easier. Default <tt class="literal"><span class="pre">[]</span></tt>.</dd>
! <dt><tt class="literal"><span class="pre">PluginDirs</span></tt>:</dt>
! <dd><p class="first">When the application server starts up, it looks in these locations
! for plugins. Each plugin is a subdirectory of its own. By
! default WebKit looks in the <tt class="literal"><span class="pre">Webware/</span></tt> directory (<tt class="literal"><span class="pre">..</span></tt>) for
! plugins -- several of which are shipped with Webware. Default
! <tt class="literal"><span class="pre">[".."]</span></tt>. See <a class="reference" href="Developing.html#creatingplugins">Creating Plugins</a> for information on creating
! your own plug-ins. @@ ib: are these really differently cased?</p>
! <p class="last">The advantage of a plug-in directory is that you can add new
! plug-ins to the app server simply by dropping them into the
! directory; no additional configuration is necessary.</p>
! </dd>
! <dt><tt class="literal"><span class="pre">ServerThreads</span></tt>: </dt>
! <dd>The maximum number of threads in the request handler thread pool,
! and therefore, the maximum number of concurrent requests that can
! be served. Unless you have a serious load on a high end machine,
! the default is generally sufficient. Default <tt class="literal"><span class="pre">10</span></tt>. @@ ib: I
! don't believe this is correct -- I think more threads are
! created on demand, but only this many threads sit around waiting.</dd>
! <dt><tt class="literal"><span class="pre">CheckInterval</span></tt>:</dt>
! <dd>The number of virtual instructions after which Python will check
! for thread switches, signal handlers, etc. This is passed directly
! to <tt class="literal"><span class="pre">sys.setcheckinterval()</span></tt>. Benchmarks have shown 100 to give a
! worthwhile performance boost with higher values resulting in
! little gain. Default <tt class="literal"><span class="pre">100</span></tt>.</dd>
! </dl>
</div>
<div class="section" id="application-config">
! <h1><a name="application-config">Application.config</a></h1>
<dl>
<dt><tt class="literal"><span class="pre">AdminPassword</span></tt>:</dt>
<dd>The password that, combined with the <tt class="literal"><span class="pre">admin</span></tt> id, allows access
to the <tt class="literal"><span class="pre">AppControl</span></tt> page of the <tt class="literal"><span class="pre">Admin</span></tt> context. Set
interactively when <tt class="literal"><span class="pre">install.py</span></tt> is run. <em>No default</em>.</dd>
<dt><tt class="literal"><span class="pre">DirectoryFile</span></tt>:</dt>
<dd>The list of basic filenames that WebKit searches for when serving
--- 11,84 ----
<div class="document" id="configuration-guide">
<h1 class="title">Configuration Guide</h1>
! <div class="contents topic" id="contents">
! <p class="topic-title"><a name="contents">Contents</a></p>
! <ul class="simple">
! <li><a class="reference" href="#command-line-configuration" id="id1" name="id1">Command Line Configuration</a></li>
! <li><a class="reference" href="#application-config" id="id2" name="id2">Application.config</a><ul>
! <li><a class="reference" href="#general-settings" id="id3" name="id3">General Settings</a></li>
! <li><a class="reference" href="#path-handling" id="id4" name="id4">Path Handling</a></li>
! <li><a class="reference" href="#caching" id="id5" name="id5">Caching</a></li>
! <li><a class="reference" href="#errors" id="id6" name="id6">Errors</a></li>
! <li><a class="reference" href="#logging" id="id7" name="id7">Logging</a></li>
! </ul>
! </li>
! <li><a class="reference" href="#appserver-config" id="id8" name="id8">AppServer.config</a></li>
! </ul>
! </div>
! <div class="section" id="command-line-configuration">
! <h1><a class="toc-backref" href="#id1" name="command-line-configuration">Command Line Configuration</a></h1>
! <p>Each of these can be set in the <tt class="literal"><span class="pre">.config</span></tt> files, but they can be overridden with the command line. Run <tt class="literal"><span class="pre">AppServer</span></tt> with switches in the form <tt class="literal"><span class="pre">--ClassName.SettingName=value</span></tt>, e.g. <tt class="literal"><span class="pre">--AppServer.Port=1</span></tt></p>
! <p>The <tt class="literal"><span class="pre">value</span></tt> is coerced into a Python type: if it starts with one of the characters <tt class="literal"><span class="pre">({["'</span></tt> -- i.e., parenthesis (expression), dictionary, list, or string -- then the value with be eval'ed. If it can be turned into an integer or float, then it will be converted, otherwise it will be left as a string. Some examples:</p>
! <ul class="simple">
! <li><tt class="literal"><span class="pre">1</span></tt> == 1</li>
! <li><tt class="literal"><span class="pre">127.0.0.1</span></tt> == "127.0.0.1"</li>
! <li><tt class="literal"><span class="pre">(10+2)</span></tt> == 12</li>
! <li><tt class="literal"><span class="pre">{'a':</span> <span class="pre">'b'}</span></tt> == {'a': 'b'}</li>
! <li><tt class="literal"><span class="pre">{a:</span> <span class="pre">b}</span></tt> == <em>error</em></li>
! <li><tt class="literal"><span class="pre">[1,</span> <span class="pre">'c',</span> <span class="pre">[2,</span> <span class="pre">3]]</span></tt> == [1, 'c', [2, 3]]</li>
! </ul>
! <p>Be careful about special characters in the shell. All the characters <tt class="literal"><span class="pre">()</span> <span class="pre">[]</span> <span class="pre">'</span> <span class="pre">"</span></tt> are special, and need to be quoted (with <tt class="literal"><span class="pre">\</span></tt> or with single or double quotation marks).</p>
</div>
<div class="section" id="application-config">
! <h1><a class="toc-backref" href="#id2" name="application-config">Application.config</a></h1>
! <p><tt class="literal"><span class="pre">Application.config</span></tt> covers not only the application, but a number
! of components that use it as a central point of configuration.</p>
! <div class="section" id="general-settings">
! <h2><a class="toc-backref" href="#id3" name="general-settings">General Settings</a></h2>
<dl>
+ <dt><tt class="literal"><span class="pre">Contexts</span></tt>:</dt>
+ <dd><p class="first">This dictionary maps context names to the directory holding the
+ context content. Since the default contexts all reside in WebKit,
+ the paths are simple and relative. The context name appears as the
+ first path component of a URL, otherwise <tt class="literal"><span class="pre">Contexts['default']</span></tt>
+ is used when none is specified. When creating your own
+ application, you will add a key such as <tt class="literal"><span class="pre">"MyApp"</span></tt> with a value
+ such as <tt class="literal"><span class="pre">"/home/apps/MyApp"</span></tt>. That directory will then contain
+ content such as Main.py, SomeServlet.py, SomePage.psp,
+ etc. <tt class="literal"><span class="pre">Webware/bin/MakeAppWorkDir.py</span></tt> will set up a context for
+ your use as well. Default:</p>
+ <pre class="last literal-block">
+ {
+ 'default': 'Examples',
+ 'Admin': 'Admin',
+ 'Examples': 'Examples',
+ 'Docs': 'Docs',
+ 'Testing': 'Testing',
+ }
+ </pre>
+ </dd>
<dt><tt class="literal"><span class="pre">AdminPassword</span></tt>:</dt>
<dd>The password that, combined with the <tt class="literal"><span class="pre">admin</span></tt> id, allows access
to the <tt class="literal"><span class="pre">AppControl</span></tt> page of the <tt class="literal"><span class="pre">Admin</span></tt> context. Set
interactively when <tt class="literal"><span class="pre">install.py</span></tt> is run. <em>No default</em>.</dd>
+ <dt><tt class="literal"><span class="pre">PrintConfigAtStartUp</span></tt>:</dt>
+ <dd>Print the configuration to the console when AppServer starts.</dd>
+ </dl>
+ </div>
+ <div class="section" id="path-handling">
+ <h2><a class="toc-backref" href="#id4" name="path-handling">Path Handling</a></h2>
+ <p>These configuration settings control which files are exposed to users,
+ which files are hidden, and some of how those files get chosen.</p>
+ <dl>
<dt><tt class="literal"><span class="pre">DirectoryFile</span></tt>:</dt>
<dd>The list of basic filenames that WebKit searches for when serving
***************
*** 73,78 ****
will look for a file with any appropriate extension (<tt class="literal"><span class="pre">.py</span></tt>.,
<tt class="literal"><span class="pre">.html</span></tt>, <tt class="literal"><span class="pre">.psp</span></tt>, etc). Default <tt class="literal"><span class="pre">["index",</span> <span class="pre">"Main"]</span></tt>.</dd>
- <dt><tt class="literal"><span class="pre">PrintConfigAtStartUp</span></tt>:</dt>
- <dd>Print the configuration to the console when AppServer starts.</dd>
<dt><tt class="literal"><span class="pre">ExtensionsToIgnore</span></tt>:</dt>
<dd>This is a list of extensions that WebKit will ignore when
--- 86,89 ----
***************
*** 108,151 ****
requests, not just requests with autodetected extensions. If set
to <tt class="literal"><span class="pre">[]</span></tt> then no restrictions are placed. Default: <tt class="literal"><span class="pre">[]</span></tt>.</dd>
- <dt><tt class="literal"><span class="pre">LogActivity</span></tt>:</dt>
- <dd>If true, then the execution of each servlet is logged with useful
- information such as time, duration and whether or not an error
- occurred. Default: <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
- <dt><tt class="literal"><span class="pre">ActivityLogFilenames</span></tt>:</dt>
- <dd>This is the name of the file that servlet executions are logged
- to. This setting has no effect if <tt class="literal"><span class="pre">LogActivity</span></tt> is 0. The path
- can be relative to the WebKit location, or an absolute path.
- Default: <tt class="literal"><span class="pre">"Logs/Activity.csv"</span></tt>.</dd>
- <dt><tt class="literal"><span class="pre">ActivityLogColumns</span></tt>:</dt>
- <dd>Specifies the columns that will be stored in the activity
- log. Each column can refer to an object from the set:
- [application, transaction, request, response, servlet, session]
- and then refer to its attributes using "dot notation". The
- attributes can be methods or instance attributes and can be
- qualified arbitrarily deep. Default: <tt class="literal"><span class="pre">['request.remoteAddress',</span>
- <span class="pre">'request.method',</span> <span class="pre">'request.uri',</span> <span class="pre">'response.size',</span> <span class="pre">'servlet.name',</span>
- <span class="pre">'request.timeStamp',</span> <span class="pre">'transaction.duration',</span>
- <span class="pre">'transaction.errorOccurred']</span></tt>.</dd>
- <dt><tt class="literal"><span class="pre">Contexts</span></tt>:</dt>
- <dd><p class="first">This dictionary maps context names to the directory holding the
- context content. Since the default contexts all reside in WebKit,
- the paths are simple and relative. The context name appears as the
- first path component of a URL, otherwise <tt class="literal"><span class="pre">Contexts['default']</span></tt>
- is used when none is specified. When creating your own
- application, you will add a key such as <tt class="literal"><span class="pre">"MyApp"</span></tt> with a value
- such as <tt class="literal"><span class="pre">"/home/apps/MyApp"</span></tt>. That directory will then contain
- content such as Main.py, SomeServlet.py, SomePage.psp,
- etc. <tt class="literal"><span class="pre">Webware/bin/MakeAppWorkDir.py</span></tt> will set up a context for
- your use as well. Default:</p>
- <pre class="last literal-block">
- {
- 'default': 'Examples',
- 'Admin': 'Admin',
- 'Examples': 'Examples',
- 'Docs': 'Docs',
- 'Testing': 'Testing',
- }
- </pre>
- </dd>
<dt><tt class="literal"><span class="pre">SessionStore</span></tt>:</dt>
<dd>This setting determines which of the three session stores is used
--- 119,122 ----
***************
*** 201,204 ****
--- 172,211 ----
<tt class="literal"><span class="pre">extraURLPath()</span></tt>. For subclassers of <tt class="literal"><span class="pre">Page</span></tt>, this would be
<tt class="literal"><span class="pre">self.request().extraURLPath()</span></tt>. Default: <tt class="literal"><span class="pre">0</span></tt> (false).</dd>
+ <dt><tt class="literal"><span class="pre">UnknownFileTypes</span></tt>:</dt>
+ <dd><p class="first">This setting controls the manner in which WebKit serves "unknown
+ extensions" such as .html, .gif, .jpeg, etc. The default settings
+ specify that the servlet matching the file be cached in memory,
+ that the contents of the file be cached in memory and that the
+ file timestamp to be checked on every request. This works well for
+ most sites.</p>
+ <p>If your site has a large amount of static files being served via
+ WebKit, you should consider changing <tt class="literal"><span class="pre">"CacheContent"</span></tt> to 0. If
+ you are confident that your static files do not get updated while
+ the app server is live, then you might consider changing
+ <tt class="literal"><span class="pre">"CheckDate"</span></tt> to <tt class="literal"><span class="pre">0</span></tt> for (slightly) better performance. If
+ you are concerned about performance, use <a class="reference" href="UserGuide.html">mod_rewrite</a> to avoid
+ accessing WebKit for static content. @@ ib: link to mod_rewrite</p>
+ <p>The <tt class="literal"><span class="pre">Technique</span></tt> setting can be switch to
+ <tt class="literal"><span class="pre">"redirectSansAdapter"</span></tt>, but this is an experimental setting
+ with some known problems. Default:</p>
+ <pre class="last literal-block">
+ {
+ 'ReuseServlets': 1,
+
+ # Technique choices:
+ # serveContent, redirectSansAdapter
+ 'Technique': 'serveContent',
+
+ # If serving content:
+ 'CacheContent': 1, # set to 0 to reduce memory use
+ 'CheckDate': 1,
+ }
+ </pre>
+ </dd>
+ </dl>
+ </div>
+ <div class="section" id="caching">
+ <h2><a class="toc-backref" href="#id5" name="caching">Caching</a></h2>
+ <dl>
<dt><tt class="literal"><span class="pre">CacheServletClasses</span></tt>:</dt>
<dd>When set to zero, the AppServer will not cache the classes that
***************
*** 217,220 ****
--- 224,232 ----
take a long time to compile, this can give a speedup. Default:
<tt class="literal"><span class="pre">1</span></tt> (true/caching does not persist)</dd>
+ </dl>
+ </div>
+ <div class="section" id="errors">
+ <h2><a class="toc-backref" href="#id6" name="errors">Errors</a></h2>
+ <dl>
<dt><tt class="literal"><span class="pre">ShowDebugInfoOnErrors</span></tt>:</dt>
<dd>If true, then uncaught exceptions will not only display a message
***************
*** 280,314 ****
</pre>
</dd>
- <dt><tt class="literal"><span class="pre">UnknownFileTypes</span></tt>:</dt>
- <dd><p class="first">This setting controls the manner in which WebKit serves "unknown
- extensions" such as .html, .gif, .jpeg, etc. The default settings
- specify that the servlet matching the file be cached in memory,
- that the contents of the file be cached in memory and that the
- file timestamp to be checked on every request. This works well for
- most sites.</p>
- <p>If your site has a large amount of static files being served via
- WebKit, you should consider changing <tt class="literal"><span class="pre">"CacheContent"</span></tt> to 0. If
- you are confident that your static files do not get updated while
- the app server is live, then you might consider changing
- <tt class="literal"><span class="pre">"CheckDate"</span></tt> to <tt class="literal"><span class="pre">0</span></tt> for (slightly) better performance. If
- you are concerned about performance, use <a class="reference" href="UserGuide.html">mod_rewrite</a> to avoid
- accessing WebKit for static content. @@ ib: link to mod_rewrite</p>
- <p>The <tt class="literal"><span class="pre">Technique</span></tt> setting can be switch to
- <tt class="literal"><span class="pre">"redirectSansAdapter"</span></tt>, but this is an experimental setting
- with some known problems. Default:</p>
- <pre class="last literal-block">
- {
- 'ReuseServlets': 1,
-
- # Technique choices:
- # serveContent, redirectSansAdapter
- 'Technique': 'serveContent',
-
- # If serving content:
- 'CacheContent': 1, # set to 0 to reduce memory use
- 'CheckDate': 1,
- }
- </pre>
- </dd>
<dt><tt class="literal"><span class="pre">MaxValueLengthInExceptionReport</span></tt>:</dt>
<dd>Values in exception reports are truncated to this length, to avoid
--- 292,295 ----
***************
*** 330,333 ****
--- 311,389 ----
raising exceptions by design and you don't want to be notified.
Default: <tt class="literal"><span class="pre">1</span></tt> (true/do report exceptions).</dd>
+ </dl>
+ </div>
+ <div class="section" id="logging">
+ <h2><a class="toc-backref" href="#id7" name="logging">Logging</a></h2>
+ <dl>
+ <dt><tt class="literal"><span class="pre">LogActivity</span></tt>:</dt>
+ <dd>If true, then the execution of each servlet is logged with useful
+ information such as time, duration and whether or not an error
+ occurred. Default: <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
+ <dt><tt class="literal"><span class="pre">ActivityLogFilenames</span></tt>:</dt>
+ <dd>This is the name of the file that servlet executions are logged
+ to. This setting has no effect if <tt class="literal"><span class="pre">LogActivity</span></tt> is 0. The path
+ can be relative to the WebKit location, or an absolute path.
+ Default: <tt class="literal"><span class="pre">"Logs/Activity.csv"</span></tt>.</dd>
+ <dt><tt class="literal"><span class="pre">ActivityLogColumns</span></tt>:</dt>
+ <dd>Specifies the columns that will be stored in the activity
+ log. Each column can refer to an object from the set:
+ [application, transaction, request, response, servlet, session]
+ and then refer to its attributes using "dot notation". The
+ attributes can be methods or instance attributes and can be
+ qualified arbitrarily deep. Default: <tt class="literal"><span class="pre">['request.remoteAddress',</span>
+ <span class="pre">'request.method',</span> <span class="pre">'request.uri',</span> <span class="pre">'response.size',</span> <span class="pre">'servlet.name',</span>
+ <span class="pre">'request.timeStamp',</span> <span class="pre">'transaction.duration',</span>
+ <span class="pre">'transaction.errorOccurred']</span></tt>.</dd>
+ </dl>
+ </div>
+ </div>
+ <div class="section" id="appserver-config">
+ <h1><a class="toc-backref" href="#id8" name="appserver-config">AppServer.config</a></h1>
+ <dl>
+ <dt><tt class="literal"><span class="pre">Host</span></tt>:</dt>
+ <dd>The host the server runs on. There is little reason to change
+ this unless you have a machine with multiple network interfaces,
+ and you don't want Webware to listen on all interfaces.
+ Default <tt class="literal"><span class="pre">127.0.0.1</span></tt>.</dd>
+ <dt><tt class="literal"><span class="pre">Port</span></tt>:</dt>
+ <dd>The port the application server listens to for requests from the
+ adapter. You cannot point a browser to this port. You may wish
+ to change this if you have another application running at this
+ port, or if you are running more than one AppServer they must each
+ be listening at a different port. Default: <tt class="literal"><span class="pre">8086</span></tt>.</dd>
+ <dt><tt class="literal"><span class="pre">PluginDirs</span></tt>:</dt>
+ <dd><p class="first">When the application server starts up, it looks in these locations
+ for plugins. Each plugin is a subdirectory of its own. By
+ default WebKit looks in the <tt class="literal"><span class="pre">Webware/</span></tt> directory (<tt class="literal"><span class="pre">..</span></tt>) for
+ plugins -- several of which are shipped with Webware. Default
+ <tt class="literal"><span class="pre">[".."]</span></tt>. See <a class="reference" href="Developing.html#creatingplugins">Creating Plugins</a> for information on creating
+ your own plug-ins. @@ ib: are these really differently cased?</p>
+ <p class="last">The advantage of a plug-in directory is that you can add new
+ plug-ins to the app server simply by dropping them into the
+ directory; no additional configuration is necessary.</p>
+ </dd>
+ <dt><tt class="literal"><span class="pre">PlugIns</span></tt>:</dt>
+ <dd>Loads the plug-ins from the given locations when starting the
+ AppServer. You must add a directory to the list for every plug-in
+ you use -- <tt class="literal"><span class="pre">PlugInDirs</span></tt> is usually easier. Default <tt class="literal"><span class="pre">[]</span></tt>.</dd>
+ <dt><tt class="literal"><span class="pre">PrintConfigAtStartUp</span></tt>:</dt>
+ <dd>Prints configuration to console at startup. Default <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
+ <dt><tt class="literal"><span class="pre">Verbose</span></tt>:</dt>
+ <dd>If true, then additional messages are printed while the AppServer
+ runs, most notably information about each request such as size and
+ response time. Default <tt class="literal"><span class="pre">1</span></tt> (true).</dd>
+ <dt><tt class="literal"><span class="pre">ServerThreads</span></tt>: </dt>
+ <dd>The maximum number of threads in the request handler thread pool,
+ and therefore, the maximum number of concurrent requests that can
+ be served. Unless you have a serious load on a high end machine,
+ the default is generally sufficient. Default <tt class="literal"><span class="pre">10</span></tt>. @@ ib: I
+ don't believe this is correct -- I think more threads are
+ created on demand, but only this many threads sit around waiting.</dd>
+ <dt><tt class="literal"><span class="pre">CheckInterval</span></tt>:</dt>
+ <dd>The number of virtual instructions after which Python will check
+ for thread switches, signal handlers, etc. This is passed directly
+ to <tt class="literal"><span class="pre">sys.setcheckinterval()</span></tt>. Benchmarks have shown 100 to give a
+ worthwhile performance boost with higher values resulting in
+ little gain. Default <tt class="literal"><span class="pre">100</span></tt>.</dd>
</dl>
</div>
Index: Configuration.txt
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/Configuration.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** Configuration.txt 3 Nov 2002 02:42:41 -0000 1.3
--- Configuration.txt 25 Dec 2002 04:44:19 -0000 1.4
***************
*** 4,7 ****
--- 4,23 ----
.. contents::
+ Command Line Configuration
+ ==========================
+
+ Each of these can be set in the ``.config`` files, but they can be overridden with the command line. Run ``AppServer`` with switches in the form ``--ClassName.SettingName=value``, e.g. ``--AppServer.Port=1``
+
+ The ``value`` is coerced into a Python type: if it starts with one of the characters ``({["'`` -- i.e., parenthesis (expression), dictionary, list, or string -- then the value with be eval'ed. If it can be turned into an integer or float, then it will be converted, otherwise it will be left as a string. Some examples:
+
+ * ``1`` == 1
+ * ``127.0.0.1`` == "127.0.0.1"
+ * ``(10+2)`` == 12
+ * ``{'a': 'b'}`` == {'a': 'b'}
+ * ``{a: b}`` == *error*
+ * ``[1, 'c', [2, 3]]`` == [1, 'c', [2, 3]]
+
+ Be careful about special characters in the shell. All the characters ``() [] ' "`` are special, and need to be quoted (with ``\`` or with single or double quotation marks).
+
Application.config
==================
***************
*** 306,311 ****
``Host``:
The host the server runs on. There is little reason to change
! this. Default ``127.0.0.1``. @@ ib: if no reason to change, why
! do we have it?
``Port``:
The port the application server listens to for requests from the
--- 322,328 ----
``Host``:
The host the server runs on. There is little reason to change
! this unless you have a machine with multiple network interfaces,
! and you don't want Webware to listen on all interfaces.
! Default ``127.0.0.1``.
``Port``:
The port the application server listens to for requests from the
Index: Developing.html
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/Developing.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** Developing.html 30 Oct 2002 23:19:39 -0000 1.1
--- Developing.html 25 Dec 2002 04:44:19 -0000 1.2
***************
*** 1,8 ****
! <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.7: http://docutils.sourceforge.net/" />
<title>Developing Webware</title>
<link rel="stylesheet" href="default.css" type="text/css" />
--- 1,8 ----
! <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<title>Developing Webware</title>
<link rel="stylesheet" href="default.css" type="text/css" />
***************
*** 12,16 ****
<h1 class="title">Developing Webware</h1>
<p>This document should outline the details you need to understand to
! Webware and WebKit internals, and assist in becoming an advanced
Webware programmer.</p>
<div class="section" id="creating-plugins">
--- 12,16 ----
<h1 class="title">Developing Webware</h1>
<p>This document should outline the details you need to understand to
! Webware and WebKit internals, and assist in becoming a more advanced
Webware programmer.</p>
<div class="section" id="creating-plugins">
***************
*** 18,25 ****
<p>Each plugin is a Python Package. WebKit finds plugins using the
<tt class="literal"><span class="pre">PlugIns</span></tt> and <tt class="literal"><span class="pre">PluginDirs</span></tt> -- see <a class="reference" href="Configuration.html#appserverconfig">Configuration</a>. See also the
! <a class="reference" href="http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000">Python tutorial on packages</a> and the <tt class="literal"><span class="pre">Plugin.py</span></tt> doc string.</p>
<p>A plug-in must have <tt class="literal"><span class="pre">__init__.py</span></tt> and <tt class="literal"><span class="pre">Properties.py</span></tt> files. You
can disable a specific plug-in by placing a <tt class="literal"><span class="pre">dontload</span></tt> file in it.</p>
! <p>@@ ib: document __init__.py, Properties.py</p>
</div>
</div>
--- 18,57 ----
<p>Each plugin is a Python Package. WebKit finds plugins using the
<tt class="literal"><span class="pre">PlugIns</span></tt> and <tt class="literal"><span class="pre">PluginDirs</span></tt> -- see <a class="reference" href="Configuration.html#appserverconfig">Configuration</a>. See also the
! <a class="reference" href="http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000">Python tutorial on packages</a> and the <tt class="literal"><span class="pre">PlugIn.py</span></tt> doc string.</p>
<p>A plug-in must have <tt class="literal"><span class="pre">__init__.py</span></tt> and <tt class="literal"><span class="pre">Properties.py</span></tt> files. You
can disable a specific plug-in by placing a <tt class="literal"><span class="pre">dontload</span></tt> file in it.</p>
! <p><tt class="literal"><span class="pre">__init.py__</span></tt> must contain a function like:</p>
! <pre class="literal-block">
! def InstallInWebKit(appServer):
! pass
! </pre>
! <p>The function doesn't need to do anything, but this gives it the
! opportunity to do something with the AppServer -- for instance, the
! PSP plugin uses AppServer.addServletFactory to add a handler for <tt class="literal"><span class="pre">.psp</span></tt>
! files.</p>
! <p>The <tt class="literal"><span class="pre">Properties.py</span></tt> file should contain a number of assignments:</p>
! <pre class="literal-block">
! name = "Plugin name"
! version = (1, 0, 0)
! docs = [{'name': 'Quick Start Guide', 'file': 'QuickStart.html'},
! {'name': 'Reference Guide, 'file': 'Reference.html'}]
! status = 'beta'
! requiredPyVersion = (2, 0, 0)
! requiredOpSys = 'posix'
! synopsis = """A paragraph-long description of the plugin"""
! WebKitConfig = {
! 'examplePages': [
! 'Example1',
! 'ComplexExample',
! ]
! }
! def willRunFunc():
! if softwareNotInstalled:
! return "some message to that effect"
! else:
! return None
! </pre>
! <p>The documents (e.g. <tt class="literal"><span class="pre">QuickStart.html</span></tt>) should be located in a <tt class="literal"><span class="pre">Docs/</span></tt> subdirectory. The example pages go in an <tt class="literal"><span class="pre">Examples/</span></tt> subdirectory.</p>
! <p>A plugin who's <tt class="literal"><span class="pre">requiredPyVersion</span></tt> or <tt class="literal"><span class="pre">requiredOpSys</span></tt> aren't satisfied will simply be ignored. <tt class="literal"><span class="pre">requiredOpSys</span></tt> should be something returned by <tt class="literal"><span class="pre">os.name</span></tt>, like <tt class="literal"><span class="pre">posix</span></tt> or <tt class="literal"><span class="pre">nt</span></tt>. Or you can define a function <tt class="literal"><span class="pre">willRunFunc</span></tt> to test. If there aren't requirements you can leave these variables and functions out.</p>
</div>
</div>
Index: Developing.txt
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/Developing.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** Developing.txt 30 Oct 2002 23:19:39 -0000 1.2
--- Developing.txt 25 Dec 2002 04:44:19 -0000 1.3
***************
*** 3,7 ****
This document should outline the details you need to understand to
! Webware and WebKit internals, and assist in becoming an advanced
Webware programmer.
--- 3,7 ----
This document should outline the details you need to understand to
! Webware and WebKit internals, and assist in becoming a more advanced
Webware programmer.
***************
*** 11,15 ****
Each plugin is a Python Package. WebKit finds plugins using the
``PlugIns`` and ``PluginDirs`` -- see Configuration_. See also the
! `Python tutorial on packages`__ and the ``Plugin.py`` doc string.
.. __: http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000
--- 11,15 ----
Each plugin is a Python Package. WebKit finds plugins using the
``PlugIns`` and ``PluginDirs`` -- see Configuration_. See also the
! `Python tutorial on packages`__ and the ``PlugIn.py`` doc string.
.. __: http://www.python.org/doc/current/tut/node8.html#SECTION008400000000000000000
***************
*** 20,23 ****
can disable a specific plug-in by placing a ``dontload`` file in it.
! @@ ib: document __init__.py, Properties.py
--- 20,57 ----
can disable a specific plug-in by placing a ``dontload`` file in it.
! ``__init.py__`` must contain a function like::
!
! def InstallInWebKit(appServer):
! pass
!
! The function doesn't need to do anything, but this gives it the
! opportunity to do something with the AppServer -- for instance, the
! PSP plugin uses AppServer.addServletFactory to add a handler for ``.psp``
! files.
!
! The ``Properties.py`` file should contain a number of assignments::
!
! name = "Plugin name"
! version = (1, 0, 0)
! docs = [{'name': 'Quick Start Guide', 'file': 'QuickStart.html'},
! {'name': 'Reference Guide, 'file': 'Reference.html'}]
! status = 'beta'
! requiredPyVersion = (2, 0, 0)
! requiredOpSys = 'posix'
! synopsis = """A paragraph-long description of the plugin"""
! WebKitConfig = {
! 'examplePages': [
! 'Example1',
! 'ComplexExample',
! ]
! }
! def willRunFunc():
! if softwareNotInstalled:
! return "some message to that effect"
! else:
! return None
!
! The documents (e.g. ``QuickStart.html``) should be located in a ``Docs/`` subdirectory. The example pages go in an ``Examples/`` subdirectory.
!
! A plugin who's ``requiredPyVersion`` or ``requiredOpSys`` aren't satisfied will simply be ignored. ``requiredOpSys`` should be something returned by ``os.name``, like ``posix`` or ``nt``. Or you can define a function ``willRunFunc`` to test. If there aren't requirements you can leave these variables and functions out.
Index: UsersGuide.html
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/UsersGuide.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** UsersGuide.html 30 Oct 2002 23:19:39 -0000 1.29
--- UsersGuide.html 25 Dec 2002 04:44:19 -0000 1.30
***************
*** 1,8 ****
! <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.7: http://docutils.sourceforge.net/" />
<title>WebKit User's Guide</title>
<link rel="stylesheet" href="default.css" type="text/css" />
--- 1,8 ----
! <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<title>WebKit User's Guide</title>
<link rel="stylesheet" href="default.css" type="text/css" />
***************
*** 53,57 ****
<h1><a class="toc-backref" href="#id6" name="feedback">Feedback</a></h1>
<p>You can e-mail <a class="reference" href="mailto:webware-discuss@lists.sourceforge.net">webware-discuss@lists.sourceforge.net</a> to give feedback,
! discuss features and get help using WebKit. If you have a bug to
report, use the <a class="reference" href="http://sourceforge.net/tracker/?atid=104866&group_id=4866&func=browse">bug tracker</a>.</p>
</div>
--- 53,57 ----
<h1><a class="toc-backref" href="#id6" name="feedback">Feedback</a></h1>
<p>You can e-mail <a class="reference" href="mailto:webware-discuss@lists.sourceforge.net">webware-discuss@lists.sourceforge.net</a> to give feedback,
! discuss features, and get help using WebKit. If you have a bug to
report, use the <a class="reference" href="http://sourceforge.net/tracker/?atid=104866&group_id=4866&func=browse">bug tracker</a>.</p>
</div>
***************
*** 194,199 ****
need to set <span class=name>ShowConsole</span> to 1 in <span
class=filename>WebKit/Configs/OneShotAdapter.config</span>. @@ ib:
! shall we kill this?
! -->
</div>
<div class="section" id="raising-exceptions">
--- 194,198 ----
need to set <span class=name>ShowConsole</span> to 1 in <span
class=filename>WebKit/Configs/OneShotAdapter.config</span>. @@ ib:
! shall we kill this? -->
</div>
<div class="section" id="raising-exceptions">
Index: UsersGuide.txt
===================================================================
RCS file: /cvsroot/webware/Webware/WebKit/Docs/UsersGuide.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** UsersGuide.txt 30 Oct 2002 23:19:39 -0000 1.2
--- UsersGuide.txt 25 Dec 2002 04:44:19 -0000 1.3
***************
*** 18,22 ****
You can e-mail webware-discuss@... to give feedback,
! discuss features and get help using WebKit. If you have a bug to
report, use the `bug tracker`_.
--- 18,22 ----
You can e-mail webware-discuss@... to give feedback,
! discuss features, and get help using WebKit. If you have a bug to
report, use the `bug tracker`_.
|