Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Message-ID: <446209AF.7090809@thebug.it>
Date: Wed, 10 May 2006 17:41:35 +0200
From: Simone Gianni <s.gianni@thebug.it>
User-Agent: Mozilla Thunderbird 1.0.6 (X11/20050807)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Cocoon CRUD (was GSoC Proposals)
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

Hi all,
me and Maurizio were very interested in this GSoC too. Unfortunately,
none of us could apply as a student for it, but it was our intention to
produce something similar even before it was proposed as a GSoC.

So, we'd like to share our thought with all the list, and plan to work
on this starting from the end of this month.

Jason, you are *obviously* invited to share your thoughts and to
cooperate in developement as much as you want, we all think cocoon needs
this stuff done in the best way, as soon as possible, and with friendly
and open cooperation. So let's merge our efforts in the most productive way.

Description of our project follows.

	--- Main ojbectives and requirements ---

The goal of the project is to provide a configurable and customizable
framework for Cocoon Forms that allows Cocoon developers to build a
simple cforms application. Traditionally, developers need to do this by
writing 3 xml files and a flow, not considering setting up a persistence
layer, which can be overkill for simple apps.

The application will basically comprise some java classes that operate
on a "database" performing the following operations :
- Fetching of metadata (column names, column types, column length limits
etc..)
- Perform a "select * where" to retrieve all the rows and display a list
- Perform an "insert" to add a new row in the table
- Perform a "select * where" to retrieve a single row
- Perform an "update" to update an existing row
- Perform a "delete" to remove an existing row

This set of classes will be realized in the conventional
insterface/abstract base/concrete implementation fashion, thus
permitting a power user to implement their own persistence components to
realize CRUDs on, say, an LDAP directory, a CSV file or whatever else
they can manipulate with a CRUD.

The default implementation will work on a relational database, using
JDBI as a persistence layer, and will require a configuration indicating
only database connection parameters (datasource name, or Spring bean
name, see later) and the table names.

Since metadata will not be enought to relize a smooth user experience,
we think that the basic configuration should be, optionally, expanded
using an XML configuration file that defines:

1 - the foreign keys, and/or details on their operation (for example,
which columns use as labels, wether to use a dropdown, a popup etc..)
2 - custom validations
3 - custom field styling
4 - custom listeners
5 - custom javascript/java hooks

These informations will be used to generate a form definition and
template. We don't think we will need a binding file, since we will use
the form to Map paradigm to send and receive data from JDBI and other
possible implementations of the persistence classes.

The first three are used to create a cforms Form Definition; starting
from that, using 4 and 5, the Form Template is created.

As you can see there is no mention of labels. Labels will be delegated
to i18n, using well defined i18n keys, for example
label.<table-name>.<column-name> or similar.

Point 6 will be used to define some hooks on the controller, so that it
will be easy to customize also the controller without having to write a
custom flow. This a brief and partial list of hooks we were thinking about :

- loadData : permits to operate on the Map containing data before this
data is binded to the form
- sendForm - initializes the Form object before the form is sent to the user
- formSubmitted - operates on the Form object after the user submitted it.
- saveData - operates on the Map containing data before this data to
perform custom operations; this can also be used to perform custom
(application scoped) server-side validations, and eventually send Form
execution from the beginning or dispatch the request to a custom cocoon URI.

We will strive not to introduce completely new XML grammars, so we will
try to reuse as much as possible already defined ft:, fd: and fi:
elements in a way that only custom parts can be written by the user and
merged with default settings.


            --- Technical draft ---

The file generation is performed using a processPipelineTo from the
JavaFlow, that allows the definition of the Form Definition and/or the
Form Template from scratch by simply adding a sitemap match that follows
a predefined name convention (e.g.
<table_name>-<crud_operation>-<def|tpl>.xml).

The Form Binding will be totally managed by JDBI, loading and saving
data using SQL Maps; no extra work is needed since the introduction of
the formToMap and mapToForm methods.

Using the custom Javaflow hooks the developer is allowed to implement
predefined interfaces or define javascript snippets and operate on the
Form object as well as the database information.

JDBI already has a bean written for Spring environments, that will
simplify the configuration process. Spring usage will obviously not be
mandatory, so that code will work also on 2.1.X without other
dependencies, but code will be written taking Spring in consideration so
that 2.2 integration will be complete.


            --- Planning ---

The realization of the project is composed of 3 milestones (+1 that
still need to be defined but we think it's worthwhile to mention it)

Milestone 1
-----------
- Basic implementation of persistence classes, but not with matadata
extraction
- Basic Javaflow implementation to provide list, write, edit and delete
operations
- User will need to write cform Form Definition

Milestone 2
-----------
- Form Definition generated by database metadata
- Spring integration


Milestone 3
-----------
- Suport for foreign keys (one to many relations)
- Additional configuration parsing: validations, styling, listeners,
foreign keys and flow hooks


Milestone 4
-----------
- Adding search criterias in a "Query by example" style as an
alternative to a plain list.
- Some way of integration or migration to-from Ruby on Rails.
- Some way of migration to use penrose libraries to define relationship
between tables, so that data can be translated to other data models,
such as LDAP.


WDYT?

Simone and Maurizio

-- 
Simone Gianni