From 9d59580c685016b3fa2eb826a94a0a0e7c1c1479 Mon Sep 17 00:00:00 2001 From: konrad Date: Mon, 19 Jul 2010 19:24:48 +0000 Subject: [PATCH] updated docu on building, installing, templating git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@567 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33 --- Doxyfile-cpp | 2 +- Doxyfile-php | 2 +- Makefile.unix | 67 +++- debian/README.server | 151 +------ debian/control | 12 +- debian/rules | 29 +- doc/build.html | 99 ++++ doc/build_prog.html | 50 -- doc/index.html | 37 ++- doc/install.html | 101 ++++ doc/install_prog.html | 7 - doc/install_web.html | 149 ------ doc/pack | 1 + doc/prog_protocol.html | 865 ----------------------------------- doc/server.html | 144 ++++++ doc/template.html | 58 +-- doc/tzone | 1 + www/inc/rendering/cart_listing.php | 25 +- www/inc/rendering/event_listing.php | 18 +- www/index.php | 38 ++ 20 files changed, 543 insertions(+), 1313 deletions(-) create mode 100644 doc/build.html delete mode 100644 doc/build_prog.html create mode 100644 doc/install.html delete mode 100644 doc/install_prog.html delete mode 100644 doc/install_web.html create mode 120000 doc/pack delete mode 100644 doc/prog_protocol.html create mode 100644 doc/server.html create mode 120000 doc/tzone diff --git a/Doxyfile-cpp b/Doxyfile-cpp index 66bd044..89fd67b 100644 --- a/Doxyfile-cpp +++ b/Doxyfile-cpp @@ -2,4 +2,4 @@ INPUT = src HTML_OUTPUT = doc/source-cpp EXCLUDE_PATTERNS = moc_* -#EXCLUDE = src/zip +#EXCLUDE = src/wob src/.ctmp diff --git a/Doxyfile-php b/Doxyfile-php index 82c6e77..cdbe051 100644 --- a/Doxyfile-php +++ b/Doxyfile-php @@ -1,4 +1,4 @@ @INCLUDE = Doxyfile.inc INPUT = www HTML_OUTPUT = doc/source-php - +EXCLUDE = www/inc/Twig www/tcache \ No newline at end of file diff --git a/Makefile.unix b/Makefile.unix index 4765b30..ae64421 100644 --- a/Makefile.unix +++ b/Makefile.unix @@ -16,6 +16,12 @@ QMAKE = qmake #change this if doxygen uses a different name or is not in your PATH DOXYGEN = doxygen +#this is used to compile the Twig docu into HTML +MARKDOWN = markdown + +#the directory to install MagicSmoke to +PREFIX = /usr/local + ########################################################### # END OF CONFIGURATION # No editable content below this line @@ -46,29 +52,60 @@ zip: tzone: cd tzone ; $(QMAKE) && $(MAKE) -#script stuff: depends on generated CPP files -script: qtscript/generated_cpp - cd qtscript/qtbindings && $(QMAKE) && $(MAKE) - -#generated script plugins: depend on Qt version -qtscript/generated_cpp: $(QTBIN)/qmake - cd qtscript/generator && $(QMAKE) && $(MAKE) - cd qtscript/generator && QTDIR=$(QTDIR) ./generator - dist: @echo Distribution not implemented yet sdoc: $(DOXYGEN) Doxyfile-php $(DOXYGEN) Doxyfile-cpp + rm -rf doc/twig ; mkdir -p doc/twig + echo 'Twig Index

Twig Index

'$$p'

' >>doc/twig/index.html + cd pack/phpbase ; $(DOXYGEN) + cd pack/qtbase ; $(DOXYGEN) + cd tzone ; $(DOXYGEN) Doxyfile + +install: install-client install-server install-doc + +install-client: client + mkdir -p $(PREFIX)/bin + install -D src/msmoke $(PREFIX)/lib/magicsmoke2/msmoke + cp src/icon.png $(PREFIX)/lib/magicsmoke2/ + echo '#!/bin/sh' >$(PREFIX)/usr/bin/msmoke2 + echo 'LD_LIBRARY_PATH='$(PREFIX)/lib/magicsmoke2:$LD_LIBRARY_PATH' >>$(PREFIX)/bin/msmoke2 + echo 'export LD_LIBRARY_PATH' >>$(PREFIX)/bin/msmoke2 + echo 'exec '$(PREFIX)'/lib/magicsmoke2/msmoke' >>$(PREFIX)/bin/msmoke2 + chmod +x $(PREFIX)/bin/msmoke2 + +SPREFIX=$(PREFIX)/share/magicmsoke2-server +install-server: server + mkdir -p $(SPREFIX) + cp -rLTf www $(SPREFIX) + -rm -f $(SPREFIX)/config.php + -rm -rf `find $(SPREFIX) -name .svn` + +DPREFIX=$(PREFIX)/share/doc/magicsmoke2-doc +install-doc: sdoc + mkdir -p $(DPREFIX) + cp -rLTf doc $(DPREFIX)/html + -rm -rf `find $(SPREFIX) -name .svn` clean: - rm -rf zip/Makefile* zip/*.o zip/*.a - rm -rf src/.ctmp src/Makefile* src/msmoke src/core* - rm -rf src/wob www/inc/wob doc/wob wob/core* - rm -rf pack/woc/.ctmp pack/woc/woc pack/woc/core* pack/woc/Makefile* - rm -rf pack/qtbase/.ctmp pack/qtbase/libqwbase* pack/qtbase/Makefile* - rm -rf doc/source-php doc/source-cpp + -rm -rf zip/Makefile* zip/libzip* zip/.ctmp + -rm -rf src/.ctmp src/Makefile* src/msmoke + -rm -rf src/wob www/inc/wob doc/wob wob/core* + -rm -rf pack/woc/.ctmp pack/woc/woc pack/woc/core* pack/woc/Makefile* + -rm -rf pack/qtbase/.ctmp pack/qtbase/libqwbase* pack/qtbase/Makefile* + -rm -rf tzone/zoneinfo* tzone/libtzdata* tzone/Makefile* tzone/.ctmp + -rm -rf doc/source-php doc/source-cpp doc/twig + -rm -rf `find . -name '*~'` + -rm -rf `find . -name '*.bak'` + -rm -rf `find . -name 'core*'` distclean: clean diff --git a/debian/README.server b/debian/README.server index 6b31d45..1b6c35c 100644 --- a/debian/README.server +++ b/debian/README.server @@ -6,156 +6,11 @@ Unfortunately this does not work entirely automatically. 1 - DocumentRoot and Web Server -------------------------------- -The debian package installs the server PHP files in /usr/lib/magicsmoke-server -and links them from /var/www/magicsmoke2 . You need to change that link if your -DocumentRoot is somewhere else or you want a different name. +The debian package installs the server PHP files in /usr/share/magicsmoke2-server. MagicSmoke runs with any web server that can execute PHP 5 scripts. Please be aware that the client does enforce SSL encryption, so the web server must be configured accordingly in order to work with the Qt based client. -2 - Database -------------- - -MagicSmoke can work with MySQL or Postgres. - -Connect to your database server using a client of your choice (I'll assume the -command line mysql client below, commands should be similar for other clients). - -Create a database user - I'll assume it is called "smoke" and uses "verysecret" -as password. - mysql> CREATE USER smoke IDENTIFIED BY PASSWORD 'verysecret'; - -Create a database - I'll assume it is called "smoke". - mysql> CREATE DATABASE smoke; - -Give the user all rights on this database. - mysql> GRANT ALL ON smoke.* TO smoke; - -MagicSmoke uses a common configurable prefix for its tables ("smoke2_*" per -default), so you can use an existing database or even use the same database -for multiple installations or different programs (assuming the other -programs are as tolerant as MagicSmoke). - -MagicSmoke2 can be installed in parallel to the old MagicSmoke 1.0 packages, but it -cannot access the same tables (upgrade is possible though). - -3 - Configuring MagicSmoke ---------------------------- - -Execute /usr/share/magicsmoke-server/install.sh with your target directory -as parameter. - -Now edit the config.php file, it is a simple PHP file. Although theoretically -all facilities of PHP are available there, you should stick to the format of -the template. - -3.1 Database Options -- - - - - - - - - - - - -The database section describes which database is used for storing data and -how the database interface behaves. - -The $db variable is supposed to point to an object of a class derived from -DbEngine. There are currently two of those: - -MysqlEngine uses the MySQLi interface of PHP to access a MySQL 5.x database - -PGsqlEngine uses the PGSQL interface of PHP to access a Postgres database. -To be compatible with MagicSmoke the server should be at least version 8.x - -Examples are available in the configuration file template. - -The $olddb variable if set can be used to upgrade a MagicSmoke 1.0 database -to version 2.0. After upgrade you should comment it out. - -3.2 Dedicated Client Configuration -- - - - - - - - - - - - - - - - - - - -This section configures the behavior of the server towards the - -There is only one option: the timeout for client sessions. It is safe to leave -it at the default. - -3.3 Web Client Configuration -- - - - - - - - - - - - - - - - -This section configures the behavior of the web interface. - -These options configure the timeouts of cookies, what features -are available to users and what features of the template engine -are available. - -4 - Creating the Database Content ----------------------------------- - -Open a browser and direct it to admin.php in your MagicSmoke installation -(usually something like http://localhost/magicsmoke/admin.php). - -The default user name is "Admin" and the password is "SmokeInMyEye" - or -whatever you have configured. - -Click the create database button. - -4.1 Initial Installation -- - - - - - - - - - - - - - -Create an initial administrator user. - -Done. - -4.2 Upgrade from MagicSmoke 1.0 -- - - - - - - - - - - - - - - - - - -MagicSmoke2 is not able to import old MagicSmoke Backups, you need to -import those with an old installation and then convert them as described -below. - -If you have set up the $olddb variable in your configuration MagicSmoke will -offer to migrate data. Do not attempt migration if your new database already -has some data stored. - -Please make sure that the old and new database do not share tables - at the -very least the database name or the table prefix should be different. - -Simply enter "upgrade" into the input line and click the button. - -The upgrade may take some time - you should make sure that PHP scripts do -not abort too soon. On a normal workstation this will take about 2-4 minutes -for a database with a few thousand orders. If it fails you should recreate -the new database and start over. - -The format of customers in the database has changed significantly. -The upgrade process tries to guess what part of customer names and customer -address belong to which detail. This heuristic may fail in some cases, you -should go through your customer list and correct any mistakes afterwards. - -When you are done comment out the $olddb configuration to avoid initializing it -for every call of a script. - -The migration process does not touch the old tables - -4.3 Both -- - - - - - -Comment out the "setAdminPassCode" line in config.php, so that noone -else can abuse this interface. - -From now on you can access it with the MagicSmoke client. Your URL for the -client ends in machine.php (eg. http://localhost/magicsmoke/machine.php). - - -5 - Templates --------------- - -MagicSmoke comes with templates for the web pages visible to web users. -It uses the Twig template engine for this. You will find some documentation -for writing templates in the usr/share/doc/magicsmoke-server/Twig-doc . - -The templates are installed in /usr/share/magicsmoke-server/template . -The install.sh script will put a copy into your target directory. - -Hint: install magicsmoke-doc and read the chapter about web templates. - -When you are ready redirect the server to your new template directory by -editing the $template variable in config.php . +Please install the magicsmoke2-doc package and read the installation procedure +there to learn how to make MagicSmoke available to the web server. diff --git a/debian/control b/debian/control index 19f3c31..44f37cc 100644 --- a/debian/control +++ b/debian/control @@ -2,15 +2,15 @@ Source: magicsmoke2 Section: main Priority: extra Maintainer: Konrad Rosenbaum -Build-Depends: debhelper (>= 7), libqt4-dev, qt4-dev-tools, subversion, subversion-tools +Build-Depends: debhelper (>= 7), libqt4-dev, qt4-dev-tools, subversion, subversion-tools, markdown Standards-Version: 3.7.3 Homepage: http://smoke.silmor.de Package: magicsmoke2-client Architecture: any Depends: ${shlibs:Depends}, ${local:libssl} -Recommends: magicsmoke2-doc -Suggests: magicsmoke2-server +Recommends: magicsmoke2-doc, libqtscript4-core, libqtscript4-gui, libqtscript4-network, libqtscript4-xml +Suggests: magicsmoke2-server, libqtscript4-svg, libqtscript4-webkit, libqtscript4-xmlpatterns, libqtscript4-doc Description: MagicSmoke Ticket Sale System - Standalone Client This package contains the MagicSmoke Ticket Sales System Client version 2. . @@ -26,10 +26,14 @@ Description: MagicSmoke Ticket Sale System - Documentation Package: magicsmoke2-server Architecture: all -Depends: php5 (>= 5), php5-mysql (>= 5) | php5-pgsql (>= 5) +Depends: php5 (>= 5.2), php5-mysql (>= 5) | php5-pgsql (>= 5) Suggests: magicsmoke2-doc, magicsmoke2 Description: MagicSmoke Ticket Sale System - Server This package contains the MagicSmoke Ticket Sales System Server version 2. . It can be installed in parallel to the old version 1 system, but is incompatible with old databases. + . + This package makes MagicSmoke available on your system, but it does not + create a database or install it into the web server directory, please + refer to the documentation files for details. \ No newline at end of file diff --git a/debian/rules b/debian/rules index 489555e..b46b6f7 100755 --- a/debian/rules +++ b/debian/rules @@ -58,36 +58,22 @@ install-client: @echo '********************' @echo Install Client... #client itself - mkdir -p $(CLIENT)/usr/share/doc/magicsmoke2-client - install -D src/msmoke $(CLIENT)/usr/lib/magicsmoke2/msmoke - cp src/icon.png $(CLIENT)/usr/lib/magicsmoke2/ - #wrapper for /usr/bin - echo '#!/bin/sh' >$(CLIENT)/usr/bin/msmoke2 - #echo 'LD_LIBRARY_PATH=/usr/lib/magicsmoke2:$LD_LIBRARY_PATH' >>$(CLIENT)/usr/bin/msmoke2 - #echo 'export LD_LIBRARY_PATH' >>$(CLIENT)/usr/bin/msmoke2 - echo 'exec /usr/lib/magicsmoke2/msmoke' >>$(CLIENT)/usr/bin/msmoke2 - chmod +x $(CLIENT)/usr/bin/msmoke2 - #remove the .svn dirs copied before - rm -rf `find $(CLIENT) -name .svn` + make -C $(CURDIR) -f Makefile.unix install-client PREFIX=$(CLIENT)/usr #debian docu + mkdir -p $(CLIENT)/usr/share/doc/magicsmoke2-client cp -L README COPYING* $(CLIENT)/usr/share/doc/magicsmoke2-client gzip `ls $(CLIENT)/usr/share/doc/magicsmoke2-client/* |grep -v .gz` cp -L src/smoke*.qm $(CLIENT)/usr/lib/magicsmoke2 DOCDIR=$(CURDIR)/debian/magicsmoke2-doc -DOCTARGET=usr/share/doc/magicsmoke2-client DOCDOC=usr/share/doc/magicsmoke2-doc install-doc: @echo '********************' @echo Install Doc... - mkdir -p $(DOCDIR)/$(DOCTARGET) mkdir -p $(DOCDIR)/$(DOCDOC) - mkdir -p $(DOCDIR)/usr/lib/magicsmoke2 - cp -rL doc $(DOCDIR)/$(DOCTARGET) - ln -sf ../../../$(DOCTARGET)/doc $(DOCDIR)/usr/lib/magicsmoke2/doc cp -L README COPYING* $(DOCDIR)/$(DOCDOC) gzip `ls $(DOCDIR)/$(DOCDOC)/* |grep -v .gz` - rm -rf `find $(DOCDIR) -name .svn` + make -C $(CURDIR) -f Makefile.unix install-doc PREFIX=$(DOCDIR)/usr SERVER=$(CURDIR)/debian/magicsmoke2-server install-server: @@ -96,16 +82,9 @@ install-server: #create docu dir mkdir -p $(SERVER)/usr/share/doc/magicsmoke2-server #copy and link scripts - cp -rL www $(SERVER)/usr/share/magicsmoke2-server - mkdir -p $(SERVER)/var/www - ln -sf ../../usr/share/magicsmoke2-server $(SERVER)/var/www/magicsmoke2 - #clean up - rm -rf `find $(SERVER) -name .svn` - rm -f $(SERVER)/usr/share/magicsmoke2-server/config.php + make -C $(CURDIR) -f Makefile.unix install-server PREFIX=$(SERVER)/usr #copy in docu cp -L README COPYING* $(SERVER)/usr/share/doc/magicsmoke2-server - mkdir -p $(SERVER)/usr/share/doc/magicsmoke2-server/Twig-doc - cp -L twig/doc/* $(SERVER)/usr/share/doc/magicsmoke2-server/Twig-doc gzip `ls $(SERVER)/usr/share/doc/magicsmoke2-server/* |grep -v .gz` gzip $(SERVER)/usr/share/doc/magicsmoke2-server/README.Debian-Install.gz diff --git a/doc/build.html b/doc/build.html new file mode 100644 index 0000000..1eee7db --- /dev/null +++ b/doc/build.html @@ -0,0 +1,99 @@ + +Building Magic Smoke + + +

Building Magic Smoke

+ +

Supported Platforms

+ +Linux is supported for both client and server. It is originally developed on Debian, but should work out of the box on any other distribution that provides the necessary tools.

+ +Windows is only supported for building the client. While I'm convinced that the server would be able to work on Windows, there is no automatic support for it - you're on your own here.

+ +MacOS is entirely untested. If all necessary tools are installed, MagicSmoke can probably be compiled and installed the Unix way, but I have no way of testing this.

+ +Other Unixoid systems are untested, but should work just like Linux if you install the proper tools.

+ +

Prerequisites

+ +You need Trolltech/Nokias Qt Open Source edition +version 4.6 or any newer.

+ +You also need OpenSSL installed and Qt needs to be built with +SSL-support. While the pure web-UI can run without SSL, it is highly recommended that you enable +SSL for the complete server. The client insists on using SSL - it is not possible to connect the +client to the server without it.

+ +You need a C++ compiler that works with Qt. I usually recommend GCC 4.x for Linux and other Unixoid systems and using the MinGW version that comes with the complete Qt SDK for Windows. If you happen to have a Mac please let me know what works best... ;-)

+ +The source documentation needs Doxygen and MarkDown in order to be built. + +

Building and Installing Packages on Debian and Ubuntu

+ +You need a working Debian packaging environment, usually this amounts to:
+sh$ apt-get install fakeroot debhelper

+ +Additionally MagicSmoke needs some pre-requisites to build:
+sh$ apt-get install libqt4-dev qt4-dev-tools subversion subversion-tools markdown
+These are the packages listed in debian/control as Build-Depends.

+ +Then simply build the packages:
+sh$ fakeroot debian/rules binary

+ +You should then have three packages: +

magicsmoke2-client - the Qt-based client built for your local architecture
magicsmoke2-doc - documentation for MagicSmoke that will be put into /usr/share/doc/magicsmoke2-doc
magicsmoke2-server - the server for MagicSmoke

+ +You can install those packages with:
+dpkg -i packagefile.deb

+ +For a server installation you need to create an empty database (mysql 5.x or postgres 8.x), configure your web server and install the server into its final web directory with:
+/usr/share/magicsmoke2-server/install.sh target-directory

+ +

Building

+ +Both server and client depend on some shared code that is pre-compiled into some of their components. So it is easiest to do a complete build (unless you are familiar with the sources).

+ +Make sure that the correct version of QMake is in your PATH (you can check this by executing qmake -version). Also note that MagicSmoke and Qt have to be compiled with the same compiler.

+ +Go to the main directory of MagicSmoke. There you will find a file called Makefile.unix for Linux and other Unixoid systems and Makefile.mingw for MinGW/Windows installations. There are a few lines at the start of those files that you can adjust to better match your system (defaults should be fine for most cases). I have no access to a Mac, but I would guess that the Makefile.unix should need only very few modifications to work if the GNU tools are available.

+ +There is no support for automatic builds without MinGW on Windows. I have only tested Linux and Windows/MinGW, so there is no guarantee for any other system. + +Unixoid systems:
+make -f Makefile.unix rule

+ +Windows with MinGW:
+mingw32-make -f Makefile.mingw rule

+ +If you omit the rule parameter make will do a complete build.

+ +The following rules are available on Unixoid systems and Windows:
+ + + + + +
Rule Description
all complete build
server everything that is necessary for the server
client the client
+ +The following additional rules are available on Unixoid systems:
+ + + + + + +
sdoc source documentation (not included in all), requires doxygen and markdown
install build and installs everything: server, client, documentation
install-client build and installs the client
install-server build and installs the server components
install-doc build and installs documentation (including source documentation)
+ +For the install targets the makefile assumes per default that everything belongs into sub-directories of /usr/local. You can change this by adding a PREFIX variable to the call, like this:
+make -f Makefile.unix PREFIX=$HOME/magicsmoke install
+this will instead install into the magicsmoke subdirectory of the calling users home directory. + +

Installation

+ +Use the install targets above for installation on a Unixoid system.

+ +See the Installation page for details. \ No newline at end of file diff --git a/doc/build_prog.html b/doc/build_prog.html deleted file mode 100644 index b2f905c..0000000 --- a/doc/build_prog.html +++ /dev/null @@ -1,50 +0,0 @@ - -Building Magic Smoke - - -

Building Magic Smoke

- -

Prerequisites

- -You need Trolltech/Nokias Qt Open Source edition -version 4.4 or any newer.

- -If you want to secure your connection with HTTPS you need -OpenSSL installed and Qt needs to be built with -SSL-support.

- -The autoupdate function of MagicSmoke needs GNU MP for signature checks. Most Linux distributions come with GNU MP as standard packages, there are pre-compiled packages at various locations in the net - make sure you use one that matches your compiler. Make sure GNU MP is installed so that gmp.h is in the default include path of the compiler.

- -You need a C++ compiler that works with Qt. I usually recommend GCC 4.x for Linux and other Unixoid systems and MinGW with GCC 3.4 for Windows. If you have a Mac please let me know what combination works best... ;-) - -

Building

- -Both server and client depend on some shared code that is pre-compiled into some of their components. So it is easiest to do a complete build (unless you are familiar with the sources).

- -Make sure that the correct version of QMake is in your PATH (you can check this by executing qmake -version). Also note that MagicSmoke and Qt have to be compiled with the same compiler.

- -Go to the main directory of MagicSmoke. There you will find a file called Makefile.unix for Linux and other Unixoid systems and Makefile.mingw for MinGW/Windows installations. There are a few lines at the start of those files that you can adjust to better match your system (defaults should be fine for most cases).

- -Unixoid systems: -make -f Makefile.unix rule

- -Windows with MinGW: -mingw32-make -f Makefile.mingw rule

- -If you omit the rule parameter make will do a complete build. The following rules are available:

- - - - - - - - - -Rule Description all complete build woc only the web object compiler wob web object compiler and preprocessing of common components server everything that is necessary for the server client the client sdoc source documentation (not included in all), requires doxygen - -

`Shipping`

- -When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can find out what these libraries are using standard tools, like ldd (Unix/Linux), objdump -x or dumpbin /depends on Windows, or otool -L on MacOS. - -(to be continued) \ No newline at end of file diff --git a/doc/index.html b/doc/index.html index bac8dbb..eb2573c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,7 +3,17 @@ Magic Smoke Documentation - + + +MagicSmoke is a client-server system in an almost classic 3-tier architecture: + +Database Layer: a MySQL or Postgres database is used for storing all of its data. +Server/Middleware Layer: the server component contains all the code that accesses the underlying database and the code that generates browsable pages for customers, it is based on PHP 5 +Client Layer: + Customer access: the system can be accessed with a normal Web Browser, you can extensively modify the templates used for this. + Theater side: the system has a special Qt-based client that can access the server and all underlying data. + + Using Magic Smoke @@ -17,26 +27,37 @@ to be written: Building/Installing Magic Smoke -Installing the Web Components +Building MagicSmoke +Installing MagicSmoke +Creating a Server Instance Templates: Web Template Design ODT Template Design Ticket and Voucher Template Design -Building the Program -Installing the Program Programmers Manual -to be written +Architectural Overviews: The MagicSmoke Architecture -Client-Server-Protocol Documentation (this version of the protocol is obsolete and only supported for a short transition period) -The Web Object Compiler - + +External Components: + +The PACK - Persistence And Communication Kit +The Twig template engine +Time Zone library source documentation + + +Source Documentation: + +The Client Classes +The Server Classes +The Web OBject interface description + \ No newline at end of file diff --git a/doc/install.html b/doc/install.html new file mode 100644 index 0000000..3fe1d40 --- /dev/null +++ b/doc/install.html @@ -0,0 +1,101 @@ + +Magic Smoke Installation + + + + +You need to build the system first. This is also true for the server web components, since they include lots of generated sources. + + MagicSmoke Client Installation + +On a Debian or Ubuntu system it is recommended to use the native installation packages for MagicSmoke - they will automatically require everything they depend upon. + + Manual Installation on Linux and Unix Systems + +Install the Qt4 library so that it is usable by Qt-based programs on your system. For systems that use the ELF binary format (eg. any Linux) Qt itself will take care of storing its location in the binary (RPATH). On other systems you can solve the problem by setting LD_LIBRARY_PATH or SHLIB_PATH to Qt's lib path. + +Make sure OpenSSL is installed and available to Qt. For the scripting interface of MagicSmoke it is also recommended to install the QtScript bindings. + +Copy the src/msmoke binary to the location you want to start it from. Or call: +make -f Makefile.unix install-client +The latter will per default install into /usr/local/bin. + + Manual Installation on Windows + +Copy the src/msmoke.exe binary to a path you want to start it from. Then copy the Qt DLLs to the same path. From the OpenSSL directory copy libssl32.dll and libeay32.dll to that path. You should be able to start MagicSmoke from this path on any Windows machine. + +If you used the full SDK of Qt to compile MagicSmoke, be sure to use the DLLs from the qt/bin subdirectory of the SDK, not the ones from bin - those are incompatible. + +It is recommended to copy the plugins directory from your Qt installation to that path as well - this will make sure that all image formats etc. are supported. + +For the scripting interface of MagicSmoke it is also recommended to install the QtScript bindings - they need to be placed in plugins/script. + + Installation Package for Windows + +This requires the NSIS Installer. + +(to be completed...) + + + Magic Smoke Server Installation + +The steps below assume that you are using a Unixoid system. A lot of them will not work on windows, since the makefile for windows does not contain them and the symlinks used inside the server source tree are not present under Windows - you will have to do a lot of manual copying in that case. + +Prerequisites + +You need a (web-)server that has PHP and a database server: + + +A webserver running PHP 5: + + version 5.2 or newer + One of the supported Database drivers: currently MySQLi and PostgreSQL are supported. + PCRE + XML driver: dom + The date extension for time zone support + +A database server -- you need full (SELECT, INSERT, UPDATE, CREATE) access to at least one database: + + MySQL 5.x, or + Postgres 8.x + + + +Hint: you can check what modules are active in your PHP installation by creating a script file +(eg. test.php) that contains only this line: <? phpinfo(); ?> . +When you install this file on the web server and then open its URL in a browser it will show +you an overview of all PHP functionality. If it returns an empty page, the file was not processed +by PHP and you still need to configure the web server. + +The database server must be reachable by the web server, but does not need to be on the same machine. + + Local Installation + +You will have to prepare an installation directory for the server by either installing the Debian packages or by installing locally: +make -f Makefile.unix install-server + +This places the PHP sources into a a specific directory on your system instead of continuing to use the source directory. It does not activate your first server yet. + +Please read the Server Creation page on how to continue from here. + + + Installation on an ISP Account + +If you are using an account at an ISP you usually don't get much access to the server. You still have to make sure that you have support for all required components. + +You also need to do a local installation first if you want to install to an external ISP account (unless you have full shell and network access there). It is also recommended to try out MagicSmoke on a local box first. If you do not want to install MagicSmoke into a system directory, just change the PREFIX: +make -f Makefile.unix install-server PREFIX=$HOME/magicsmoke + +Copy the local server installation directory to you ISP account with whatever copying mechanism your provider has given you (usually FTP or scp). Rename config.php.template to config.php. + +Some providers install several versions of PHP in parallel and detect what version you use by the file suffic that you are using. Try the phpinfo() call from above with different file extensions (eg. .php, .php5) to find out what is needed to be interpreted as a PHP 5 (version 5.2 or newer) script. Rename exactly the scripts index.php, admin.php, and machine.php to the correct suffix. Do NOT change any other script names - these are the only ones executed directly and they rely on the other script names still being as delivered. + +You will usually get a MySQL database and a matching user name from your provider. You can skip the basic DB creation, configure the parameters you got from the provider and then go on with the configuration as normal. See Server Creation for details. + + + + \ No newline at end of file diff --git a/doc/install_prog.html b/doc/install_prog.html deleted file mode 100644 index 3531965..0000000 --- a/doc/install_prog.html +++ /dev/null @@ -1,7 +0,0 @@ - -Installing Magic Smoke - - - Installing Magic Smoke - -to be written... \ No newline at end of file diff --git a/doc/install_web.html b/doc/install_web.html deleted file mode 100644 index d7bf2ae..0000000 --- a/doc/install_web.html +++ /dev/null @@ -1,149 +0,0 @@ - -Magic Smoke Web Installation - - -Magic Smoke Web Installation - - -Prerequisites - -You need a (web-)server that has PHP and MySQL installed: - - -A webserver running PHP version 5.x, with at least the following modules: - - Hash or MHash for authentication (although it is possible to work without them it is not recommended) - One of the supported Database drivers: currently only MySQL is supported. - PCRE - XML driver: dom - -MySQL 4.x or 5.x -- you need full access to at least one database. - - -Hint: you can check what modules are active in your PHP installation by creating a script file -(eg. test.php) that contains only this line: <? phpinfo(); ?> . -When you install this file on the web server and then open its URL in a browser it will show -you an overview of all PHP functionality. If it returns an empty page, the file was not processed -by PHP and you still need to configure the web server. - -Preparation - - -Build at least the server components. -create a database on MySQL (eg. create database smokedb) -create a database user (eg. create user smokeuser) -give this user full access to this database (eg. grant all on smokedb.* to smokeuser) -create a configuration (see below) -create templates (see below) - - -All files needed for Web-Installation are in the www-subdirectory. - -Installation on an ISP Account - -If you are using an account at an ISP you usually don't get much access to the server. You still have to make sure that you have support for all required components. - -You will usually get a MySQL database and a matching user name from your provider. You can skip the basic DB creation above, configure the parameters you got from the provider and then go on as normal. - -Some providers install several versions of PHP in parallel and detect what version you use by the file suffic that you are using. Try the phpinfo() call from above with different file extensions (eg. .php, .php5) to find out what is needed to be interpreted as a PHP 5.x script. Rename exactly the scripts index.php, admin.php, and machine.php to the correct suffix. Do NOT change any other script names - these are the only ones executed directly and they rely on the other script names still being as delivered. - - Configuration - -Copy the config.php.template file to config.php, then modify it to suit your -needs. - -Database Configuration - -Magic Smoke is designed to work with multiple database engines. However, currently only MySQL is -supported (this does not support mysqli or pdo_mysql). - -The $db variable needs to be assigned with the correct engine to open the database. Currently only the MysqlEngine exists. This is an example configuration: - -// create engine: server, user, password -$db = new MysqlEngine("localhost","smokeuser",""); -// set database name -$db->setDbName("smokedb"); -// set table-prefix (optional) -$db->setPrefix("smoke_"); -//set this to one of the supported MySQL storage engines for DB creation -$db->setStorageEngine("InnoDB"); - - -The three parameters to the MysqlEngine constructor are: first the host the database server runs on. Use "hostname:port" if it runs on a non-standard port or ":/path/to/socket" if you want to use the local socket on a Unix system. The second parameter is the username for the database server and the third one the password (empty if no password is necessary). - -The setDbName call is used to set the database that is used by Magic Smoke. The setPrefix call can optionally be used to set a prefix for all table names -- this way a single database can be used for multiple installations of Magic Smoke or even different applications (if the other applications are guaranteed to not touch Magic Smokes tables). - -The setStorageEngine call can be used to set the table storage engine used by MySQL. Magic Smoke relies on MySQL using a transactional table type. The default is "InnoDB". It is not recommended that you change the default unless you know exactly what you are doing. - - Admin Configuration - -There is one option stored in the DB-Engine that is only used for database creation and recovery: --$db->setAdminPassCode("Admin","SmokeInMyEye"); - - -This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users. Change the second parameter (password) to something else, so I won't be able to guess your admin password in case you forget to comment it. - -Client Authentication and Session Configuration - -The remainder of the config file contains settings for the dedicated client: --//Authentication algorithm -// possible: md5, sha1, sha256, hmac-md5, hmac-sha1, hmac-sha256 -$ClientAuthAlgo="hmac-sha1"; -//hash algorithm library -- the PHP extension/module used for calculation -// possible: string (md5, sha1 only), hash, mhash -$HashLib="hash"; - -//Initial timeout from start of session request to session authentication -// usually 300s (5min) is a good value -$ClientAuthTimeout=300; -//Authenticated session timeout - how long an authenticated session lasts -// this should usually be a few hours (3600s per hour) -$ClientSessionTimeout=2*3600; - - -$ClientAuthAlgo contains the algorithm that is used to authenticate the client. You have to make sure that the algorithm selected is a) available in PHP, b) secure enough for your application, and c) available in all clients that are supposed to connect. The algorithms are: - - - - - -md5 Uses the MD5 hash algorith described in RFC1321. Please note that this algorithm is regarded as broken and should not be used. sha1 Uses the SHA-1 hash algorithm described eg. in RFC3174. Please note that this algorithm is theoretically broken, although the use of this algorithm in Magic Smoke should still be secure for a few years. sha256 Uses the SHA-256 hash algorithm of the SHA-2 hash family. This algorithm is currently recommended as replacement for SHA-1. However, it is currently not supported by any client. hmac-md5, hmac-sha1, hmac-sha256 Uses the same hash algorithms in HMAC mode (see RFC2104). This use is more secure than the plain use of the algorithms. It is recommended to use HMAC. - -$HashLib defines what PHP extension is used for calculation of hash values: - - - - -string Doesn't use any extension and instead uses the string functions md5 and sha1. This mode does not support sha256 or any of the hmac-modes. hash Uses the "hash" extension. This extension supports all modes listed above. mhash Uses the "mhash" extension. This extension supports all modes listed above. - -The $ClientAuthTimeout and $ClientSessionTimeout set the two session timeouts. The first timeout defines how long the authentication handshake of the client may last before the handshake is terminated. The second value defines how long a session may be active before it is automatically closed. - - Creating Templates - -The www/template/* directories contain collections of template files. These are used to generate the user interface that users get to see. - -Please read the chapter about Template Design and create your own set of templates (or customize an existing one). - -Then modify the template line in your config file, eg.: - -$template="./template/mytemplate/"; - - -Installation - - -copy the www directory including your configuration and templates to the web server -navigate to admin.php in your browser, enter the admin name and passcode you configured -click to create the database -create an initial admin user in the database -close the browser -link the index.php script from your other pages, so that customers can find it -continue with the client installation - - - - - - \ No newline at end of file diff --git a/doc/pack b/doc/pack new file mode 120000 index 0000000..57747aa --- /dev/null +++ b/doc/pack @@ -0,0 +1 @@ +../pack/doc \ No newline at end of file diff --git a/doc/prog_protocol.html b/doc/prog_protocol.html deleted file mode 100644 index 84d4630..0000000 --- a/doc/prog_protocol.html +++ /dev/null @@ -1,865 +0,0 @@ - -Magic Smoke Protocol Documentation - -Magic Smoke Protocol Documentation - - -The Magic Smoke Protocol is used between the Magic Smoke Server and Client. It is based on HTTP and XML. Only POST requests are allowed. All body data is presumed to be in UTF-8 encoding, headers are restricted to ASCII-127. - -Each request must have a "x-magicsmoke-request=..." header. The actual request data is sent as POST-data. Except for the serverinfo and startsession requests all requests must also carry a "x-magicsmoke-session" header. - - HTTP Headers - -Part of the data is transmitted in headers. This section lists all possible headers used by Magic Smoke. - -Client Request Headers - - - - -x-magicsmoke-request The request that is to be executed by the server. This header is mandatory for all requests. x-magicsmoke-session The session ID of this connection. This header is mandatory for all requests except serverinfo and startsession. - -Server Response Headers - - - -x-magicsmoke-status The status of the request execution. See table below for details - -Possible status codes are: - - - - - - - - - -(missing) If the whole header is missing or contains an unknown value, this should be treated as if it contained "Error" (see below). Ok The request went ok and the actual data comes as response body. Error Some unspecified error occured. The response body might contain some detailed human readable information. NonPost The HTTP method was not POST. The body is a simple HTML page explaining to the user that browsers are not meant to use this page. Unauthenticated The session ID does not exist, authentication failed or the session expired. NotAllowed The user does not have the right to execute this transaction. InvalidRequest The request was not understood. There was probably a mismatch in client and server version. SyntaxError There was a syntactical error in the request data. Some details might follow in the response body. - - - Server Info - -A serverinfo-request can be sent by any client in order to get basic information -about the server. - -The server replies with an XML document that contains the most important information: - -<Info> - <ServerVersion proto="protocol-version">server-version-number</ServerVersion> - <AuthAlgorithm>hash-algo</AuthAlgorithm> -</Info> - - -The proto argument of the ServerVersion tag returns the protocol version, which is used by the client to check whether it is compatible with the server. It consists of two blocks of four hex-digits each, separated by a space. The first block is the lowest protocol version understood by the server, while the second block contains the current protocol version implemented by the server. - -The server version number in the ServerVersion tags text is a the software version itself. The hash-algorithm values are described below in the authentication protocol section. - -The protocol version described in this document is 0000. - - - Authentication protocol - -First the client requests the hash-algorithm from the server. Possible -algorithms are: - - - - -md5, sha1, sha256 use the hash algorithm directly, the returned value is calculated by first concatenating challenge and password/hostkey and then hashing it hmac-* use the same algorithm in HMAC mode with the challenge as data and the password/hostkey as key - -Step 1: Start a Session - -The authentication handshake is started with the client asking for a new session using a startsession-request. The post data of this request should consist of at least 128 random bits (base64 or another ASCII encoding) which are used by the server to calculate a session ID. - -The server responds with a session object: --<SessionStart> - <ID>session-id-string</ID> - <HostChallenge>host-challenge-string</HostChallenge> - <UserChallenge>user-challenge-string</UserChallenge> - <Timeout>seconds-till-session-timeout</Timeout> -</SessionStart> - - -The challenge strings are derived from some internal function and the clock. By no means they are meant to be secure against all kinds of attack. The challenge-response-protocol is only supposed to avoid sending the passwords in plain text over the wire. - -The timeout of the temporary session is usually 5 minutes (300s). - - Step 2: Authenticating the Session - -This is done using a sessionauth request. The session ID header must be set. - -The client sends its authentication data as XML: - -<SessionAuth> - <HostName>host-name</HostName> - <HostAuth>host-authentication-data</HostAuth> - <UserName>user-name</UserName> - <UserAuth>user-authentication-data</UserAuth> -</SessionAuth> - - -The authentication data is calculated using the hash-function mandated by the server. The HostAuth item is calculated using the HostChallenge and the hosts key. The UserAuth item is calculated using the UserChallenge and the users password. Both *Auth values are hexadecimal-encoded. - -The status is "Ok" or "Unauthenticated" - in the latter case the session ID is deleted and the client needs to start with a startsession request again if it wants to retry. If the request succeeds, the result body contains two numeric items (separated by a newline) that state the new session timeout and the current time as a Unix timestamp (seconds sice epoch - 1Jan1970, 00:00 UTC). - -A result of "Unauthenticated" can have multiple reasons: the timeout of the temporary session expired before the request was received, the authentication of the user failed, the user is not allowed to connect from this or an anonymous host, or the authentication of the host failed and the user is not allowed to connect from an anonymous host. - - Step n: Closing the Session - -This is done with a sessionclose request. Neither request nor response contain a body. - -This request always yields an "Ok" status response regardless of whether the session ID was still valid or not. - - Note on Usernames and Roles - -Both, user names and roles, are restricted to letters, digits and "_". Leading and trailing whitespace is ignored (trimmed). - -Each role corresponds to a function that can be called and executed remotely through the machine interface. Roles beginning with "_" are reserved keywords that can alter the behaviour of other roles and must not be used to name functions. - - - Basic Requests - -Getting ACL info - -The getmyroles transaction requests all roles from the server. A role is a transaction that needs permission to be executed (ie. all transactions except serverinfo, startsession, sessionauth, closesession, and getmyroles) or a special right. The response is a list of roles with one role per line. - -Special rights are: - - -_admin The user is an administrator and can automatically execute everything. - - - - Event Related Requests - -Getting a List of Events - -The geteventlist transaction requests all events from the server. The response is a simple XML structure that contains only very basic data for each event: - - -<EventList> - <Event id="0" start="1190543432" sold="11" capacity="20" reserved="2">blechsalat</Event> - <Event id="1" start="1191419769" sold="11" capacity="20" reserved="2">stringsalat</Event> -</EventList> - - -Each event is encapsulated in an Event tag. The events have no specific order. The id attribute contains the internal ID of the event that can be used to reference it in other requests. The start attribute contains the start time of the event as Unix timestamp. The text of the Event tag contains the title of the event. - -There are 3 optional attributes: capacity contains the maximum number of seats for this event, sold the number of tickets that have been sold and reserved the number of tickets that have been reserved. - - Getting Detailed Event Data - -The geteventdata transaction returns detailed data about the event. The request body contains a space separated list of event IDs. The response looks like: - - -<EventData> - <Event id="0" start="1190543432" end="1190543532" capacity="25" defaultprice="1177" cancelled="false"> - <Title>blechsalat</Title> - <Artist>Broken Blech</Artist> - <Description>a lot of text containing encoded <b>HTML</b> tags</Description> - <Room>Invisible Library</Room> - <CancelReason>a damned good one</CancelReason> - </Event> - <Event id="1" start="1191419769" ...> - ... - </Event> -</EventData> - - -Attributes and tags: - - - - - - - - - - - - -id the ID of the event start the start time as Unix timestamp end the end time as Unix timestamp capacity how many tickets may be sold for this event defaultprice the default price for tickets as integer in cent (or penny or ...) cancelled optional: "true" or "false" -- shows whether the event is cancelled, default is "false" Title the title of the event Artist the artist appearing Description a description for the web page, may contain HTML Room the room it is happening in (the room must exist in the list of available rooms) CancelReason optional: if the event is cancelled, the reason for it (human readable) - -If one of the requested events does not exist, it simply does not generate an Event block. It is permissible for the server to send an empty EventData tag if no data is available for the request. - - Changing/Creating an Event - -The seteventdata transaction creates/changes an event. The request data looks like: - - -<Event id="0" ....> - <Title>.... -</Event> - - -Attributes and tags are the same as for the geteventdata response. Except that the id attribute may contain the value "new" to create a new event, a negative integer is not allowed. - -The response contains the ID of the new/changed event if the status is "Ok". In the case of failure the status will be "Error" and an optional reason for the failure may be in the body. - -The request must not change the cancellation status of an event - the attribute "cancelled" is ignored and the element "CancelReason" may be ignored if it violates the current status. - - Getting a Ticket Summary of an Event - -The eventsummary transaction returns summary data for an event. The request contains the ID of the event. The response contains: - - -<EventSummary event="eventID" reserved="numbeOfCurrentlyReservedTickets" - cancelled="numberOfCurrentlyCancelledTickets" - totaltickets="numberOfUsableTickets" totalmoney="totalIncomeOfEventInCent" > - <Tickets price="priceCategoryInCent" bought="numberOfUsableTicketsInThisCategory" - used="numberOfUsedTickets" unused="numberOfUnusedTickets" /> - <Comment customerid="customerID" customer="customers Name" orderid="orderID">comment</Comment> - <Orders>space separated IDs of all orders for this event</Orders> -</EventSummary> - - - -Cancelling an Event - -The cancelevent transaction can be used to cancel an event. This transaction is not reversible. The request contains the event-ID and the cancel reason separated by a newline, the response is empty. - - - -Room related Transactions - -Getting Rooms - -The getroomdata transaction returns data about rooms in the database. The request data looks like this: - - -<GetRooms detail="basic"> - <Room>ID of room</Room> - ... -</GetRooms> - - -The detail attribute may be "basic" or "full". If no <Room> tags are present all rooms are returned. - -The response data looks like: - - -<RoomData> - <Room capacity="24"> - <ID>Room ID</ID> - <Description>some encoded HTML text that describes the room</Description> - </Room> - ... -</RoomData> - - -The capacity attribute tells how many persons fit into the room. The ID tag contains the ID or Name of the room, the optional Description tag contains a description of the room - it is only present if full detail has been requested. - -Setting Rooms - -The setroomdata transaction is used to create/change one or more rooms, the request data looks like: - - -<RoomData> - <Room capacity="24"> - <ID>Room ID</ID> - <Description>some encoded HTML text that describes the room</Description> - </Room> - ... -</RoomData> - - -The response simply contains the status "Ok" or "Error". - - -ACL related Transactions - -Getting User Info - -The getusers transaction returns the names and descriptions of all users in the system. The request is empty, the response looks like: - - -<Users> - <User name="loginname">Description of User</User> - ... -</Users> - - -Adding Users and Setting New Descriptions - -The setuserdescription call can be used to set new descriptions for existing users. The call may silently fail for any user that does not exist, hence the client should request user data from the server to confirm whether the call succeeded. - -The adduser call can be used to create new user accounts. Initially the new user will have no ACL and no host settings. - -Both calls use this structure for the request: - - -<Users> - <User name="loginname" passwd="initial password">Description of User</User> - ... -</Users> - - -The passwd attribute is optional. - -The adduser call also uses it for the response, leaving out any user name that already existed or does not conform to the syntax requirements. - - Deleting a User - -The deleteuser transaction deletes one single user. The request contains the user name to be deleted on the first line and optionally a user to assign database object to that are currently owned by the user to be deleted (eg. orders). If no second user is referenced those objects are un-assigned. - -The response is empty or optionally contains an error message. - - Changing a Users own Password - -The setmypasswd can be used to change the user of the current session. The request looks like: - - -<SetMyPasswd oldpwd="old password" newpwd="new password"\> - - -The response is empty. Only the status counts. - -Changing another Users Password - -The setpasswd can be used to change the user of the current session. The request looks like: - - -<SetPasswd user="user name" newpwd="new password"\> - - -The response is empty. Only the status counts. - -Getting User ACLs - -The getuseracl transaction returns the ACL of a specific user. The request contains only the login name of the user. The response looks like: - - -<ACL user="username"> - <Role name="rolename" set="1|0"/> - ... -</ACL> - - -All setable roles must be listed, so that the client can use these for displaying in a dialog. - -Setting User ACLs - -The setuseracl transaction can be used to update a users ACL. The request is identical to the response of getuseracl, while the response is an empty document on success - only the status "OK" counts. - -Any role listed in the request is changed accordingly, non-existant roles are ignored, roles not listed are left unchanged. - - Getting a Users Hosts - -The getuserhosts transaction returns the allowed client hosts of a specific user. The request contains only the login name of the user. The response looks like: - - -<Hosts user="username"> - <Host name="hostname" set="1|0"/> - ... -</Hosts> - - -All setable hosts must be listed, so that the client can use these for displaying in a dialog. - -Setting User Hosts - -The setuserhosts transaction can be used to update a users allowed client hosts. The request is identical to the response of getuserhosts, while the response is an empty document on success - only the status "OK" counts. - -Any host listed in the request is changed accordingly, non-existant hosts are ignored, hosts not listed are left unchanged. - - Creating and Changing Hosts - -The addhost transaction creates new hosts. The sethost transaction changes the key of existing hosts. For both the request looks like: - - -<Hosts> - <Host name="hostname">hostkey</Host> - ... -</Hosts> - - -FIXME: currently these transactions do not return any feedback about success. The sethost transaction silently ignores hosts that do not exist. - -Getting All Hosts - -The gethosts transaction returns the name and key of all hosts. There is no request body. The response looks like the request above. - -Deleting Hosts - -The deletehost transaction deletes one single host. The request contains only the name of the host as ASCII text. - -FIXME: special hosts (beginning with "_") return errors. Non-existing hosts are silently ignored. - - - Customers - -Getting List of Customers - -The getcustomerlist transaction returns a short list of customers. The request is empty. The response returns this: - --<CustomerList> - <Customer id="integer ID" name="full name"/> - ... -</CustomerList> - - -Customer Details - -The getcustomer transaction returns detailed information about a customer. The request contains the ID of the customer, the response contains: - - -<Customer id="integer ID" name="full name" mail="login-mail-for-webinterface"> - <Address> address info</Address> - <Contact> contact information</Contact> - <Comment> system internal comment</Comment> -</Customer> - - -The "mail" attribute is optional - it is only reported for customers that have a web-interface account. - -Setting Customer Details - -The setcustomer transaction is used to set details of the customer. The request contains a customer XML object as listed above, but without the mail attribute. The response contains the ID of the customer. - -Deleting and Merging Customers - -The deletecustomer transaction can be used to attempt to delete a customer from the database. It will fail if this customer still has any data (eg. orders) stored in the database. The request contains the ID of the customer to be deleted. The request may optionally contain a second customer ID separated from the first with a single space - if it does, the first customer is merged into the second one. The response is empty. - -If customers are merged, the following rules are executed: - -the first ID is the one to be deleted - all database objects (orders, tickets, vouchers, etc.pp.) of the first customer ID are transferred to the second one - all customer data (name, address, etc.) of the second customer ID is preserved, while the data of the first ID is deleted - exception: if the second ID has no web-login associated with it, but the first one does, then the login is re-assigned to the second ID before the first ID is deleted - - - -Orders and Sales - -The order XML representation looks as follows: - --<Order id="orderid" customer="customerid" seller="sellerid" ordertime="timestamp" senttime="timestamp" - totalprice="amountInCent" paid="amountInCent" status="orderstate"> - <Ticket event="eventid" id="ticketid" price="priceInCent" status="ticketstate" /> - <Voucher id="voucherid" price="priceInCent" value="remainingValueInCent" used="0|1" status=""/> - <Shipping price="priceInCent" type="shippingtypeID">Shipping Comment</Shipping> - <DeliveryAddress>deliver address</DeliveryAddress> - <Comment>comment...</Comment> -</Order> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Item Description Occurrence Order Container for one single order or sale 1 id ID of the order, if already known. 0-1 customer ID of the customer. Mandatory. 1 seller Login of the seller. Automatically filled in. 0-1 ordertime Time of the order. Automatically filled in. 0-1 senttime Time at which the order was shipped. Automatically filled in. 0-1 totalprice Total accumulated price of the order. Automatically filled in. 0-1 paid Amount that has already been paid. Automatically filled in. 0-1 status Current status of the order. Automatically filled in. See table below. 0-1 Ticket(*) data about a single ticket bought in this order 0-unlimited id ID of the ticket 1 event ID of the event this ticket refers to. 1 price Price of the ticket 1 status Status of the ticket (see below) 1 Voucher(*) data about a single voucher bought in this order, vouchers that are used to pay for an order are not stored 0-unlimited id ID of the voucher 1 price Price of the voucher (adds to price of the order) 1 value Value (in cent) of the voucher (does not add to the order, but refers to how much the voucher is worth) 1 status only in validation responses: result of the validation 0-1 used Flag whether the voucher has been used to pay for anything (assumed as 0 if not present) 0-1 Shipping information about the kind of shipping used and how much it costs; if text is used it is a copy of the text from the shipping table information - it cannot be changed here 0-1 price Price of the shipping option 1 type shipping type ID 1 DeliveryAddress the address to send the stuff to, if not present or empty the address of the customer is used 0-1 Comment comment entered into the order by customer or seller 0-1 -(*)At least one of Ticket or Voucher must be used. - -If items that are not expected are filled in in a message, they will be ignored. - -Order status: - - - - - - - -Status Description placed The order has been placed, nothing has been sent or paid yet. sent The order has been shipped. reserved The order has been reserved. This means the tickets are blocked, but it cannot be paid or shipped. cancelled The user cancelled an unshipped and unpaid order. closed The order is final and cannot be altered. (State maybe not needed.) - -Ticket status: - - - - - - -Status Description bought(1) The ticket is valid; whether it is paid for depends on the order status. refund(2) The ticket has been or needs to be refunded; eg. after the event or order was cancelled. used(1) The ticket has been used. reserved The ticket is reserved. This state is currently not used. -(1)bought and used tickets add to the total price of an order; only bought tickets can be used -(2)refunded tickets add nothing to the total price of an order, this may make the paid amount higher than the amount due. - - Checking or Creating Orders/Sales - -The createorder transaction creates an open order. The initial state of the order is "placed". -The createreservedorder transaction creates a reservation. The order looks like a normal order, but it is in the "reserved" state in which it cannot be paid or shipped - it has to be converted first -The createsale transaction creates an order that is marked as delivered and paid. The initial state of the created order is "sent" and the amount paid is equal to the total price. -The checkorder transaction performs all checks and lookups of an order, but does not commit it to the database. - -The create* transactions fail with an error if a ticket cannot be reserved or if a voucher value is invalid. The checkorder transaction uses special state values to signify failure. It sets the price of a voucher to the nearest legal voucher value if the value is not allowed. - -The request is an order object without most fields filled in, the response is a copy of that object with all relevant fields filled in: - - - - - - - - - -Element Attributes in Request Attributes in Response Order customer id(1), customer, seller(3), ordertime(1,4), totalprice(5), paid(1), status(6), senttime(2,4) Ticket event, price(7) event, id(1), price, status(6) Voucher value, price(7) value, price, id(1), status(11) Shipping type(8), price(9) type(10), price, [text](10) DeliveryAddress [text] [text] Comment [text] [text] -(1)field is optional for checks and has no meaning there, it is recommended the server returns a dummy ID for checks -(2)the field only exists for sales -(3)the seller is automatically taken to be the session user -(4)time stamps are automatically filled in with the current server time -(5)the total price is the accumulated price of all tickets and vouchers in the order -(6)the status fields have special meanings for checks, see below -(7)the price field will only be honoured in the request, if the user also has the privilege to use the changeticketprice transaction -(8)the shipping types that are allowed depend on whether the user has the _anyshipping privilege -(9)price is optional, if set it is ignored if the user does not have the _repriceshipping privilege -(10)the type in the response may be -1 if an error occurred in this case the text contains the error message, otherwise it contains a copy of the shipping option text -(11)in validation responses if the voucher contains a non-empty state it is not deemed valid by the server, the state must be one of the status constants below - -Order status for checks: - - - - - - -State Description ok(1) the order can be executed as is saleonly(2) the order can only be continued as a sale, not as an open order orderonly(2) the order can only be continued as an open order, not as a sale; this state also shows that there is a problem with the configuration fail the order contains failed items -(1)Attention: the return code "ok" means the order would have succeeded at the time of the check, it may still fail when it is actually placed -(2)these states are equivalent to ok if the intended transaction matches and to fail if it does not match - -Ticket status for checks: - - - - - - - - - -State Description ok(1) the order can be executed as is saleonly(2) the order can only be continued as a sale, not as an open order orderonly(2) the order can only be continued as an open order, not as a sale; this state also shows that there is a problem with the configuration toolate the order is not possible any more exhausted there are no more tickets for this event cancelled the event has been cancelled, no order is possible invalid the event does not exist in the database -(1)Attention: the return code "ok" means the order would have succeeded at the time of the check, it may still fail when it is actually placed -(2)if two or more tickets contradict on this state the order is returned as failed - -Voucher status for checks: - - - - - -State Description [empty] the order can be executed as is invalidvalue the user is not allowed to use this value for the voucher invalidprice for this user the price must equal the value (or be ommitted) - - Getting an Overview List of Orders - -The getorderlist transaction can be used to get a list of all currently stored orders. The request does not contain any data, the response looks like: - - -<OrderList> - <Order id="orderid" customer="customerid" status="orderstatus" - totalprice="amountDueInCent" paid="amountPaidInCent"/> - ... -</OrderList> - -(this is a small subset of the full order object) - -Paying/Refunding Orders - -The orderpay transaction is used to add to the amount paid in an order. The orderrefund transaction is used to subtract from the amount paid of an order. In both cases the request consists of two positive numbers separated by a space: the order-ID and the amount in cent. The response contains the new amount paid after the transaction in the case of success and status error plus an explanation in case of any problem. - -Set Shipping State of an Order - -The ordershipped transaction is used to mark an order as shipped. This transaction is only legal for orders in the "placed" state. The request contains the order ID, the response contains the new shipping time (set automatically during transaction). - -Cancelling an Order - -The cancelorder transaction is used to mark an order as cancelled. It also marks all tickets inside the order as cancelled and voids any vouchers in it. This transaction is only legal for orders in the "placed" state. It will fail if any tickets or vouchers have already been used. - -Converting Reservations - -The reservationtoorder transaction marks a reservation as a normal order. From that time on it can be paid and shipped. -The reservationtosale transaction marks a reservation as a sale. It will be marked as paid and shipped. - -The request contains the order ID, the response is empty or contains an error message. - -Use the cancelorder transaction (see above) to cancel a reservation. - - - Searching for an Order - -The orderbyticket transaction can be used to find an order by a ticket ID from that order. The request contains the ticket ID, the response contains the order ID or returns as error if not found. - -The getordersbyevents transaction can be used to return all orders that contain tickets for a specific event. The request is a space separated list of event IDs, the response has the format of the getorderlist response. - - Changing the Comment of an Order - -The setordercomment transaction is used to change the orders comment. The request is a simple XML document: - - -<OrderComment orderid="id">comment text...</OrderComment> - - -The response body is empty or optionally contains an error message. - -Changing the shipping option on an order - -The orderchangeshipping transaction can be used to change the shipping information on an order. The request looks like: - --<OrderChangeShipping orderid="orderId" type="newShippingType" price="newPriceInCent"/> - - -If type is not present, the price is taken from the new shipping type. If type is not present, it is not changed. If type is empty it is reset to none (NULL) in the Database. If a price other than 0 is used, the type in the database must be present (!= NULL). - -The response contains the updated order object or just an error message. - - Creating/Changing/Deleting Shipping Options - -The setshipping creates or changes a shipping option. The request looks like: - --<ShippingOption type="shippingOptionID" price="priceInCent" web="0|1" anyUser="0|1"> - Text that describes the option -</ShippingOption> - - -If the type attribute is missing the server creates a new option. Otherwise it changes an existing one. The web attribute tells whether the option is available to customers using the web interface. The anyUser attribute tells whether the option can be used by anyone who can create an order/sale (=1) or only by users with the "_anyshipping" privilege (=0). - -The response contains the new shipping option id or contains an error message. - -The deleteshipping transaction can be used to delete a shipping option. The request contains just the ID of the option, the response is empty. - - Listing Shipping Options - -The getshipping transaction can be used to return all shipping options. If the user has the "setshipping" or "_anyshipping" privilege the list will also contain privileged options. The request is empty. The response looks like: - --<ShippingList> - <ShippingOption type="shippingOptionID" price="priceInCent" web="0|1" anyUser="0|1"> - Text that describes the option - </ShippingOption> - ... - ... -</ShippingList> - - -Adding Tickets or Vouchers to an Order - -tbd. - - - -Tickets - -Getting Tickets - -The getticket transaction can be used to get information about a ticket. The request contains only the ticketID, the response looks like: - - -<Ticket id="ticketid" status="ticketstate" order="orderid" event="eventid" price="priceincent" orderpaystate="status of the order" /> - - -The attribute orderid may be <0 if the ticket is not attached to an order. - - - - - -Attribute Description status can be any of reserved, bought, used, refund, error (see getorder above for details) orderpaystate the payment status of the order, it can be "none" if the order is invalid or the ticket is not attached to one, "ok" if the order has been paid correctly, "cancelled" if the order was cancelled, "needpayment" if the order is not fully paid yet, or "needrefund" if too much has been paid - - Using Tickets - -The useticket transaction marks a ticket as used. The request contains only the ticket ID, the response has status ok and no body if the action succeeded, it has status error and an explanatory text if it failed. - -Only tickets that have status "bought" and whose order have payment status "ok" or "needrefund" can be used. The transaction fails for all other tickets. - - Changing Ticket Prices - -The changeticketprice transaction can be used to change the price of a ticket. The request contains the ticket-ID and the new price in cent separated by a newline. The response is empty. - -Returning Tickets - -The ticketreturn transaction can be used to return a ticket that has not been used yet. The request contains the ticket-ID, the response is empty. - - -Vouchers - -Rules for vouchers: - -a voucher with price and value zero is cancelled (the used flag is ignored in this case) - any non-cancelled voucher that is unused can be cancelled - any non-cancelled voucher can be emptied - a voucher with non-zero value can be used - - -Getting Valid Voucher Prices - -The getvoucherprices transaction can be used to retrieve allowed voucher prices. The request is empty. The response contains the allowed prices in cents, separated by spaces - it is empty if no voucher prices are configured. - -Using a Voucher - -The usevoucher transaction can be used to use a voucher for payment. The request contains the voucher-ID on the first line and the order to be paid on the second line. - -On success the response contains the amount that remains on the voucher on the first line and the now current amount that has been paid for the order on the second line. -On error the response contains an error message. - - Returning/Cancelling a Voucher - -The cancelvoucher transaction can be used to cancel a voucher. The request contains just the voucher-ID. The response is empty or contains an error message. - -For this transaction to succeed the voucher must not have been used. The price and the value will be reset to zero. If the voucher is already cancelled the transaction will report success. - - Destroying a Voucher - -The emptyvoucher transaction can be used to void any remaining value of the voucher. The request contains just the voucher-ID. The response is empty or contains an error message. - -This transaction simulates buying nothing for a lot of money: it sets the voucher to used and resets the remaining value to zero. The voucher will still have a price that needs to be paid and it cannot be returned/reimbursed afterwards. - -Only privileged users should be able to do this (if anybody at all). - - Getting a Voucher - -The getvoucher transaction can be used to retrieve information about a specific voucher. The request just contains the voucher ID, the response contains the XML representation of it (see the Voucher tag in the Order XML object for details). - -Using a Voucher outside the system - -The usevoucheroutside transaction can be used to remove value from a voucher without logging it to a specific order. The request contains the voucherid in the first line and the value to take in the second line. The response contains the actual value taken in the first line and the remaining value of the voucher in the second line. - - -Templates - -Templates are used for printouts and documents. There are several types of templates: - - -Open Document Text Template -XML Ticket printer template - - -Base names of templates are restricted to the regular expression ^[a-z0-9_]+$ and are case-insensitive. They may have an extension (legal values: "od[ts]t", "xtt") and a variant ID (at the moment numeric, but may match "^[a-z0-9_]+$"). - -Below "file name" refers to the complete concatenation of base name, extension, and variant: -basename.extension[,variant] - - List of Templates - -The gettemplatelist transaction returns an informational list of templates. The request is empty, the response looks like: - - -<TList> - <Template name="filename" hash="md5-hash">Description text</Template> - ... -</TList> - - -The Hash is caculated at the server side and can be used to find out whether the template has been changed. It does not necessarily need to be MD5 or any other specific algorithm, it can be any kind of ASCII string that shows changes (hence the client must remember the string if it wants to use it). - -Getting a Template - -The gettemplate transaction returns a specific template. The request contains only the file name, the response contains the template file as content. In case of an error the content is left empty and the status code is set appropriately. - -Setting a Template - -The settemplate transaction creates a new template file. The request contains the file name terminated with a newline ("\n") and then the binary content of the template - it is important that there are no additional characters between the newline and the template content. The response contains the new hash of the template or error details. The description is initially set to NULL and can be changed later with settemplatedescription. - -The settemplatedescription transaction sets a new description for a template. The first line of the request contains the filename, the remainder the description. - - Deleting a Template - -The deletetemplate transaction deletes a template from the database. The request contains the file name (full name). The response is empty. The transaction does not return any errors. - - - -Backup - -The currently implemented backup function is DB scheme dependent. This may change in the future. - -The machine interface only provides for the retrieval of the backup file. Restoration is done via admin.php. - -The backup transaction is used to retrieve a backup file. It does not have any parameters. The response is in the special backup format: - - -startbackup -backupversion 0 -dbversion 00.02 -table exampletab -value stringcolumn str TWFnaWNTbW9rZVZlcnNpb24= -value intcolumn int 1 -value boolcolumn bool 1 -value anothercolumn NULL NULL -insert -endofbackup - - -The format is command oriented: each line is a specific command that can be interpreted by the restore processor: - - - - - - - - - - -Command Description startbackup marks the begin of a backup file backupversion defines the format version (integer version number) of this backup file - this only shows which commands are valid, not what content can be transferred dbversion version of the database scheme this data is taken from table marks the start of a new table, has the (scheme-)name of the table as parameter, deletes the current dataset buffer value adds a value to the current dataset buffer, parameters are the column name, encoding format and value insert pushes the current dataset buffer into the current table, then empties the dataset buffer endofbackup marks the end of the backup file, the processor should stop here - -Table cell values are encoded according to the content in the source database. The target database must decode the values according to the format used in the backup file and then escape the value as appropriate for the target database (irrespective of the just decoded source format). - -The following encoding formats are currently known: - - - - - - -Format Description NULL a NULL value, the actual value in the backup file does not matter, the target value is NULL int integer, the value must be converted into an integer number bool boolean, the value "1" means true, the value "0" means false, everything else is an error and should be interpreted as NULL str string or blob, the content is base64 encoded - if it is a string the result of base64 decoding is in UTF-8 encoding - - - - \ No newline at end of file diff --git a/doc/server.html b/doc/server.html new file mode 100644 index 0000000..79ec4cb --- /dev/null +++ b/doc/server.html @@ -0,0 +1,144 @@ + +Magic Smoke Server + + + + + Creating a Magic Smoke Server Instance + +You need to build and install the system first. + +The steps below assume that you are using a Unixoid system. A lot of them will not work on windows, since the makefile for windows does not contain them and the symlinks used inside the server source tree are not present under Windows - you will have to do a lot of manual copying in that case. + + Prerequisites + +Make sure your web server, and database server work normally. + +Database Preparation + +Normally you can skip this section for ISP side installations, since your ISP will give you a database and the correct login data for it. + +MagicSmoke can work with MySQL or Postgres. Connect to your database server using a client of your choice (I'll assume the command line mysql client below, commands should be similar for other clients). + +Create a database user - I'll assume it is called "smoke" and uses "verysecret" as password. Create a database - I'll assume it is called "smoke". Then give the user all rights on this database. + +mysql> CREATE USER smoke IDENTIFIED BY PASSWORD 'verysecret'; +mysql> CREATE DATABASE smoke; +mysql> GRANT ALL ON smoke.* TO smoke; + + +MagicSmoke uses a common configurable prefix for its tables ("smoke2_*" per default), so you can use an existing database or even use the same database for multiple installations or different programs (assuming the other programs are as tolerant as MagicSmoke). If you have the possibility it is however recommended to give each MagicSmoke instance its own database, since it is easier to drop and restore entire databases insted of just parts of them. + +MagicSmoke2 can be installed in parallel to the old MagicSmoke 1.0 packages, but it cannot access the same tables (upgrade is possible though). + + Server Instance Creation + +You can skip this part for ISP side installations, instead follow the instructions for Installation on an ISP Account. + +During installation you copied all MagicSmoke sources into a central directory. MagicSmoke supports being run as multiple instances. For each instance you have to chose a target directory in which you want to configure it. + +Execute /usr(/local)/share/magicsmoke2-server/install.sh with your target directory +as parameter. This will link the current version of MagicSmoke into the target directory, if you have already made a configuration there it will not touch it. + +If the target directory is not already inside the DocumentRoot of your server, link the target directory into your web server - either with a symlink or an Alias configuration statement. + + Configuring MagicSmoke + + +Now edit the config.php file, it is a simple PHP file. Although theoretically +all facilities of PHP are available there, you should stick to the format of +the template to avoid unintended side-effects. + +The configuration file contains several sections: + + Database Options + +The database section describes which database is used for storing data and +how the database interface behaves. + +The $db variable is supposed to point to an object of a class derived from +DbEngine. There are currently two of those: + +MysqlEngine uses the MySQLi interface of PHP to access a MySQL 5.x database + PGsqlEngine uses the PGSQL interface of PHP to access a Postgres database. +To be compatible with MagicSmoke the server should be at least version 8.x + + +Examples and directions are available in the configuration file template. + +The $olddb variable if set can be used to upgrade a MagicSmoke 1.0 database +to version 2.0. After upgrade you should comment it out. + +There is one option stored in the DB-Engine that is only used for database creation and recovery: + +$db->setAdminPassCode("Admin","SmokeInMyEye"); + + +This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users. Change the second parameter (password) to something else (preferably something hard to guess), so I won't be able to guess your admin password in case you forget to comment it. + +Dedicated Client Configuration + +This section configures the behavior of the server towards the dedicated client. + +There is only one option: the timeout for client sessions. It is safe to leave it at the default setting - making it short potentially confuses the client into re-establishing the connection immediately, if the clock between server and client are significantly off, making it longer does not have any effect since the client automatically renews the session when it nears its end. + + Web Client Configuration + +This section configures the behavior of the web interface. + +These options configure the timeouts of cookies, what features are available to users and what features of the template engine are available. + + + Database Initialization + +Open a browser and direct it to admin.php in your MagicSmoke installation (usually something like http://localhost/magicsmoke/admin.php). + +The default user name is "Admin" and the password is "SmokeInMyEye" - or whatever you have configured above. + +Click the create database button. + + Initial Installation + +Create an initial administrator user using the form at the bottom of the page. + +Done. + + Upgrade from MagicSmoke 1.0 + +MagicSmoke2 is not able to import old MagicSmoke Backups, you need to import those with an old installation and then convert them as described below. + +If you have set up the $olddb variable in your configuration MagicSmoke will offer to migrate data. Do not attempt migration if your new database already has some data stored. + +Please make sure that the old and new database do not share tables - at the very least the database name or the table prefix should be different. + +The upgrade may take some time - you should make sure that PHP scripts do not abort too soon. On a normal workstation this will take about 2-4 minutes for a database with a few thousand orders. If it fails you should empty/recreate the new database and start over. + +Simply enter "upgrade" into the input line and click the button. + +The format of customers in the database has changed significantly. The upgrade process tries to guess what part of customer names and customer address belong to which detail. This heuristic may fail in some cases, you should go through your customer list and correct any mistakes afterwards. + +When you are done comment out the $olddb configuration to avoid initializing it for every call of a script. + +The migration process does not touch the old tables. + + Both + +Comment out the "setAdminPassCode" line in config.php, so that no one else can abuse this interface. + +From now on you can access it with the MagicSmoke client. Your URL for the client ends in machine.php (eg. http://localhost/magicsmoke/machine.php). + + + Creating Templates + +The template/* sub-directories of your target directory contain collections of template files. These are used to generate the user interface that users get to see. Each sub-directory of template is the name of a language in ISO 639 coding - e.g. "en" stands for English, "de" for German, etc. The link "C" (upper-case) points to your fall-back language that is used if the users browser does not support one of the available languages. + +Please read the chapter about Template Design and create your own set of templates (or customize an existing one). + +If you plan to store your templates in a different directory modify the template line in your config file, eg.: + +$template="/home/erwin/mytemplate/"; + + + + + \ No newline at end of file diff --git a/doc/template.html b/doc/template.html index 3c75b0a..e493526 100644 --- a/doc/template.html +++ b/doc/template.html @@ -5,47 +5,33 @@ Magic Smoke Template Design -The web user interface is constructed with templates with just a few dynamic values filled in. Thos templates are found in the www/template/* directories. These templates are normal HTML (actually: you chose the version of HTML that is used) with some special constructs to fill in the blanks. - -In order to create your own templates copy one of the template directories and start to modify the files in there. Usually it should be enough to change the layout.html template. If you use relative links inside your templates they will be interpreted as relative to the index.php script. - - Syntax - -The most important element of templates are variables. Variables can be set by the template itself, or by the script. Wherever the value of a variable needs to be inserted it is simply placed between two "@" characters, eg. "Variable XYZ contains @XYZ@". These value replacements can occur anywhere in the text, whereas all other syntactical elements must appear on a line of their own. - -Variables can be set and unset using the special #set and #unset commands: - -#set:VARIABLE=value -#set:LONGVARIABLE: -some values containing anything -#endset - - -The first version of the set-syntax just assigns everything behind the "=" to the variable named before it. The second version of the set-syntax assigns everything between the #set and #unset lines without replacing any values or interpreting any syntax. - -Conditional parts of the template text can be put between #if and #endif: - -#if:VARIABLE==value -text that only appears if VARIABLE contains value -#endif - -All comparisons are made as string comparisons (this eg. means "2" is greater than "100") with both the variable and the comparison value trimmed. Possible operators are: - - - - - - - -== matches if the variable contains exactly this value < matches if the variable is smaller than this value > matches if the variable is greater than this value <= matches if the variable is smaller or equal to this value >= matches if the variable is greater or equal to this value != or <> matches if the variable does not contain this value +The web user interface is constructed with templates with just a few dynamic values filled in. Those templates are found in the template/* directories. These templates are normal HTML or text with some special constructs to fill in the blanks. + +Please see the Twig template engine documentation for syntax details. Template Files -layout.html +There are template files for everything that is displayed on the web page and for all types of eMail sent by the MagicSmoke customer system. + +Each of the example templates contains some hints what data is available. Most objects are types from the Web Object Interface. + +Please see the Templates Chapter of the PHP Source Documentation. -This is the main template that contains the static parts of all pages displayed by Magic Smoke. + Template Caching -The only variable inside it is @PAGE@ which is replaced by the context created using one of the other templates. +The Twig template engine compiles the templates into PHP code before actually displaying anything. You have to choice to discard those compiled templates or to store them for faster access next time the page is called. Allowing the web server write access to a directory opens a potential security hole. If you want to do caching securely: + +create a storage directory in parallel to the template directory, eg. tcache, or if it already exists empty it +make sure the directory is writable by the web server +enter this directory into the Twig configuration: +$twigoptions=array( 'cache' => './tcache' /*...*/ ); +make it writable for the web server +uncomment the "setAdminPassCode" line in config.php +open index.php?mode=compile in a browser - it will ask you to enter the admin credentials +the page will compile all templates it can find and store them in the configured cache directory +restrict the directory access rights so the web server cannot write to it any more, make sure it can also not overwrite the files +comment the "setAdminPassCode" line in config.php + \ No newline at end of file diff --git a/doc/tzone b/doc/tzone new file mode 120000 index 0000000..cdca883 --- /dev/null +++ b/doc/tzone @@ -0,0 +1 @@ +../tzone/sourcedoc \ No newline at end of file diff --git a/www/inc/rendering/cart_listing.php b/www/inc/rendering/cart_listing.php index 2dde2a2..cbbe8e1 100644 --- a/www/inc/rendering/cart_listing.php +++ b/www/inc/rendering/cart_listing.php @@ -128,7 +128,29 @@ static public function getNewCartId(){ } -/** creates the cart overview */ +/** \page templates Templates +\section tpl_cart Cart Variables + +The cart.html template is used to render the current cart of the customer. + +\param cart an object of the web type WebCart (PHP: WOWebCart) that represents the entire cart of the user. +\param shipping and array of web objects of type Shipping (PHP: WOShipping) which represent all available shipping types that customers can chose from. +\param forceshipping a boolean that contains whether customers must chose a shipping type. + +\section tpl_carterror Cart Error Variables + +The carterror.html template is used to when the cart expired or the customers browser lost the cookie. + +Just the \ref tpl_base Base Variables +are available. +**/ + + +/** creates the cart overview + +for templating info see \ref tpl_cart Cart Variables +and \ref tpl_base Base Variables +*/ static public function createCartOverview() { global $twig,$basevars,$WebForceShipping; @@ -163,7 +185,6 @@ static public function createCartOverview() return $p->render($list); } - //end of WebCart }; diff --git a/www/inc/rendering/event_listing.php b/www/inc/rendering/event_listing.php index de5cb35..0628d8d 100644 --- a/www/inc/rendering/event_listing.php +++ b/www/inc/rendering/event_listing.php @@ -10,7 +10,22 @@ // +---------------------------------------------------------------------- // +/** +\page templates Templates +\section tpl_index Event List +The index.html template is used to render the list of events available to customers. + +\param events an array of the events available, starting at the current time, ordered by time; the events are of web object type Event (PHP: WOEvent) + +\section tpl_eventdetail Event Details + +The eventdetails.html template is used to render a single event and to offer the user to buy tickets for it. + +\param event the event being rendered; the event is of web object type Event (PHP: WOEvent) +*/ + +/** wrapper arount event (list) rendering for the web UI*/ class EventRender { /** creates an list of events */ @@ -31,8 +46,7 @@ public static function createEventList() if(!$session->checkFlags($event->getflags()))continue; //encode as array $list['events'][]=$event; - } - + } //pass 2: create page return $p->render($list); } diff --git a/www/index.php b/www/index.php index ecd043b..b9f5b67 100644 --- a/www/index.php +++ b/www/index.php @@ -34,6 +34,43 @@ foreach($twigextensions as $te){ $twig->addExtension(new LangFilterExtension); $twig->addExtension(new SmokeFilterExtension); + +/** \page templates Templates +\section tpl_base Base Variables + +There are some variables available for all templates. + +\param script.* variables contain URLs for different modes of the web site: + + + + + + + + + + +script.root root URL for the index.php script script.this the URL of the currently called script mode script.index URL of the list index script.eventDetails URL for event detail pages, append the event ID to it to complete it script.eventOrder URL for ordering tickets for a specific event, arguments are expected as POST parameters script.cart URL of the cart, the cart must exist when calling it, otherwise a cookie error will be displayed script.mycart URL of the cart that transparently creates the cart if it does not exist yet script.checkout URL to check out the cart script.setlanguage URL for setting the language cookie, add the language code to it to complete it +\param inputnames.* variables contain names for specific form input elements: + + + + + +inputnames.amountTickets amount of tickets to be ordered inputnames.event contains the event ID inputnames.mode contains the display mode inputnames.cartid ID of the cart of the current customer, usually the cart cookie is used instead +\param cartcookie variable contains the name of the cookie that contains the cart ID. +\param lang variable is an object of type LanguageManager - it represents translations done for the language the user has chosen. + + +\section tpl_error error.html + +This template is used whenever an error occurs during processing. + +\param ErrorText the text to be shown for an error +\param ErrorTrace a full ASCII version of an exception trace. This is only filled if the $WebShowErrors option is set to true in the config.php file. +**/ + //basic variables shared by all templates // script URLs $basevars['script']['root']=$_SERVER['SCRIPT_NAME']; @@ -124,6 +161,7 @@ try{ $e["ErrorText"]=translate("WebSite","An error occured, contact the server admin for details."); $page=$p->render($e); } + //spit out completed page header("Content-Type: text/html; charset=utf-8"); print($page); -- 1.7.2.5

Rule	Description
all	complete build
server	everything that is necessary for the server
client	the client

sdoc	source documentation (not included in all), requires doxygen and markdown
install	build and installs everything: server, client, documentation
install-client	build and installs the client
install-server	build and installs the server components
install-doc	build and installs documentation (including source documentation)

md5	Uses the MD5 hash algorith described in RFC1321. Please note that this algorithm is regarded as broken and should not be used.
sha1	Uses the SHA-1 hash algorithm described eg. in RFC3174. Please note that this algorithm is theoretically broken, although the use of this algorithm in Magic Smoke should still be secure for a few years.
sha256	Uses the SHA-256 hash algorithm of the SHA-2 hash family. This algorithm is currently recommended as replacement for SHA-1. However, it is currently not supported by any client.
hmac-md5, hmac-sha1, hmac-sha256	Uses the same hash algorithms in HMAC mode (see RFC2104). This use is more secure than the plain use of the algorithms. It is recommended to use HMAC.

string	Doesn't use any extension and instead uses the string functions md5 and sha1. This mode does not support sha256 or any of the hmac-modes.
hash	Uses the "hash" extension. This extension supports all modes listed above.
mhash	Uses the "mhash" extension. This extension supports all modes listed above.

x-magicsmoke-request	The request that is to be executed by the server. This header is mandatory for all requests.
x-magicsmoke-session	The session ID of this connection. This header is mandatory for all requests except `serverinfo` and `startsession`.

(missing)	If the whole header is missing or contains an unknown value, this should be treated as if it contained "Error" (see below).
Ok	The request went ok and the actual data comes as response body.
Error	Some unspecified error occured. The response body might contain some detailed human readable information.
NonPost	The HTTP method was not POST. The body is a simple HTML page explaining to the user that browsers are not meant to use this page.
Unauthenticated	The session ID does not exist, authentication failed or the session expired.
NotAllowed	The user does not have the right to execute this transaction.
InvalidRequest	The request was not understood. There was probably a mismatch in client and server version.
SyntaxError	There was a syntactical error in the request data. Some details might follow in the response body.

md5, sha1, sha256	use the hash algorithm directly, the returned value is calculated by first concatenating challenge and password/hostkey and then hashing it
hmac-*	use the same algorithm in HMAC mode with the challenge as data and the password/hostkey as key

id	the ID of the event
start	the start time as Unix timestamp
end	the end time as Unix timestamp
capacity	how many tickets may be sold for this event
defaultprice	the default price for tickets as integer in cent (or penny or ...)
cancelled	optional: "true" or "false" -- shows whether the event is cancelled, default is "false"
Title	the title of the event
Artist	the artist appearing
Description	a description for the web page, may contain HTML
Room	the room it is happening in (the room must exist in the list of available rooms)
CancelReason	optional: if the event is cancelled, the reason for it (human readable)

Item	Description	Occurrence
Order	Container for one single order or sale	1
id	ID of the order, if already known.	0-1
customer	ID of the customer. Mandatory.	1
seller	Login of the seller. Automatically filled in.	0-1
ordertime	Time of the order. Automatically filled in.	0-1
senttime	Time at which the order was shipped. Automatically filled in.	0-1
totalprice	Total accumulated price of the order. Automatically filled in.	0-1
paid	Amount that has already been paid. Automatically filled in.	0-1
status	Current status of the order. Automatically filled in. See table below.	0-1
Ticket(*)	data about a single ticket bought in this order	0-unlimited
id	ID of the ticket	1
event	ID of the event this ticket refers to.	1
price	Price of the ticket	1
status	Status of the ticket (see below)	1
Voucher(*)	data about a single voucher bought in this order, vouchers that are used to pay for an order are not stored	0-unlimited
id	ID of the voucher	1
price	Price of the voucher (adds to price of the order)	1
value	Value (in cent) of the voucher (does not add to the order, but refers to how much the voucher is worth)	1
status	only in validation responses: result of the validation	0-1
used	Flag whether the voucher has been used to pay for anything (assumed as 0 if not present)	0-1
Shipping	information about the kind of shipping used and how much it costs; if text is used it is a copy of the text from the shipping table information - it cannot be changed here	0-1
price	Price of the shipping option	1
type	shipping type ID	1
DeliveryAddress	the address to send the stuff to, if not present or empty the address of the customer is used	0-1
Comment	comment entered into the order by customer or seller	0-1

Status	Description
placed	The order has been placed, nothing has been sent or paid yet.
sent	The order has been shipped.
reserved	The order has been reserved. This means the tickets are blocked, but it cannot be paid or shipped.
cancelled	The user cancelled an unshipped and unpaid order.
closed	The order is final and cannot be altered. (State maybe not needed.)

Status	Description
bought(1)	The ticket is valid; whether it is paid for depends on the order status.
refund(2)	The ticket has been or needs to be refunded; eg. after the event or order was cancelled.
used(1)	The ticket has been used.
reserved	The ticket is reserved. This state is currently not used.

Element	Attributes in Request	Attributes in Response
Order	customer	id(1), customer, seller(3), ordertime(1,4), totalprice(5), paid(1), status(6), senttime(2,4)
Ticket	event, price(7)	event, id(1), price, status(6)
Voucher	value, price(7)	value, price, id(1), status(11)
Shipping	type(8), price(9)	type(10), price, [text](10)
DeliveryAddress	[text]	[text]
Comment	[text]	[text]

State	Description
ok(1)	the order can be executed as is
saleonly(2)	the order can only be continued as a sale, not as an open order
orderonly(2)	the order can only be continued as an open order, not as a sale; this state also shows that there is a problem with the configuration
fail	the order contains failed items

State	Description
[empty]	the order can be executed as is
invalidvalue	the user is not allowed to use this value for the voucher
invalidprice	for this user the price must equal the value (or be ommitted)

Attribute	Description
status	can be any of reserved, bought, used, refund, error (see getorder above for details)
orderpaystate	the payment status of the order, it can be "none" if the order is invalid or the ticket is not attached to one, "ok" if the order has been paid correctly, "cancelled" if the order was cancelled, "needpayment" if the order is not fully paid yet, or "needrefund" if too much has been paid

Command	Description
startbackup	marks the begin of a backup file
backupversion	defines the format version (integer version number) of this backup file - this only shows which commands are valid, not what content can be transferred
dbversion	version of the database scheme this data is taken from
table	marks the start of a new table, has the (scheme-)name of the table as parameter, deletes the current dataset buffer
value	adds a value to the current dataset buffer, parameters are the column name, encoding format and value
insert	pushes the current dataset buffer into the current table, then empties the dataset buffer
endofbackup	marks the end of the backup file, the processor should stop here

Format	Description
NULL	a NULL value, the actual value in the backup file does not matter, the target value is NULL
int	integer, the value must be converted into an integer number
bool	boolean, the value "1" means true, the value "0" means false, everything else is an error and should be interpreted as NULL
str	string or blob, the content is base64 encoded - if it is a string the result of base64 decoding is in UTF-8 encoding

==	matches if the variable contains exactly this value
<	matches if the variable is smaller than this value
>	matches if the variable is greater than this value
<=	matches if the variable is smaller or equal to this value
>=	matches if the variable is greater or equal to this value
!= or <>	matches if the variable does not contain this value

`script.root`	root URL for the index.php script
`script.this`	the URL of the currently called script mode
`script.index`	URL of the list index
`script.eventDetails`	URL for event detail pages, append the event ID to it to complete it
`script.eventOrder`	URL for ordering tickets for a specific event, arguments are expected as POST parameters
`script.cart`	URL of the cart, the cart must exist when calling it, otherwise a cookie error will be displayed
`script.mycart`	URL of the cart that transparently creates the cart if it does not exist yet
`script.checkout`	URL to check out the cart
`script.setlanguage`	URL for setting the language cookie, add the language code to it to complete it

`inputnames.amountTickets`	amount of tickets to be ordered
`inputnames.event`	contains the event ID
`inputnames.mode`	contains the display mode
`inputnames.cartid`	ID of the cart of the current customer, usually the cart cookie is used instead