Jalopy - a Collaborative Web Project

Installation and Use Guide

Author: Michael Foord
Contact: fuzzyman at voidspace dot org dot uk
Author Homepage:
 Pythonutils
Version: Jalopy v0.6.0
Date: 2005/09/21
License:BSD License
Home Page:Jalopy Homepage
Online Demo:Jalopy and Login demo
Support and Bug Reports:
 Pythonutils Mailing List

Contents

1   An Introduction

Jalopy is a 'collaborative website' creator, with a built in, online, WYSIWYG, editor. This means it is a tool to allow a team to build a website together. It is integrated with login tools so that pages can only be created, or edited, by people with a login. Jalopy websites have a private index through which the site is edited. They also have a public index that is automatically updated when new pages are added, or details changed. Jalopy means - a dilapidated old vehicle. Any program I create is bound to creak around the edges a bit, so I thought it was appropriate. It also ends in 'py', which is a tradition for projects written in Python.

Jalopy is currently at 'alpha' stage. It all works, as far as I can tell anyway, but there's lots that can be done to improve it. It has been created for Funding Web. There are three different teams working on funding issues, for a charitable project I'm involved in - the Jesus Centre. Funding Web will allow us to share information about who's doing what, and what the results are. The online editor we use is called Kupu. It allows non technical users to edit the pages, including tables etc.

Currently Jalopy is only suitable for small projects. Each 'website' is an index page, with webpages inside a single directory. One install of Jalopy allows many websites though, and they can share a user base (or not) through configuring login tools. There are many things Jalopy could become - see TODO and Wish List. For example, it is a very nice way of giving people their own section in your website. The look of Jalopy is set through HTML templates, so you can set it up to fit in with any website.

It is not necessary to understand/touch python to use Jalopy on your website. It does need Python 2.2 or later installed on the server. Everything about Jalopy (and login tools) can be configured through simple text config files, and the HTML templates. See the section on installing Jalopy for the full low down, including a detailed example of setting up a new Jalopy website.

Because of the way Kupu works, Jalopy will only work with Mozilla/Firefox or Internet Explorer browsers.

Jalopy is integrated with Kupu. Kupu is written in javascript and does all the 'client side' work. Jalopy is the python backend that sits on the server. When you are editing your webpage you are using Kupu - everything else (saving the page, sending the right page to edit, generating the indexes) is Jalopy.

2   Downloading

The Jalopy and logintools package can be downloaded from Jalopy and logintools Zip (436k).

You can try out an online demonstration of Jalopy and logintools at Jalopy and login demo.

The demo has a guest login. This means you can create and edit pages. There is also a guest admin login, which can delete pages.

3   Installing Jalopy

The current distribution Jalopy is a single zipfile. This contains Jalopy, Kupu, logintools and all the modules needed. It is already setup for a single website called 'jalopy'. Installing Jalopy is really just a case of personalising it so that it looks how you want it to.

The zipfile contains three directories - 'kupu', 'jalopy' and 'cgi-bin'. These should be unpacked into the root directory of your website.

3.1   Basic CGI Stuff

All the folders in the zipfile can be installed into your root web directory. Give 'jalopy.py' (in the 'cgi-bin/jalopy' folder) permissions '755' and then point your browser to http://www.yourhost.com/cgi-bin/jalopy/jalopy.py and it should work ! You may have to do the usual '#!' magic with the first line of jalopy.py. In many cases '#!/usr/bin/python' will work, but for some people '#!/user/bin/env python' might be right. If you are using a windoze box then the right file associations will need to have been made. Oh, and don't forget that python files ('.py') must be uploaded to your website in ASCII mode rather than binary mode. I recommend Filezilla as a good FTP client.

If you can't install these directories into the root directory of your website then setting up Jalopy is a bit more of a challenge. This will be the case if your website address is not something like - http://www.somedomain.com, but is more like http://www.somedomain.com/somepath/. Some of the paths we'll use are hardwired into the Kupu files. This means that those paths will all need the somepath/ bit adding to them before Jalopy will work at all. See the section Edited Files in the Kupu Distribution for the details of this. The path will also need correcting in the config file.

If you have a straightforward setup then you should see a page that displays a Please Login message, with a form to login. It should also tell you there is a guest login, with the username guest and the password pass1.

3.2   Jalopy is Two Applications

This first page you are looking at is not actually generated by Jalopy at all. The Jalopy application is actually protected by a tool called Login Tools. This provides a way of doing user account management and authentication. The first thing that Jalopy does is check that anyone trying to access it has a login. This means that you can restrict the people able to modify your website to a selected team. You can switch this off in the config file. Like Jalopy, Login Tools uses HTML templates for it's look. To configure the appearance of Jalopy you need to configure Jalopy and Login Tools. Luckily both of these are straightforward processes. For details of configuring login tools, see the section Configuring Login Tools or go direct to the Login Tools documentation.

The easiest way of illustrating how to set up a Jalopy website is to take you through the process. With Jalopy installed you can have many editable websites. We call this having many 'instances' from a single install. To setup your first one you can either create a new instance or just edit the default jalopy one. The two processes are very similar, so I'll describe how to create a new instance.

4   Creating a New Instance

First we need to choose a web location for our new website. Let's call it 'mywebsite'. By the way, experimenting with this offline is much easier than having to upload it to a real website everytime. For windoze I recommend the Xitami server running as 'localhost'.

Hint

If you are happy to just hack into the default setup, then you could skip straight to The Config File section. You will also need to know about the Template Files, and also check out Configuring Login Tools.

Every Jalopy instance needs :

It is possible to omit, relocate, or share the last two of these items - but we won't worry about that here. The next list are the steps we about to perform. It is also a good summary for those who want to cut straight to the chase. :

  1. Choose a location for your website and create a folder for it - Create the Website Folder
  2. Create a folder for your website inside cgi-bin - Create the cgi-bin Folder
  3. Copy into it jalopy.py and jalopy.ini and the following subdirectories 'jalopy', 'users' and 'logintemplates' - Copying the Files In
  4. Edit the 'thesite' variable in jalopy.py and rename the 'jalopy' subdirectory and 'jalopy.ini' to this value - Setup thesite Name
  5. Edit the config file (previously known as 'jalopy.ini') - especially 'webloc', 'webpath', and 'templatefile' will need changing - Edit the Config File
  6. Go into the 'users/' subdirectory and edit 'config.ini' - particularly 'cookiepath' will need to be changed - Editing the Login Tools Config File
  7. You can now edit the HTML templates in the 'logintemplates' directory and what was the 'jalopy' directory, particularly you will want to edit/rename the file 'jalopytemplate.html' - Editing the Templates

Although that seems like a lot, most of it is just copying the templates and renaming them for your website ! In this tutorial we will create a Jalopy website called mysite.

Note

Once I have a script that automates this process it will be possible for you to automatically allocate an area of your website for users to edit themselves. This is akin to website content management systems like 'genesis', but with the kupu editor built in and automatic index generation.

4.1   Create the Website Folder

In the initial distribution this is the top level folder called 'jalopy'. It has a subdirectory call 'stylesheets' which contains two files - 'default.css' and 'indexes.css'. 'default.css' is the css file for the webpages we create. 'indexes.css' is the css file for the index pages.

To create the folder for your website, copy the 'jalopy' folder and rename it 'mysite'. It won't have any files in it until you create a page from the editor. When you create your first page the public index file will also be generated.

4.2   Create the cgi-bin Folder

Next we need to create a folder inside cgi-bin. This will contain a script and all of our templates. Create a new directory inside 'cgi-bin' called 'mysite'.

4.2.1   Copying the Files In

Having created the folder 'cgi-bin/mysite' you need to copy into it various of the files from the 'cgi-bin/jalopy' subdirectory. Copy the following files and directories :

  • 'jalopy.py'
  • 'jalopy.ini'
  • 'cgi-bin/jalopy/jalopy' directory (these are the index and page template for your website)
  • 'cgi-bin/jalopy/users' directory (these are the user config files)
  • 'cgi-bin/jalopy/logintemplates' directory (templates for Login Tools)

4.2.2   Setup thesite Name

Jalopy references each site by a parameter called 'thesite' internally. This is the site name, so in our case it's 'mysite'. The first place to change it is inside our copy of jalopy.py - 'cgi-bin/mysite/jalopy.py'. The line that reads thesite = 'jalopy' needs to be changed to thesite = 'mysite'.

Jalopy always looks for a config file with the site name followed by '.ini'. This means we need to rename 'jalopy.ini' to 'mysite.ini'. It will always look for the page templates in a subdirectory with the same name as our site. 'cgi-bin/mysite/jalopy' should be renamed to 'cgi-bin/mysite/mysite'.

4.3   Edit the Config File

The file that is now called 'mysite.ini' is the config file for our Jalopy website. Here we need to tell Jalopy where it can find a few files and also setup some defaults. For a full explanation of all the values go to, the config file section.

The first one we need to change is 'webloc'. As our website is in a directory called 'mysite', in the top level directory, then this value should be set to '/mysite/'. This value is put into webpages we create.

Next we need to change 'webpath'. This value tells our jalopy.py script the relative path from itself to the webpages we will be creating. This means going up to directories and then into the 'mysite' web folder. Set 'webpath' to '../../mysite'.

Lastly, when we look at the HTML templates we are going to rename our basic page template from 'jalopytemplate.html' to 'mysitetemplate.html'. This means we need to change the 'templatefile' to 'mysitetemplate.html'.

Because we have kept the same directory structure when we copied over the users folder and logintemplates folder etc, we can leave most of the rest of the values as they are. You can change some of these later to allow websites to share users or template files, or even share users with another application, if you want.

You might want to change the first few values though. These are the default names and title of new pages we create. At the moment they say things like 'A New Jalopy Web Page' etc. We could change it to 'A New Web Page for My Site'.

It's worth noting that Jalopy will also need access to our editor template files. These are in the 'cgi-bin/jalopy/templates' directory which we haven't copied across. The value in 'templatedir' should already be set up to find these. These files don't need editing and are shared between instances.

4.3.1   Editing the Login Tools Config File

The next step involves editing another config file. This is 'config.ini' in the 'cgi-bin/mysite/users/' directory. Most of the values there are actually to do with configuring login tools rather than Jalopy. There is another section devoted to things you might like to change in login tools. You will, however, need to change the 'cookiepath' value.

Login Tools currently works by setting a userid cookie. This records the fact that the user is logged in. In order to stop different cookies from different instances of Jalopy interfering with each other we set a unique identifier for each site. This is currently the web path to the directory of the install. In our case this is '/cgi-bin/mysite/' - so this is the value we set in cookiepath.

Warning

Login Tools was developed for Jalopy. It is also at an alpha stage of development (although fully working). One thing that is quite likely to change is the use of cookies. It is likely that in the next update we will switch to using a name as an identifier rather than the path. This will allow multiple instances in a single directory. This should only mean that the cookiepath value becomes something like 'cookiename' and we set it to 'mysite', but it will require a change (unless I put a backwards compatible hack in of course).

The Login Tools config file is not complicated. You are likely to want to change the admin email address, the message sent to new users who sign up, and also whether or not new users can sign up. These things are all down to your own needs and preferences. By default there are two users already setup, guest and admin. Read the Login Tools manual for the full details of how to create and edit new users. If you login as admin you can easily create new users. You can change the login name of the main admin user by renaming the file 'admin.ini' in the user directory. By using the 'edit account' option you can change the password away from the default 'pass1'. If you want to you can get rid of the guest login by deleting 'guest.ini' from the users directory.

Having set cookiepath, your new Jalopy website will actually work. It will still have the default settings and all the default templates, but it will work and you can log in to it. If you're running Xitami (or any other server as localhost), and have been making these changes in the 'webpages' and 'cgi-bin' folder, then you can go to http://127.0.0.1/cgi-bin/mysite/jalopy.py and see it. The next stage is the important one - customising the HTML templates so that it is your website that is being edited.

4.4   Editing the Templates

Of course as soon as you log into it, you will see that it is exactly the same as the default 'Jalopy' website that Jalopy shops with. This is hardly surprising, as we've created it by just copying all of the default pages. You customise the look of your website by editing the HTML template files. When you edit them there are certain values that need to be present in the template - otherwise it won't work properly. This section will briefly tell you what files need editing. For a more in depth look, see the Template Files section.

There are three types of templates :

  • The two indexes - the public index and the private index
  • The template page you are given to start with when you create a new page
  • The template files for Login Tools

(There are a few other template files that you needn't worry about - see Template Files if you want the gory details.)

4.4.1   The Indexes

As has been already mentioned, every Jalopy website has two index pages [1] . These two files are located in the folder we have renamed 'mysite' - 'cgi-bin/mysite/mysite/'. They are called 'publicindex.html' and 'privateindex.html' and you shouldn't rename them.

Both these indexes are used by Jalopy as the basis of the index pages, the table of links is inserted into these templates. As new pages are created, or the details edited, the table changes. This is done by having certain values in the template pages that are swapped over for the table and other links. It uses the same basic system as Login Tools. Where you see a value that looks like **some name**, it is probably a marker that is dynamically swapped when the page is generated.

In 'publicindex.html' there is only one of these. If you look in the HTML you will see **table of links**. This must appear somewhere in your page for the system to work. You can change whatever else you want about the appearance of the page. It's worth noting that the css page it references (stylesheets/indexes.css) is relative to its final location. This index will become (in our example) the file - '/mysite/index.html'. The css file that it uses by default is at '/mysite/stylesheets/indexes.css'. There's no reason not to change this. See the note below about the character encoding though, this is relevant to both publicindex and privateindex.

'privateindex.html' contains several values. This is because it also contains links to things like 'log out', 'edit your account' and also 'admin screen' if the user has admin rights. It also has the form used to create new pages. You must have **table of links** and **createpage**. To make sure the other links are included you could just copy the whole section :

<p>To log out - <a href="**logout**">Click Here</a>.</p>
<p>To edit your account details - <a href="**edit account**">Click Here</a>.</p>
<!-- **admincommstart** <p>To enter the admin menu - - <a href="**admin menu**">Click Here</a>.</p> **admincommend** --> 

(The comments are removed if the user logged in has admin rights)

'publicindex.html' does have a link to edit pages - this is a link back to jalopy.py. It's not added by jalopy, so if you want it to work for your site you'll need to change 'href="/cgi-bin/jalopy/jalopy.py"' to 'href="/cgi-bin/mysite/jalopy.py"'.

Note

The two indexes 'publicindex.html' and 'privateindex.html' need to be in 'UTF8' character encoding. This means they ought to have the line <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> in their head element. You should also make sure that they are saved with a 'UTF8' encoding from whatever editor you use. If this requirement causes problems I may change it.

4.4.2   The Template Template

When you select 'create new page' from the private index, the Kupu editor loads. It also loads a default page for you to edit, with whatever title you gave it. This default page is just a template - and you may well want to edit it. This file is in the same directory as the index pages - 'cgi-bin/mysite/mysite/'. It was originally called 'jalopytemplate.html'. You may have already renamed it 'mysitetemplate.html'. Whatever name you give it must be the same as the value given to the keyword 'templatefile' in 'mysite.ini'. See Edit the Config File to remind yourself about this.

This template page is slightly different to the other templates we've looked at so far. This is because parts of it's structure are important to Jalopy. It contains several meta tags, as well as values, that Jalopy is going to use. Because of this it is recommended that you only edit the section between the title and the '</body>' tag. That means you should leave the whole of the first section as it is :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
 <head>
 <title>**Document Title**</title>

 <!-- headers to prevent the browser from caching, these *must* be provided,
        either in meta-tag form or as HTTP headers -->
 <meta http-equiv="Pragma" content="no-cache" />
 <meta http-equiv="Cache-Control" content="no-cache, must-revalidate" />
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

 <!-- some meta data, customizations could build property tools that
        edit more of them -->
 <meta name="Publisher" content="**publisher**" />
 <meta name="Description" content="**description**" />
 <meta name="Author" content="**original author**" />
 <meta name="Last-Edited-On" content="**last edited on**" />
 <meta name="Last-Edited-By" content="**last edited by**" />
 <link rel="stylesheet" href="**stylesheet**" type="text/css" />

 </head>
<body>

<h1 align="center">**Document Title**</h1> 

The file is saved with the character encoding UTF-8. You must keep it as a UTF-8 file. Anything else will cause problems. Other than this you can edit the entire rest of the body of the text. Note that the stylesheet location is included in the part that you shouldn't edit. The stylesheet used is '/mysite/stylesheets/default.css'. You are welcome to edit that, but you should leave the different table styles intact if you want the table style selector to work in Kupu. I may be adding support for enhanced kupu style handling in a future release.

4.4.3   Login Tools Templates

Login Tools is a whole framework for user login and authentication. This means that it offers login and edit account and account administration facilities. All the screens it displays are also done from HTML templates. It uses the same **some value** system as jalopy in it's templates. The actual templates are all located in the 'logintemplates' directory - 'cgi-bin/mysite/logintemplates/'. You may only want to edit the 'login_page.html' and 'newlogin_page.html'. See the Configuring Login Tools section for more details.

And there you have it - you are now ready to start creating content, or inviting other people to join you, and getting them to create content with you ! Once you have created your first page, you will be able to access the public index which will be at - http://127.0.0.1/mysite/index.html

Note that if you have followed this example you now have two websites setup - the default jalopy one and 'mysite'. The process we have gone through is 'creating a new instance' of a jalopy website. You can have as many as you like running from one install. You could switch off the default one by renaming (or deleting) 'cgi-bin/jalopy/jalopy.py'. Alternatively, if you only need one jalopy instance, you could just edit the default one instead of creating a new instance.

5   Using Jalopy

Using Jalopy is very straightforward. If your cookie is still valid from a previous session then you won't need to login again. Once you are in, you will see the description under the 'About Jalopy' title [2], followed by a title 'Links'. The first time your website is used, this will say 'None Yet, Sorry'. This is because you there aren't any pages yet. Once you have created some pages you will see a table of them here - with links to various options for each page. There are also a couple of other things you can do. There are basically five different types of operation.

  1. Create New Page
  2. View Page
  3. Edit Page
  4. Change Page Details
  5. Using the Login Tools features

5.1   Create New Page

Below the links section is the 'Create New Page Form'. You can give the page a name, a title, and a description. You'll see the default ones in the form entry boxes. These can all be edited later. The page name is the short name that appears in the table of links, as does page description. The page title will appear on the title bar for that page (surprise !) and also as big heading on the page you are editing. When you hit the 'Create Page' button you are whisked magically to the editor page.

This then loads the Kupu editor. Kupu is made of several javascript scripts. Over a very slow connection it may take thirty seconds or so to load, the first time. You can then start editing the page - including creating headings and tables and adding links etc. Kupu is very easy to use, but there may be more about it's features in the Kupu the WYSIWYG Editor section.

To save the page use the little disk button on the top left of the editor area. If you hover the mouse over any of the other buttons it will tell you what they do. When the page is saved, a new entry is made into the links table and you are taken back to the main index. The page itself will have a link back to the public index added to it at the top. This makes the public website easier to navigate.

5.2   View Page

Once you have pages in your table of links, you will see the 'View Page' option. This link actually takes you out of the private index and into the public area of the website. You can use the back button to get back to the main index page. The link at the top will take you to the public index.

5.3   Edit Page

This takes you back to the editor screen. It then loads the relevant page for you to edit with Kupu. A bug in IE means that currently you can't (yet) edit the title or description from here. (It works fine in Firefox/mozilla). You should edit these from Change Page Details.

5.4   Change Page Details

This is the 'Edit Details' option from the index table. It allows you to edit the page name, title and description. If you are using IE, this is currently the only way of editing the name and description. Whether you are using Mozilla/Firefox or IE, this is the right way to change the 'page name' that appears in both the public index and the private index.

This menu also allows you to delete pages. The default setup is that only administrators can delete pages, although the owner of the website can configure it to allow anybody to do it.

5.5   Using the Login Tools features

Through the main index you also have various options to do with logins. As a user you can logout or edit your account details. This includes your password. If you are an administrator you can also edit other user accounts and create/invite new users. Administrators can also edit the settings for Login Tools itself from here. It is very straightforward - but for more details please read the Login Tools docs.

6   The Config File

The config file is the file referred to in Edit the Config File. In the normal distribution it is the file 'cgi-bin/jalopy/jalopy.ini'. Whenever you create a new instance you will need to copy and rename this file. In the example above we created a new site called 'mysite', so this file became 'mysite.ini'. The renaming is so that eventually we can have lots of installs in the same directory - not quite ready yet though ! The config file controls various aspects of Jalopy, as well as telling it where to find all the files that it needs.

Note

The config files used by Jalopy and Login Tools are read using a module called ConfigObj. They are basically like INI files - simple keyword-value pairs. ConfigObj has lots of other properties that we don't use here - like sections, list values etc. If you need to read (or write) config files from Python, it's well worth having a look at.

If you look in the config file (with any standard text editor), you will see various keywords and the values they are set to. These can be divided into simple groups :

6.1   Editor Page Values

Ok, so this is a group of one ! When you edit the page there is a big heading and the page has a title. You can configure what this says by setting the value of editor title. :

'editortitle'     = 'Jalopy Editor Page - Using Kupu'           # title for the editor page

6.2   Default Page Values

When you create a new page, you can choose what name it will be created with, give the page a description, and give it a title. There are three keywords that determine what the default values for these properties will be. :

'deftitle'     = 'A New Jalopy Web Page'           # default title for new pages
'defdescript'  = 'A spanking new jalopy page.'     # default description for new pages
'defname'      = 'A New Page'                      # default name for new pages

6.3   Paths and Locations

The most important set of values to get right are the ones that tell Jalopy where to find the files and directories it uses. It needs two sets of values. It needs to know the 'filepath' to various places. These will usually be expressed as a relative path from the main script. The main script is 'cgi-bin/jalopy/jalopy.py' by default. In the example, we made it 'cgi-bin/mysite/jalopy.py'. The next sets of values are web locations. This is because Jalopy needs to put certain locations into the webpages it creates - e.g. the location of the stylesheet. In general if the name of a keyword ends with 'path', or 'dir', it is a file path. If it ends 'loc' it is a location and will be part of a url rather than a filepath.

Warning

Jalopy assumes that the Kupu files are located in the weblocation '/kupu/'. This is because this path is used within the kupu files themselves. If this isn't the case - e.g. they are in something like '/homepage/kupu/' - then this path must be changed in a couple of files. See Edited Files in the Kupu Distribution.

Anyway, here are the values. :

'webloc' = '/jalopy/'                        # web location of pages
'webpath' = '../../jalopy/'                  # file path from script to the html files
'kupupath' = '../../kupu/'                   # filepath to the kupu directory - 
                                             # if the web location of this directory *isn't* '/kupu/' 
                                             # then changes to kupubasetools.js and makepage.py must be made
'finalstyleloc' = 'stylesheets/'             # final location of stylesheet relative to web pages
                                             # must be *relative* to webloc
'templatedir' = '../jalopy/templates/'       # the directory that the jalopy templates are stored in
'userdir' = 'users/'                         # the directory containing the user login files. 
                                             # Set to '' to not require a login
  • webloc refers to the final web location of the website we are creating.
  • webpath is the relative path from our script to the directory the web pages will be saved in.
  • kupupath is the relative path from our script to the kupu directory
  • finalstyleloc is the relative path from the web pages to the directory their stylesheet is in
  • templatedir is the directory containing the Jalopy editor templates
  • userdir the directory containing our user files. Applications sharing a user directory share a userbase. If you don't want to require a login, this value can be set to ''.

As we've seen from Edit the Config File, a lot of the default values here are probably ok.

6.4   Filenames

These values tell jalopy the filenames of various files we use. :

'stylesheet' = 'default.css'                    # filename of the stylesheet used for new files
'publicindex' = 'publicindex.html'              # file in the template directory that has the template 
                                                # for the public index page
                                                # used to create index.html in the webloc folder
'privateindex' = 'privateindex.html'            # file in the template directory that has the template
                                                # for the private index page 
                                                # used to create the main index

'templatefile' = 'jalopytemplate.html'          # the name of the template file in our directory

The only ones you might want to edit are stylesheet and templatefile. The stylesheet is the stylesheet for the webpages. It should be in the directory referenced by 'finalstyleloc'. The template file is the basic page used to create new webpages. You may want to rename this depending on the name of your website.

6.5   admindel

The last value is a group all by itself. :

'admindel' = '2'          # the minimum admin level a user must have before 
                          # they are able to delete pages. 
                          # Set to 0 to let anyone delete

By default only administrators can delete pages. The minimum admin level is set by this value. If you want anyone to be able to delete pages you can set this to 0. If you look in the WISH LIST you'll see that I intend to allow non-admin users to delete pages they have created.

7   Kupu the WYSIWYG Editor

This project is built on Kupu. Kupu is an online WYSIWYG editor, written entirely in javascript. This means that webpages can be easily edited by non technical users. There are a few limitations, some of which are down to Kupu and some of which I will have to sort out. You can see a list of them at KUPU PROBLEMS.

Greater functionality will be added as I add image drawers and link drawers. These allow for an easy way of adding links and images into pages - without having to understand HTML. Kupu can add headings, tables, links, and more. It's all pretty obvious really.

XXXX add or write a user guide to Kupu. Anyone want to take this on ? See http://kupu.oscom.org for some links to a couple of brief visual introductions.

Jalopy is currently built on Kupu 1.1.1. Very shortly Kupu 1.2 will be released (it may even be ready by the time you read this) and incorporated into Jalopy.

Kupu isn't the only online WYSIWYG editor available. Some others include TinyMCE, HTMLArea, and FCKeditor. Kupu is one of the nicest looking, but not necessarily the most fully featured. I will evaluate continued use of Kupu before I do the next major update. A lot of Jalopy is tailored round Kupu, so changing is non-trivial (but not too difficult).

8   Configuring Login Tools

Login Tools is a python module for use with CGIs. It is a framework that provides user logins and authentication. It includes user account editing and an account administration interface. It is easy to configure with a simple config file like the one Jalopy uses. It also uses HTML template files, so you can adjust it's appearance by editing them. For the full lowdown see the Login Tools homepage. This section covers enough of configuring Login Tools to use it within Jalopy.

Login Tools uses cookies for it's logins. If you don't have cookies enabled then it simply won't work - or at least you'll have to login in between each page access.

Login Tools stores a single config file for each user. These files are stored in the user directory. There are a few files in here that aren't users. These are 'default.ini', 'config.ini', and 'temp.ini'. The 'config.ini' is the main config file for us. We'll look at that in a minute. The other two files that come as standard are 'guest.ini' and 'admin.ini'. These are the two default users, guest is a guest login and admin is a login with admin rights. They both start with the password 'pass1'. Unless you intend to leave the guest login available, it is recommended that you change the name and passwords on these accounts before deploying your application.

There are three ways of creating new users. They can sign up for an account from the login screen, an administrator can just create a new user, and an administrator can 'invite' a new user to join. It is possible that you don't want new users to be able to sign up for accounts. This can be switched off in the config file.

8.1   Editing the Config File

The config file for Login Tools is 'cgi-bin/jalopy/users/config.ini'. It is similar to the Jalopy config file and is also read in using ConfigObj. You may want to edit most of the values in this file.

8.1.1   templatedir

This is the directory that contains the templates for Login Tools. The path should be absolute or relative to the calling script. These are the files that come in the 'logintemplates' directory. If you're editing the default website, or have copied the 'logintemplates' directory, you can leave this as it is. See Login Tools Templates for the details of what the files in here are for.

8.1.2   cookiepath

For every Jalopy website, with a separate userbase, you need a unique cookiepath so that the browser can keep a track of which cookie is for which website. The cookiepath is the path on the server that is used to access the application. The default one is '/cgi-bin/jalopy/'. In the example we created a new website in a subdirectory of 'cgi-bin' called 'mysite'. This made the cookiepath '/cgi-bin/mysite/'. I will probably soon change this to referencing cookies by name.

8.1.3   adminuser

Every Login Tools setup will have one main admin user. It's not possible for another admin user to delete this account. If you change the name of the default admin login then you need to change this value as well.

8.1.5   adminmail

If you put an email address here, Login Tools will email you when a new user confirms their account. Set to '' to switch this off.

8.1.6   Email Values

The last two values in 'config.ini' are used when sending an email to a new user who has just signed up or been invited. The keywords 'email_subject' and 'email_message' correspond to the subject line and body of the message sent. (Surprisingly enough). You will want to change them to something appropriate for your website. If they were invited by an administrator then the email will also tell them their login name and initial password. You can use triple-quotes to surround this value if it spans multiple lines.

8.2   Login Tools Template Files

Using the Login Tools template files you can modify the look and feel of the Login Tools screens. You will almost certainly want to modify the default login screen. For the full reference on this see the Login Tools docs - 'Template Files and Values' section.

The templates for Login Tools are divided into html files and text files. The html files tend to be the main pages, whilst the text files are forms that get inserted into the pages. The template files are done in the same way as the Jalopy template files. This means that there are some important values used by Jalopy. These all tend to be in the form **some name**. You can edit the look and appearance of these pages, but should leave these values in place. Below is a brief list of the HTML files and what they are for.

  • login_page.html - This is the main login page.
  • newlogin_page.html - The page shown whilst signing up for a new login.
  • login_done.html - The page shown when a user has finished signing up for a new login.
  • edacc_page.html - The page shown whilst editing your account.
  • admin_page.html - The basic page used for all the admin screens.

8.3   Sharing a Userbase

It is possible that you will want several Jalopy sites to share the same users. This could be because you want to divide a website into several sections, or because you want users to only need one login across all the different websites/programs that you operate. The way to do this is to have only one 'users' directory. Any applications (including Jalopy websites) that share the same user directory, will share users and a config file. This means that a single login name/password will work in all the applications. Because the websites share the same config file they will also share the Login Tools templates.

Configuring the websites to share a userbase is really easy. In the Jalopy config file you simply set the 'userdir' value to be the shared directory. See the Paths and Locations section. When you setup multiple instances you do need to ensure they all have a unique cookie path though. See - cookiepath.

You could use this to setup a much larger website with several sections. Each instance (each Jalopy website) is one section. You would need one index page with links to all the sections, and then a link back to that on all the index pages for the sections.

10   Dependencies

By default Jalopy comes with the modules it's dependent on. These are currently : logintools, configobj, caseless, listquote, dateutils, dataenc, pathutils and cgiutils. The normal situation is to put all these modules in a folder called modules.

The home of these modules is http://www.voidspace.org.uk/python/modules.shtml They are all very useful in their own right. These modules include :

  • logintools - adding user login management and authentication to Python CGIs
  • configobj - easy reading and writing of config files
  • caseless - a case insensitive dictionary, list, and sort function
  • dataenc - timestamp and encode values for including in form fields and cookies
  • dateutils - functions for dealing with dates, particularly useful is the date to julian day number
  • listquote - reading lists and quoting/unquoting elements
  • cgiutils - a few standard functions for use with CGI (including form handling and sending email)
  • pathutils - basic file and path handling functions.

These will only work on Python 2.2 or more recent.

If you are not using Login Tools, i.e. your 'userdir' value in The Config File is set to '', then you don't need the logintools directory or 'login.py'.


11   Template Files

Jalopy has two types of template files, as well as the Login Tools templates. The first type are the basic templates that we came across in Editing the Templates. They come by default in 'cgi-bin/jalopy/jalopy/', which will have changed to 'cgi-bin/mysite/mysite/' if you followed the example. The other sort of templates are stored in 'cgi-bin/jalopy/templates/' and actually make up the editor page and forms. It is normal to edit the basic templates, but you probably don't need to edit the form and editor templates.

11.1   List of Template Files

11.1.1   Basic Templates

  • jalopytemplate.html - The template page used to create new pages
  • publicindex.html - The index page for the website
  • privateindex.html - The index page for editing the website
  • editdetails_page.html - The page used for editing page details

11.1.2   Form and Editor Templates

  • create_form.txt - The form used to get the details for a new page
  • editdetails_form.txt - The form used to change the details of a page
  • form_head.txt - The head of the editor page
  • form_foot.txt - The foot of the editor page

11.2   Values in the Templates

Most of these template files are meant to be edited by the user. This allows a native look and feel for the editor and the basic template pages. In some of the files there are various values that Jalopy uses to fill in paths etc. These values must be in the right place in these files. It should be obvious where they are by looking at the examples supplied. If you edit any of the forms, you must take care to leave all the form fields in place.

11.2.1   jalopytemplate.html

  • **Document Title** Document Title - entered by person who creates page.
  • **stylesheet** Path to Stylesheet - from template to normal stylesheet, needs to be changed when saved.

The following meta values aren't yet used.

  • **publisher** Jalopy plus version string
  • **description** Description - entered by person who creates page
  • **original author** Name of person who created page
  • **last edited on** Date of last change
  • **last edited by** Name of person who made last change

11.2.2   publicindex.html

  • **table of links** the public index table

11.2.3   privateindex.html

  • **table of links** the private index table
  • **createpage** the form used to create a new page
  • **logout** the link used to logout
  • **edit account** the link used to go to the edit account screen
  • <!-- **admincommstart** Used to obscure the admin link for non admin users
  • **admincommend** --> ditto
  • **admin menu** the link to go to the admin menu (admin users only !)
  • **username** Used to welcome the user if we are using logins
  • <!-- **commstart** Used to obscure the welcome message if we don't have logins
  • **commend** --> ditto

11.2.4   editdetails_page.html

  • **username** Automatically replaced with username
  • **edit details table ** Replaced with the edit details form
  • <!-- **message** --> Used to display messages to the user in case of errors

11.2.5   form_head.txt

  • **page title** page title
  • **menu link** link to the main index
  • **makepage** path to the makepage script
  • **filename** The filename of the page being edited. For new files this will be 'new'.
  • **pagename** The name of the page being created. Only used for a new file.
  • **path** The relative path from the script location to the kupu directory - this should also be added to 'href="' and 'src="' references (currently done in makepage.py - could this be done in a distribution ?)
  • **the site** The site we are editing a page for.

11.2.6   form_foot.txt

  • **edit file** path to file to be edited - calls the jalopy script which sends a copy of the page to be edited

11.2.7   create_form.txt

  • **makepage** path to the makepage script
  • **page title** default page title
  • **description** default description
  • **page name** default page name
  • **the site** site the form is for

11.2.8   editdetails_form.txt

  • **makepage** path to the makepage script
  • **the site** site the form is for
  • **filename** filename being edited
  • **page title** page title
  • **description** description
  • **page name** page name
  • <!-- **del start** delete button comment start
  • **del end** --> delete button comment

12   Edited Files in the Kupu Distribution

Jalopy is built on files from the 'common' directory of the standard Kupu distribution. It is modified slightly to work with Jalopy - mainly turning an HTML page into our editor templates. This is a reference of the files from this distribution that I have had to edit, and how they have been changed. :

urls need to be manually edited in - kupustyles.css
Done with a search and replace - url(" becomes url("/kupu/

The editor page kupuform.html is chopped in two to form editor_head.txt and editor_foot.txt
It is edited to add form fields and variables to substitute.
Changed kupuimages/kupu_icon.gif to /kupu/kupuimages/kupu_icon.gif - may alter later to a different default image.

The XML files need the full path /kupu/ adding.
These will need to be dynamically generated anyway.
The XSL file has a single reference to the css file that I have changed in the same way.

image.html and link.html need references to the stylesheet sorting

kupubasetools needs - kupupopups/link.html and kupupopups/image.html sorting

Note that the changes above are only true if the weblocation of the Kupu directory is '/kupu/'. On some sites it might be something like '/homepage/kupu/'. The locations above that include '/kupu/' will have to be changed appropriately. You will also have to change a single value in the 'cgi-bin/jalopy/makepage.py' file. This is the line in the 'readconfig' function - weblocmod = '/kupu/'. (Line 114 in version 0.5.1a).

13   KUPU PROBLEMS

This is a description of issues and problems that are specific to the Kupu editor. Many of the problems are 'browser dependent', that is they may be a problem with one browser, but not another. Kupu will only work with mozilla browsers or internet explorer (minimum 5.5). No other browsers are supported. Javascript support is obviously essential if you want to use Kupu at all. If user logins are turned on, then cookie support will also be essential. Firefox is the recommended browser for Jalopy. Kupu is still a work in progress. It is already the best online WYSIWYG editor I've ever seen - but it continues to be developed and improve. In fact some of these problems may already be resolved by the time you read this.


14   TODO

This TODO list is the list of features/fixes that I am likely to actually get round to at some point. They aren't in order of priority, but some are obviously more important than others. If any particularly matter to you, or you have suggestions for things that ought to be on the list, then let me know. If you wanted to tackle any yourself I can give you lots of help. Some of the items can already be done, either through the templates or just by writing external functions - but they ought to be built in.

15   Wish List

This is the part of the TODO list that I will only work on if I need them, or if someone pesters me for it. If you want anything from this list let me know, and I'll try and move it up the list. As above, if you wanted to tackle any yourself I can give you lots of help.

16   ISSUES

These 'issues' are things that don't work as they should. Some of them are bugs, some of them have solutions, and some aren't very important but are worth being aware of.

17   Changelog

Warning

Although Jalopy works it's alpha quality. The project it was developed for got shelved Sad - much to my annoyance. This means I'm not currently working it.

There are lots of obvious improvements needed - and the code needs refactoring to get rid of the horrible global config stuff. It should all be implemented as a single class.

If anyone wants to do this then I will provide every help I can. Alternatively, if anyone wants to sponsor new features (like archiving changes and the ability to undo them) then they should email me on fuzzyman at voidspace dot org dot uk.)

17.1   2005/09/21 Version 0.6.0

Changes to be compatible with Pythonutils 0.2.2

Updated to Kupu 1.3

17.2   2004/12/25 Version 0.5.1a

IE strips part of "http-equiv" meta tags. Fixed in makepage.py.

17.3   2004/11/29 Version 0.5.0a

First release into the wild. Packaged along with logintools.

Works OK, lot's of functionality still to add.

18   License

Jalopy is licensed under the BSD license. This is a very unrestrictive license - and comes with the usual disclaimer. This is free software - test it, break it, just don't blame me if it eats your data ! (If it does though, let me know - and I'll fix it (try to !) so that it doesn't happen to anyone else Smile

Copyright (c) 2003-2004, Michael Foord
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:


    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

    * Neither the name of Michael Foord nor the name of Voidspace 
      may be used to endorse or promote products derived from this
      software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You should also be able to find a copy of this license at : BSD License

If you use this project, please donate a few dollars to the Jesus Centre project and it's work with the poor.




Certified Open Source

[1]This allows Jalopy to generate static HTML pages for the websites it edits. This results in a much lower load on the server. It also separates the public view from the editing side of things - the website viewers have no need to know that the website is edited/created by Jalopy.
[2]Assuming you haven't changed the layout of the private index page.