QuickHP - A minimalistic webbased homepage administrator ======================================================================= Version 0.3 - 2002-05-23 - Thank you for using QuickHP! Copyright (C) 2001, 2002 Manuel Kiessling ======================================================================= This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ======================================================================= Due to the fact that my mother language is not english, it is possible or better very probably that there are several mistakes - I hope they are at least funny... if you find one, then please send me an eMail to manuel@kiessling.net. Thank you very much! ======================================================================= Requirements: ------------- You need a webserver that supports PHP version 4.1.2 with full FTP, XML and XSLT (Sablotron) support. Later versions should work, but I did not test this. Get PHP 4.1.2 here: http://www.alltheweb.com/search?cat=ftp&ftype=6&query=php-4.1.2.tar.gz My php configure line looks like this: ./configure --with-apxs=/usr/local/apache/current/bin/apxs --with-mysql=/usr/local/mysql/current --enable-ftp --with-xml --enable-magic-quotes --enable-xslt --with-xslt-sablot At least this is the part of the configure line that is needed to get QuickHP running - more options are no problem of course. You need MySQL: http://www.mysql.com Installation: ------------- Extract the archive. Now ftp-copy the files on your webserver. Let's assume your homepage is located at http://www.domain.com/ then put the files e.g. beneath http://www.domain.com/admin/ It is important that you ftp-copy the files with the same ftp-user which you will allow access to the userdata files later! You must create a directory called 'tmp', and it must be located directly beneath the 'admin' directory so you then have http://www.domain.com/admin/tmp 'chmod' this directory to 777. Now secure the directory admin with .htaccess or sort of, so only you have access to it. Add a new table to one of your MySQL databases by using the install.sql file you will find in the root directory of the extracted archive. It is a really good idea to change the password in the table afterwards! Open the config.inc.php file in the same directory with your favorite editor and change the lines 24 to 27 so they fit your FTP settings; remember that QuickHP must use the same FTP user that you used to copy the QuickHP files onto the server! Change the lines 32 and 33 so they fit your MySQL settings. In your browser, open this adress: http://www.domain.com/admin/ Log in with the credentials that are saved in the MySQL table. You see the directory listing of the directory 'userdata', and you should see 2 directories called 'templates' and 'input'. You should now create a new directory with the browse tool, not with your ftp program. Go to the form field "create new directory:" and enter 'output', then hit 'create'. You should now have these directories: http://www.domain.com/admin/userdata/templates http://www.domain.com/admin/userdata/input http://www.domain.com/admin/userdata/output so your browser should show something like this: Content of userdata/ [input] [output] [templates] These are required to run QuickHP. You will create your XML files beneath 'input', and when you start parsing, preview files will be created from the 'input' files using the templates from the 'template' directory, and then copied to 'output', and if you go live they are ftp-copied from 'output' to the live system. I give you a basic example of how QuickHP works. First, you go to the directory 'input' (just click on the name). Then you create a new file 'index.xml' using the template 'Standard'. After hitting 'create', you click on the link 'xml' in the 'Edit' column of the directory listing (you can also click on the filename instead). Then you see the xml file editor. Enter the appropriate values in the fields, enter some content (valid XML!), and hit 'Save file'. If now you click 'Start parsing', the following things will happen: The script opens one input file after the other and parses it through one of the template files, depending on the type of the input file (transitional, valid or dynamic) - the template files are located in the 'templates' folder and named 'valid_template.qpf' etc. If it is not one of the possible XML formats, it is simply copied. You can now browse to the 'output/html' folder and click on 'index.html' to see the result. If in the parsing window you click 'Copy into system', the file http://www.domain.com/admin/userdata/output/html/index.html is copied to http://www.domain.com/index.html Before you are able to copy stuff into your 'live system' with QuickHP you will have to edit the file userdata/templates/html.qpt/config.qcf To get a basic idea how to handle the XML files, take a look at the three example files in the input folder. Except for the transitional XML files, where the content of the different fields is only copied to according placeholders defined in templates/html.qpt/transitional_template.qpf, the XML files are parsed via XSLT, as defined in templates/html.qpt/valid_template.qpt. After all, this is where the real work is done - by the XSLT extension of PHP, and not by QuickHP. Giving an introduction to XSL is really not possible in this README file - you will have to find other resources for this. The important point is that the valid and dynamic XML files must really contain _valid_ XML (or, in the case of the dynamic file, it may contain PHP code or whatever scripting language your server supports, but if opened via fopen, the server-parsed result must be valid then)! Maybe the best way to see how QuickHP works is to simply parse the example files in the input folder and then look at the result in the output folder, and also look at the template files. This should get you started. The thing to remember is that: - True static XML files that will result in true static HTML files end on .xml and my contain only valid XML code - Dynamic XML files that will result in dynamic PHP (or sort of) files end on .dxml and must contain valid XML code and/or the output of possible PHP (or sort of) commands must be valid XML (e.g. 'echo date("Y:m:d")."
";' is fine but 'echo date("Y:m:d")."
";' is not) - Transitional XML files end on .txml and may contain whatever code you like (but only in the content fields, otherwise QuickHP cannot handle them), but they are not parsed through the XSL template, their field contents are only copied to the according placeholders in the transitional template file. Some more features: QuickHP has to placeholders you can use in your xml files: {qp_rootpath} always points to the root directory of all QuickHP input files. Example: If you have a file userdata/input/work/projects/index.xml (what will result in http://www.domain.com/work/projects/index.html) and you use this placeholder e.g. in a link like this: Go Home then it will result in Go Home thus pointing to http://www.domain.com/, while you don't need to care about the consistency of this link, even if you move the file to another location later. Another placeholder is {qp_timestamp_parsed}, which will simply be replaced by the actual time in the moment the file is parsed. If you click on the link 'Hist', you will see a list of all versions that exist of a file (a new version is created every time you open a file), providing a cheap rollback solution. This should get you started; if you need further help feel free to email me. I am sorry there is no real documentation yet. The homepage of QuickHP is: http://www.kiessling.net/home/manuel/projects/software/quickhp/ You are welcome to send in patches or take part in development. Manuel Kiessling manuel@kiessling.net