======================================= Jalopy - a Collaborative Web Project ======================================= ----------------------------- Installation and Use Guide ----------------------------- :Author: Michael Foord :Contact: fuzzyman@voidspace.org.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`_ .. _Jalopy Homepage: http://www.voidspace.org.uk/python/jalopy.html .. _logintools: .. _Login Tools: http://www.voidspace.org.uk/python/logintools.html .. _Pythonutils Mailing List: http://voidspace.org.uk/mailman/listinfo/pythonutils_voidspace.org.uk .. _Pythonutils: http://voidspace.org.uk/python/index.shtml .. _BSD License: http://www.voidspace.org.uk/documents/BSD-LICENSE.txt .. _Python: http://www.python.org .. _Jalopy: http://www.voidspace.org.uk/python/jalopy.html .. _`Jalopy and logintools Zip (436k)`: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=jalopy_login.zip .. _Jalopy and login demo: http://www.voidspace.org.uk/cgi-bin/jalopydemo/jalopy.py .. _Funding Web: http://www.voidspace.org.uk/fundingweb/index.html .. _Kupu: http://kupu.oscom.org .. _Jesus Centre: http://www.jesuscentre.org.uk .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html .. meta:: :description: The homepage of Jalopy. A collaborative web project using Kupu. :keywords: python, script, kupu, editor, javascript, cms, content, management, collaborative, wysiwyg, online, collaborate, community .. contents:: .. sectnum:: 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. 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. 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. * **Kupu** contains all the files for the kupu editor. * **jalopy** is where your public index and website pages will be located * **cgi-bin** contains two further sub-directories - **modules** a set of general purpose python modules that jalopy needs - **jalopy** the jalopy script itself *and* the config file and templates 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*. 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. 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 : * a webfolder (with the stylesheets) *jalopy/* * a config file - *cgi-bin/jalopy/jalopy.ini* * a single script to call - *cgi-bin/jalopy/jalopy.py* * a directory containing the page templates - *cgi-bin/jalopy/jalopy/* * a directory containing the user config files for everyone who has a login - *cgi-bin/jalopy/users/* * a directory containing the template files for Login Tools - *cgi-bin/jalopy/logintemplates/* 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. 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. 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'. 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) 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'. 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. 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. 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.) The Indexes ~~~~~~~~~~~~~ As has been already mentioned, every Jalopy website has two index pages [#]_ . 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 : ::

To log out - Click Here.

To edit your account details - Click Here.

(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 ```` 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. 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 '' tag. That means you should leave the whole of the first section as it is : :: **Document Title**

**Document Title**

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. 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. 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 [#]_, 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`_ 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. 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*. 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`_. 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. 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. 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 : * `Editor Page Values`_ * `Default Page Values`_ * `Paths and Locations`_ * `Filenames`_ * `admindel`_ 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 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 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. 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. 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. 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). 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. * `Editing the Config File`_ * `Login Tools Template Files`_ * `Sharing a Userbase`_ 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. 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. 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. 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. newloginlink ~~~~~~~~~~~~~~ This value has two functions. If set to 'Yes' then it is possible for new users to sign up. As well as this a link will appear on the login page. Setting it to no removes the link and makes new logins impossible, unless created/invited by an administrator. 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. 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. 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. 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. Page Links ============ When you create a new page Jalopy automatically gives it a filename. This filename is generated from the page name that you give it. Until link drawers a working you will have to use this filename as the reference when you create links. Every page that is created will have a link to the public index page added. This link is removed before editing, then put back afterwards. This is so that every page in your website has a link to the index. 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'. --------------------- 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. List of Template Files ------------------------ 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 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 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. 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 publicindex.html ~~~~~~~~~~~~~~~~~~ - ``**table of links**`` the public index table 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 - ```` 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 - ```` ditto editdetails_page.html ~~~~~~~~~~~~~~~~~~~~~~~~ - ``**username**`` Automatically replaced with username - ``**edit details table **`` Replaced with the edit details form - ```` Used to display messages to the user in case of errors 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. 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 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 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 - ```` delete button comment ----------- 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). 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. * Can't change title or description in IE ? - weird problem. Works fine in mozilla. You can change these from the 'edit details' page instead. * Table editing is much better in the Firefox browser than Internet Explorer. * Setting font colours and background colours doesn't work in Firefox. (or other mozilla browsers). * Image drawers and link drawers don't work - these need server side functionality, so I will need to do it. Currently image display doesn't work at all. This will be sorted ! * Several of the right hand mouse (context menu) options - like 'create link' - don't work reliably (and will eventually be removed). ------------------ 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. * Need to sort local image links. * Image drawers, link drawers (checkout static XML from Kupu 1.2). * Max total directory size. * Max file size for individual files being read. * Check the 'site' parameter - check makepage works standalone. I think we have some of the pages not using a site parameter at all and some using 'thesite' rather than 'site'. * The regex for sorting out local references now needs work. * Get the index table going back to 'None Yet, Sorry' when the table is empty. * Parse links added without an ``http://``. They wrongly become local links. * Check what happens to the welcome message on the edit_details page, if logins are switched off ! * Check if Kupu can handle editing pre-existing webpages (i.e. non XHTML tag soup, table layout etc) * Absence of config file for the site should raise an appropriate error message. 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. * Until logintools uses multiple cookies rather than cookiepath, we can't have separate sites in the same directory with different user bases. (i.e. can't use just makepage.py with the 'site' parameter). * Sections - multiple directories and index pages (big change). At the moment this can be implemented through having several different 'instances' from a single install, but sharing a user base. This means that the users can access all the different 'sections' and the respective index pages. New 'sections' must be manually added, they should all be linked via a single index page. Could either add support for multiple directories from a single index or just a new 'section manager' script. * Allow people to 'subscribe' to page changes, to be informed by email of changes to particular pages. Should they be allowed to delete their own pages ? (currently only admin can delete files). This means proper tracking of who created which page. * Log changes. Allow admin to automatically rollback changes - through an admin interface (would mean archiving the original before making any changes). * Email admin of any changes. (must be optional) * Move the HTML snippets in makepage into external templates. (the stuff for building the tables). * Fill in the meta-data - author, last edited on, last edited by etc. (Or just save who created the page in index_table and log all changes along with who made them ??) * Allow turn off creation of new pages - editing existing pages only. This can currently be done by just making the 'create new page form' an empty text file. Should we have levels of user privileges to allow admin to create new pages, but not normal users ? Only if someone requests it I guess. * Allow the automatic creation of new instances - with options for sharing user files or automatic creation of user directory and user files. (Automatic invite via logintools ?). This would allow the implementation of sections *and* allow webmasters to automatically give users a section in their website. (Like Genesis). * Allow a manually supplied index_table with different paths - then people could use jalopy to edit *all* their website ! Automatic indexing of several directories ? (this would need work because the description metatag and other page structure elements might be different to our current assumptions). * File uploads (images, documents etc - automatically add to the appropriate drawer) * Sort a transformation script that will automatically make the required changes from a new Kupu distribution. * When creating a new page - could have several templates to choose from. * Add a plain 'HTML Source editor' - the page in a textarea with description/title. * Rework as a single script with useful API. Do the authentication and site stuff separately. This will allow it to be plugged into other programs. * A set of smiley image drawers. * A method to insert date and time - e.g. [date], [time]. (Way of setting format in the config file ?) * Support for the Kupu CSS tool. * When a page comes in, check it is a whole and valid page. e.g. check we received an ''. 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. * Only works with javascript and cookies enabled. No way round this. * privateindex.html and publicindex.html, need different links to their stylesheets : publicindex.html is 'stylesheets/indexes.css', privateindex.html is '/jalopy/stylesheets/indexes.css'. * Giving it badly formed pages - without the meta description tags or no '' etc will cause us muchly problems. * Uncertain of the future with Kupu. Their seem to be a lot of issues that may not be resolved imminently. Would HTMLArea or FCKeditor (or TinyMCE) be more suitable for this project ? * Do we really need separate page title and page name ? * Kupu probably can't handle editing pages it didn't create - so existing content can't easily be converted over. This needs testing of course. Changelog ========== .. warning:: Although Jalopy works it's alpha quality. The project it was developed for got shelved {sm;:-(} - 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@voidspace.org.uk.) 2005/09/21 Version 0.6.0 ----------------------------- Changes to be compatible with Pythonutils 0.2.2 Updated to Kupu 1.3 2004/12/25 Version 0.5.1a ------------------------------ IE strips part of "http-equiv" meta tags. Fixed in makepage.py. 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. 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 {sm;:-)} :: 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. .. raw:: html



Certified Open Source


.. [#] 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. .. [#] Assuming you haven't changed the layout of the private index page.