root/branches/gettext/rfcs/rfc0002.txt

patForms RFC #0002: patForms FormNamespaces
======================================================================
Author: Sven
Created: 2005-06-22
Status: draft

# Scope:
----------------------------------------------------------------------

Invent ability to set a form-wide namespace per form to avoid element
naming conflicts when existing forms are joined.

# Rationale
----------------------------------------------------------------------

When we have two forms that are already in use and now shall be joined
to one form, element naming conflicts can occure. For example, we have
two forms that map to two different address classes: HomeAddress and
DeliveryAddress. It's most likely that both classes will use identical
member names and thus that form elements in both forms are named
identically.

Solution: set a namespace attribute on each of the forms.

# Functionality
----------------------------------------------------------------------

We will invent a method to set the patForms namespace. When a form
namespace is set, the resulting elements (serialized) html code will
have a name attribute that uses an array-like syntax. This will result
in arrays in $_GET/$_POST that can be read by the patForms after the
form has been submitted.

For example:

   $form1 = &patForms::createForm(...);
   $form1->setNamespace('home');

   $form2 = &patForms::createForm(...);
   $form2->setNamespace('delivery');

When both patForms will be rendered into one Html form tag, this will
result in:

   <form>
      <input name="home[name]">
      <input name="home[street]">
      <input name="delivery[name]">
      <input name="delivery[street]">
   </form>

And after the form has been submitted, we will have in $_REQUEST:

   array(
      'home' => array('name' => ..., 'street' => ...),
      'delivery' => array('name' => ..., 'street' => ...),
   )

$form1 will then only read data from $_REQUEST['home'] and $form2 will
only read data from $_REQUEST['delivery']. So both forms can use and
process their data independently.

# Dependencies
----------------------------------------------------------------------

This shouldn't break existing code since functionality remains the
same as long as no namespace has been set for a patForms instance.

# Implementation
----------------------------------------------------------------------

[uncomplete]

Basically three things will be necessary:

1. provide a method patForms::setNamespace($namespace) to set an
   attribute and make this attribute visible to the patForms_Elements.

2. when rendering/serializing the patForms_Elements, use the namespace
   attribute value to create the appropriate Html element names.

3. make sure that client-side Javascript variable names etc. get
   rendered in an appropriate way. Variable names like
   namespace[elementname] won't work of course, so we'll probably want
   to use something like namespace_elementname here.

We need to make sure, subpackages also provide support for namespaces.

1. patForms_Parser
   Make sure that the parser is able to treat the namespace attribute
   correctly:
   <patForms:Form namespace="delivery">
      ...   
   </patForms:Form>
   There are two possible solutions:
   - The Parser will call setNamespace after creating the form
   - The namespace property is no real property, but an attribute
     and can be passed to the constructor.
   
# History
----------------------------------------------------------------------

$Log$
Revision 1.2  2005/06/22 15:04:30  schst
added some notes on the patForms_Parser

Revision 1.1  2005/06/22 14:41:40  sfuchs
Startet RFC #0002