[horde] of Skeletons and Zombies: automatically create new horde apps

[Karsten Fourmont]

Hi,

I noticed that the skeleton module is somewhat out of date. IMHO it is 
also not too helpful to new developers as it does not contain actual 
functionality.

So I created Zombie as a alternative to Skeleton.

It seems to me that many (potential) horde applications (or maybe 
webapps in general) are based on a main database table: you have a list 
of table entries, a page to view a single entry, and a page to edit an 
entry.

Zombie's idea is to give you a jumpstart into developing such apps.

Zombie is based on nag (from cvs-head a few weeks ago). I stripped the 
code down to the bare  essentials of editing a database table:  no 
shared/multiple lists and such.  All  references  to tasks and ask-lists 
had to go as well. The result is a template rather than an  application 
  itself.

I then wrote a script (makezombie.php) which takes any database table as 
input and  creates a working horde application based on the template but 
with all  the modifications for the given table. The template contains 
!!ZOMBIE!!-stubs
where table dependant codes is required. The scripts injects code there.

The following features are created:

-standard pages for these tasks:
   - list: list complete database table
   - view: view one table entry
   - edit: edit of single entry. With fancy datechoosers for date/time
     fields.
   - delete: delete entries from database
   - prefs: startup implementation for setting default sorting order
   - configuration: selection of table and database
- complete code for column sorting (always annoying to do that manually)
- charset conversion between database and horde
- transparent conversion between sql date types and php unix epoch
   timestamps

The created app is intended to be a starting point for further development.

The name "Zombie" was chosen as a zombie can be seen as a skeleton with 
some flesh automagically attached to it, so it acts like being alive. 
Basically that's what an app created by the mazombie script is.

The current version (initial release) can be downloaded here:

http://www.fourmont.com/zombie/zombie.tgz

Unpack it in the horde directory like any other horde application as well.
Read REAME and call 'php -f makezombie.php' in the scripts directory to 
get some usage information.

I attached the Zombie README for reference. It contains a quick tutorial.

Please let me know what you think. I've written it for my own needs but 
maybe others find it useful as well. Of course it's GPL (most of the 
actual code is derived from Nag) and I'd be happy if this or something 
like this makes it into Horde's CVS.

Best Regards
  Karsten
-------------- next part --------------

Zombie Version 1.0

What is Zombie?
===============

Zombie is a hack to quickly create a skeleton app in horde.

It takes a database table as input and creates a working horde application
around this table. These features are provided:

- standard pages for the following tasks:
  - list: list of complete database table
  - view: view of one table entry
  - edit: edit of single entry. With fancy datechoosers for date/time fields
  - delete: delete entries from database
  - prefs: startup implementation for setting default sorting order
  - configuration: selection of table and database
- complete code for column sorting
- charset conversion between database and horde
- transparent conversion between sql date types and php unix epoch timestamps

The created app is intended to be a starting point for further development.

The name "Zombie" was chosen as a zombie is basically a skeleton with some
flesh attached to it, to make it act like being alive.

TUTORIAL/QUISTART
=================

This section lets you create an application to modify the nag_tasks table.
Of course zombie makes real sense only when you use your own table rather
than one for which the horde app is already there. But this is an example.

You need to have Horde and Nag installed to run this. Here we go:

1) run tar -xvzf zombie.tgz in the main horde directory.
2) go to zombie/scripts and run php -f makezombie.php nag_tasks
3) edit zombieconf.php:
  - change the type for task_due from int to unixepoch
  - change $config['app']   = 'app'; to
           $config['app']   = 'myapp';
4) run php -f makezombie.php zombieconf.php
5) append the contents of horde/myapp/registry.stub
   to horde/config/registry.php
6) direct your browser to http://my_horde_url.com/horde/myapp/
   Voila! Your very own new horde app.
   Click on a task item to get the detail view and on edit to edit an item.
  

HOW TO USE
==========

The Zombie application should be unpacked under the horde directory like any
normal horde app. However it acts as a template rather than as an app itself.

The magic is done in the makezombie.php command line script in the scripts
directory.

Call 'php -f makezombie.php' without any arguments to get a usage summary.

As a first step you call the makezombie script with the name of a database
table. If you want to run makezombie on the nag_tasks table as a test, use

php -f makezombie.php nag_tasks

For tables that are not in the horde database you can provide a dsn with
the -d command line option.
Makezombie creates a zombieconf.php file.
Now you can (but don't have to) edit it to suit your needs. You might
especially want to change the name of the target  app to  something
different  from "app", as this is the target directory for the new app and
gets inserted in the source code at various places. You can also change
the name for 'item' and  'items' to maybe 'task' and 'list'. Please note
that these are used as variable names in the source code as well, so
including whitespace is a really bad idea.

After editing the config file, a second call to makezombie.php creates the
application:

php -f makezombie.php zombieconf.php

The files will be written to a new directory under horde/. Now you can

1) paste content of app/registry.stub to horde/config/registry.php.
   After that, the app should be working!
2) replace app.gif with proper application icon
3) start playing around and enhancing your new horde application

Please note that the zombie directory is only needed for running the
makezombie script. Afterwards (or in a production enviroment) it can
be safely deleted. The app resides completly in the new app dir.

TIPS FOR EDITING THE CONFIG FILE
================================

1) you may change the field type to adjust it to your needs. E.g. if you
   have a datetime field but are only interested in the data part, just
   change it to "date". Of course these changes must be compatible: changing
   an int to a string gets you into serious contflicts with the sql syntax.
  
2) you may change integer fields that represent boolean 0/1
   values to 'boolean'. Then they get rendered using checkboxes.

3) for date/time information that are stored as unix epoch (php) int values
   in the database (like horde does), you can manually set the field type to
   - 'unixepoch' for datetime values (date and time is shown)
   - 'unixdate' for date only values
    -'unixtime' for time only values
   Then the apprioriate renderers and edit widgets are used.
  
  
KNOWN LIMITATIONS
=================

- writing of 'timestamp' fields does not work with older mysql versions.
  Reading is OK though.
- The database table must have a single primary_key field with flag
  primary_key set. You can add the flag manually in zombieconf.php.
- Adding of new database entries currently works with horde style
  varchar primary keys only. For other pk's (database automatically
  or Pear::DB  sequences) you have to modify the add method in Driver/sql.php

Enjoy!