[PHPLIB-DEV] On the way to new OOH Forms From: Ulf Wendel (UW <email protected>)
Date: 04/07/00

Hi,

I'm about to place a new version of ooh forms in the cvs. No it's
not there yet - the weather has developed beautiful and it's
weekend. But the weather report says it's raining tomorrow...

I made a complete rewrite:

+ new features
+ new api
+ new internal structure
- (JavaScript stuff is incomplete)

++++ Features ++++

+ generation of html tags as known before
+ pre-validators as known before

+ new type combo
+ new type tree (no JavaScript application)
+ possibility to write custom validators that turn on/off the
default validators

- new JavaScript code

++ New type combo ++

Many of you will known combo boxes, nearly everybody has used one
before. A combo box is a special kind of a select box. The user
can add new values to this select box. HTML doesn't know this
type. But you can combine a select with a text input tag to get
something quite simmilar. The new type is called "combo".

The bad thing is - you need a session var to save the options
(see #internal structure for details), it's up to you to add new
entries. But of course validation is done for you...

++ New Type tree ++

Tree is again a special kind of an select box. You probably know
treelists from Windows. They're used to display directory
structures.
Tree does not render grey lines like Windows does (if you're in
feel free to add code...), but it intends the entries and it
gives you [+]/[-] signs in front of the labels. So the user can
easily distinguish between knodes and leaves.

Trees are defined in the way, that was introduced in menu.inc:

1/ => Menu 1
2 => Menu 2
1/1/ => Menu 1.1
(Yes, you don't have to care on the definition order.)

++ Custom validators ++

The main reason to rewirte the ooh forms was to have custom
validators.

Yes you can validate a form automatically by ooh forms and yes,
you could simply override some results but that's no good
programming style. And it gives you lots of pain when it comes to
complex forms (ooh to template/tab style). Think of a form that
collects payment informations.

The user selects the radio credit cards and types his data. Old
OOH Forms starts validation and complains on missing information
on his/her bank account... The new OOH Forms will call allow you
to bind custom validation functions on certain elements. These
functions are called before the default validators are (partly)
called. You custom validator can turns on/off the validation of
each element and set an error. In the payment example you'd turn
off the default validators for all elements that belong to the
bank account. Validation can be turned on/off not only by element
but by event (all, length, valid, intro).

Let's ave a look at the source to see how easy it is:

class MyForm (
  [...]
  function MyValidator() {

    $payment = getvalue("payment");
    switch ($payment) {
      case "credit card":
        $ellist = array (
                          "bank1" => "all",
                          "bank2" => "all",
                          "bank3" => "all"
                        );
        $this->ValidationOff($ellist);
        break;
      case "bank":
        [...]
        break;
    }
    #$this->setValidationError($name, $ok, $message);
  } // end func my_validator

) // end class my_form

++ new JavaScript code ++

The new JavaScript Code knows two validation modes: onChange and
onSubmit. If JavaScript validation is turned on you choose
between "onChange" and "onSubmit" validation. "onChange" implies
"onSubmit" validation.

For some elements there's JavaScript code for others not. I
didn't have enough time to work on it yet. Is there someone who's
really though in JavaScript that can help me? In detail it's
somewhat tricky, for example when it comes to custom validators
(not implemented yet), because as far as I know arrays are rather
simple structured in JavaScript.

++++ New API ++++

Sorry Negro, due to the new internal structure the API has
changed - but not completely. Wait for the source and the
documentation to get more informations. Here're some extracts:

- add_element is now called addElement()

- select, combo and tree allow you to define an intro message
(top of all options).
This intro, e.g. "please select..." is not provided in valid_e,
it's stored in intro and intro_e.

- new setSize()
Sets the default size of text and textarea elements

- new setMaxlength()
Sets the default maxlength of text and textarea elements

- new attributes accesskey, readonly, tabindex
- renamed attribute extra_html to additional_html

- new function setValues()
- new function getOptions()
- new function addOption()
- new function getNewComboOption()

- different handling of radio elements:
New attribute elname (in contrast to name, used for JavaScript
and HTML)

[...]

++++ New internal structure ++++

++ Developer ++

The new OOH Forms are still OO. You'll still find one central
class surrounded by several element classes. As knownm form
generates objects and stores them in an array. In contrast to the
old ooh forms this element does not contain anything but the
generated object. Encapsulation is stronger. As before, you can
add new element classes. An element class extends the base class
of_element and overrides this methods:

get()
getfrozen()
validate()
generateJS()
(special elements provide some more functions)

Use the function form->introspection() to get an idea of the
internal structures.

Note that I have used some coding standards, please follow them:

1.) Userfunctions do not contain underscores (_).
phpfunctions do use underscores. userfunction use lower und upper
case characters to make their name readable.

Examples:
 getfrozen() instead of get_frozen()
 addElement() instead of add_element()
 generateJS() instead of generate_js()

2.) Uservariables contain underscores

3.) Inline Documentation is a must
I've used kind of javadoc to document all functions/methods and
variables/class vars. No, I don't want to use xml tags instead.
XML is not part of a php3/4 distribution, and no I'm sorry I
don't (yet) have a tool to extract the documentation.

++ User ++

A creates a new class that extends form. The class my_form must
provide a constructor, that calls the form constructor and a
method Init(), that holds all addElement() calls. Custom
validation functions (methods) are stored in my_form.
This way you'll get rid of includes with heaps of the old
add_element() calls, but you do have to load the form with
submitted data if you do not want your form to forget the
input...

What does it look like?

class MyForm extends NewForm {
  function MyForm($js_mode="weak", $showerror="",
$haltonerror="") {
    $this->NewForm($js_mode, $showerror, $haltonerror);
  }

  function Init() {
    $this->addElement (
                      );
    [...]
  }

  function MyValidator() {
    [...]
  }
}

Have a nice weekend!

Ulf 

-- 
Ulf Wendel
NetUSE Kommunikationstechnologie GmbH
Siemenswall, D-24107 Kiel, Germany
Fon: +49 431 386435 00  --  Fax: +49 431 386435 99
-
PHPLIB Developers Mailing List. Send messages to <phplib-dev <email protected>>.
To unsubscribe, send "unsubscribe" to <phplib-dev-request <email protected>> in
the body, not the subject, of your message.