FiForms Framework: Framework for rapid Web application development

FiForms Framework 1.1
===============================

This is the README for the FiForms Framework version 1.1. 
The FiForms Framework enables developers to build web/database 
applications rapidly in XML. Using the unique FiForms XML 
Application Markup, a developer can build a complete database 
application without writing a single line of PHP code. 
      
History

FiForms started as a collection of PHP classes for creating web-based data 
entry screens for a MySQL database. It has since grown into a collection 
of projects addressing many aspects of web-database development needs. 
The FiForms framework currently includes the FiForms data-entry classes 
and the FiReports XML report generation scripts. These libraries are 
combined scripts which utilize the new XML capabilities of PHP version 5 
to create a framework for developing web applications completely in XML. 

The latest version of this software is available at the following web site:

  <http://www.fiforms.org>

You can find documentation and setup instructions for the FiForms Framework
on the wiki:

  <http://wiki.fiforms.org/>

Documentation for XML schemas can be found at

  <http://xml.fiforms.org/>
  
Quick Installation
==================

To get FiForms up-and-running quickly, we suggest you follow the instructions
outline on the wiki page http://wiki.fiforms.org/index.php/Installation

Requirements
============

Before you can use FiForms, you must have the following software installed on 
your system:

*   an operating system (of course)
        FiForms should work on any operating system that Apache and PHP
	will run on. Most of the development and testing of FiForms has
	been done on Linux, but it should also run under Windows, OS X,
	BSD, etc. 

*   an http webserver (works best on Apache webserver)
            <http://apache.org> 

*   MySQL database server <http://mysql.org> 
	FiForms works well with MySQL 4.0, 4.1, and 5.0. It should also 
	work with other versions.

*   a PHP interpreter <http://www.php.net> FiForms requires PHP 5.x. 

*   Php.XPath (this is included with FiForms if you are installing using
        a pre-built package or installer)
        <http://sourceforge.net/projects/phpxpath/> 

*   XSLTProc (required if you will be using FiReportsXML with server-side
	      transformation, and you are not using PHP_XSLT)
	<http://xmlsoft.org/XSLT/>
	Install libxslt on your operating system and configure the path
	to XSLTProc in FiForms_global.inc.php

	Note to windows users:  
        A package containing all the programs you need is available at
        http://downloads.sourceforge.net/myforms/FiForms_Binary_Dependencies_Win.zip

        This is a compliation of binaries available on Igor Zlatkovic' website:
	http://www.zlatkovic.com/libxml.en.html You can, alternativly, download
	libxml2, libxslt, iconv, and zlib from his website yourself. Extract 
	each zip file and copy the contents of each bin directory into 
	a single directory. Then point FIFORMS_XSLTPROC to the path you set.
	For example, if you copied the files to c:/libxml2, put this line 
	in FiForms_global.inc.php:

	define("FIFORMS_XSLTPROC","c:/libxml2/xsltproc.exe");
	

*   A Web Browser (On each client machine)
      Recommended: Mozilla Firefox Web Browser
             <http://mozilla.org/>

	Note: FiForms Forms should work fine in any browser
	     (Firefox, Lynx, IE, etc). Depending on the way you configure
	     the FiReport generator, you may require a browser that
	     supports XML and XSLT (Firefox and IE 6 both do). This is the
	     case if FiReports is configured for client-side transformation.
	     If it is configured for server-side transformation, you will
	     have to have xsltproc installed on the server but any browser
	     will work on the client (including Konqueror, Lynx, and older
	     version of IE which don't support XML). 

*    Jaxe or your favorite XML editor (http://jaxe.sourceforge.net/)
	This software can save you a lot of time in creating FiForms XML 
	applications. Jaxe configuration files for the FiForms XML schema
	are included in the package under example/jaxe. Simply copy these
	into your jaxe/config directory to start using them. 

Installation
============


Unzip the contents of the archive file into a new directory (if
you have not already done so). We recommend placing FiForms
outside of the DocumentRoot of your webserver, and configuring
an alias to the scripts/ directory of FiForms in your
webserver configuration.

Once FiForms is installed, direct your browser to the scripts path
in the new installation, for example, http://localhost/scripts/
or http://localhost/FiForms/scripts/ . You should be greeted
with a configuration screen, where you can set parameters. 

Follow the on-screen instructions to complete the installation.

Now you should be ready to start creating FiForms XML applications. 

Take a look at the examples included with this distribution. This
will show you how you can make some simple FiForms. Before you can use the 
sample scripts, you will need to set up the MySQL database FiForms_sample. Use
the included FiForms-sample.sql script to set up the database with the 
necessary tables. Of course, there are a lot more features in FiForms than are 
documented in the sample applications; please refer to the wiki and XML
documentation online.


5-Minute Tutorial
=================

FiForms XML Application
-----------------------

Create a new directory structure under the apps directory in FiForms. The top 
level directory should be the name of your app. This directory should contain
three subdirectories named forms, menus, and reports. All directory names are
case-sensitive.  "Register" the application by creating the appinfo.xml
file in the application root. Create a Main Menu called main.xml in the menus 
directory. Place form and report definitions in their respective folders. 
References from the menu are relative to the base of their respective folders; 
i.e. you do not need to specify path in the href when linking to forms and 
reports from your menu. See the example application for more ideas.

FiForms PHP Application
-----------------------

Create your PHP scripts anywhere you want, but make sure the scripts are able
to find the include files. This can be done using .htaccess files similar to
the one in the example directory, or by adding the FiForms_includes directory
to your include_path in php.ini. 

For both XML Applications and PHP Applications, please make use of the example
files included with this distribution. 

Note: this method of creating applications is no longer recommended; please
consider creating your new applications in XML.

Authors
=======

Founding Author: 
    Daniel McFeeters <databases at alltel dot net>

Contributing Authors: 
    Kristina Reeve <covrainbow at yahoo dot com>
    D. Kevin Burk <dkburk at gmail dot com>
    Jared Colangelo <pilotpencil at users dot sourceforge dot net>

Credits
    Kristina Reeve
        Development assistance, consultation, and inspiration to 
        keep this project going.
    The Somerset Oil Refinery <http://somersetoil.com>
        Supporting development, testing software
    Jim McFeeters <http://scc-it.serveftp.net>
        Teaching me programming, and helping with suggestions
	in several features of FiForms
    D. Kevin Burk
        For (indirectly) challenging me to write this
	in the first place. 


Contributing
============

If you would like to contribute to this project, or if you have any questions 
or suggestions, send an e-mail to Daniel McFeeters <databases at alltel dot net>


Bugs and To-Do List
===================

See the Wiki http://wiki.fiforms.org/


License
=======

    Copyright (C) 2003-2008  Daniel McFeeters

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA