Return to INSTALL.txt CVS log

Up to [Repository] / kupuMPIWG / doc

===============
Installing Kupu
===============

Abstract
--------

This document describes the installation of Kupu into a web
application.  Since Kupu itself makes little assumptions about the
environment, this document too is very general.

If you need specific instructions on how to install Kupu in

  o Zope 2.x, please refer to ZOPE2.txt_

  o Plone 2.x, please refer to PLONE2.txt_

.. _ZOPE2.txt: ZOPE2.html
.. _PLONE2.txt: PLONE2.html


Requirements
------------

o An XSLT processor with XInclude support, such as xsltproc from
  Gnome's libxml/libxslt.

  Windows users: You can get libxml/libxslt binaries at
  http://www.zlatkovic.com/pub/libxml/. As a minimum you need to
  download the zipfiles for libxslt, libxml2, iconv and zlib.
  Extracting all of the .dll and .exe files into c:\libxslt is
  sufficient for make.bat to work (ignore subdirectories in the
  zipfiles).

o A webserver that can handle some form of server-side processing, and
  preferrably also HTTP PUT requests (POST is also supported, see 'PUT
  or POST' below).


Quick installation
------------------

Basic install on a 'plain' webserver (Apache, IIS, etc.):

Unpack the kupu tarball. XXX xsl transformation, copy default dir XXX


Configuration and customization
-------------------------------

The default kupu.html is quite sober: it serves as an example or base
document rather then as an out-of-the-box webpage. To configure Kupu
you can set some attribute values on the iframe, change the CSS or
override initKupu() (the initialization function). The latter is only
necessary for larger customizations, simpler ones (like removing a
tool from the UI or changing a button image) will usually only mean
overriding the CSS. For more information about customization and
configuration see CUSTOMIZING.txt.


Adding dynamics
---------------
  
To use the kupu.html file for editing multiple files, you will
probably want to make the 'src' and 'dst' attributes get filled from
script (SSI, PHP, ASP, etc.). Kupu will load it's content from the URL
in the 'src' attribute (actually it lets the browser do that, it's the
default behaviour of an iframe) and will send the results to the URL
in the 'dst' attribute (this obviously is done by Kupu rather than by
the browser).  Although this sort of thing isn't hard to accomplish,
writing dynamic web applications is beyond the scope of this document,
partially because there are many different platforms on which Kupu
will run (and as many different server-side scripting languages and
technologies). There is, however, plenty of documentation about this
subject available on-line.


PUT or POST
-----------

Kupu will by default send its data to the server the HTTP PUT request
method. Using PUT rather than POST has some advantages: Kupu can make
asynchronous PUT requests (currently async POST is not implemented) so
when a user saves the page doesn't have to be reloaded, and since PUT
is invented for storing full documents and Kupu edits full documents,
it is the most logical and elegant request method to use.

If for some reason PUT is not available on your platform, Kupu can
also be used inside an HTML form to participate in a POST
situation. This way Kupu behaves like it is a field in a form, when
the form gets submitted Kupu will add a hidden form field to the form
and place it's contents in the field, so it is part of the request
body when the form is submitted. To accomplish this, a method called
'prepareForm' should be called just before the form is submitted. For
an example of how to use this method, see kupuform.html (which can
also be used as the basis for your Kupu editor page, like kupu.html).

Setting up a webserver is or explaining the details about writing a
script that handles POST or PUT requests is out of scope for this
document but there should be plenty documentation available on the
internet.
 
If problems occur...
--------------------

If you have installation problems, see http://kupu.oscom.org for a
list of possible places to ask questions (mailinglist, IRC channel) or
send an email to kupu-dev@codespeak.net.