Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Forms Library for FE Extensions

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Extension coordination team (category ECT)

notice - This information is outdated


Introduction

This document describes a new proposal for a generic FE form system for Typo3; see the requirements below.

What it is

The forms library should provide a way for extension developers and possibly the core/BE to render and validate forms based on a given configuration, be that TCA, TS, or PHP. It alsos needs to take into account future development of forms in general and anticipate those trends to stay up to date.
Since Rails seems to be doing a lot of things in this area right, we will definitely take a look at their implementation as well as already existing form libraries inside Typo3 and possibly other places.

What it is not

It is not a survey library. While more complex things like multiple pages should and will be kept in mind during the design phase, the goal is to keep it very simple and low level.

Definite Goals

  • Ease of use
  • Flexibility
  • Accessibilty
  • Different ways of configuration (TCA, TS, PHP)
  • Client/Server side validation (or just server with AJAX)

Possible Goals

These still need to be discussed in some way.

  • Is data storage part of this library, and how will it work?
  • Being functional as standalone library or part of the MVC framework
  • xForms

Requirements

General

Based on the meeting of the forms team, here are the requirements we decided on so far. Discussion can continue on the Talk Page.

  1. Ease of use. This is one of, if not the, most important thing.
  2. Hints (question mark with popup on the right)
  3. Labels (possibly containing HTML markup; many pages or forms start with a short introduction)
  4. Validation, client and server side, or just server side using AJAX for instant feedback
  5. Visibility dependencies
  6. Additional records on a form
  7. Required fields
  8. All used forms plus tabs as in Flexforms, maybe multiple pages

Overall the forms library should be easy to use yet still be flexible. This requires a pretty low level implementation while higher level things like multiple pages are still kept in mind during the design phase.

Ease of use

The goal for the library is to be easy. Very easy. Developers shouldn't have to learn another thing. So we need to pay attention to how easy it is to use. One of the ways to achieve that could be a visual form designer or something of the sort that allows developers to design forms visually, add labels, validation, and other things. It remains to be discussed whether this is too complicated or worth it.

Visibility Dependencies

Some forms are dependent on a certain setting of a control, so the 'married' setting on a marital status dropdown box should make additional forms for the spouse's info visible.

Additional Records

Sometimes it's necessary for a form to allow several entries, e.g. 'Children' should have a (+) button maybe to enter additional children into the same form.
Instead of just showing an additional input form, it might be nicer to be able to define field sets that could dynamically show.

Example:

children? yes [next fieldset appears]
   child's firstname, lastname, dob
   + add a child [on click, next fieldset appears]
   child's firstname, lastname, dob

General Ideas

Validation

Validation should take place either client side AND sever side, but since client side validation requires JS, we might as well use AJAX to validate it all in the background through the server.
Here is a list of things we need to validate for:

  • Length
  • Number Range
  • Dates
  • Email
  • URLs
  • ...

While validation needs to come with the library, there should be an option to override the validation functions, either by subclassing the validation class or otherwise.

We should take full advantage of AJAX capabilities, which could mean form validation even while tpying, etc.

Forms

We will of course use the most popular forms and mabye add support for flexforms and even multiple pages, but that remains to be seen.

  • Input
  • Password
  • Multiselect
  • Dropdown
  • Checkbox
  • ...

Configuration

TypoScript

Forms should definitely be configurable through TS. Maybe revamping the FORMS content object would be an option, or just using normal TS.

TCA

A lot of this still needs to be discussed, but TCA should at least be an option to generate the forms. Whether it's all or none, or override through TS, still needs to be discussed.


Interface / API

This is just a proposal for an API. Please discuss on the Talk Page what this should look like.

It is important that we set an API as soon as possible so that other extensions or the core can think about how to use our library before it's complete.
PHP script:
  var $myform = new form();
  $myform->addTCA('tx_someextension_items');
        $elementArray['type'] = 'textinput';
        $elementArray['name'] = 'username';
        $elementArray['value'] = 'enter your username'; // default value
  $myform->addElement($elementArray);
        $elementArray['type'] = 'textarea';
        $elementArray['name'] = 'comments';
        $elementArray['value'] = 'type your comments here'; // default value
 $myform->addElement($elementArray);

  // default template would be some default rendering by the extension
  $myform->setTemplate('fileadmin/templates/someform.html');

Data Storage

Data storage, if even part of this library, definitely needs to be a separate class. Possible options for storage media should be:

  • Database - DBAL
  • XML
  • CSV
  • Email

It should be possible to use more than one at the same time, so a submitted form could be sent as an email and saved to the database at the same time.

It must be possible to transform entered data before sending the data to any storage engine/class. So eg a male/female drop down box with values 0/1 sends the data as m/f to the DB but as male/female per email.

Rails

The rails way of doing it is to define the form fields, tie them to an array, and render in the frontend. One suggestion is using a data array and tying that to typoscript.
Also, within a cObject you can use a .data field to map the cObject to a field in an array. Then, when form values are submitted, return an identical array that has been validated and filled with data.

Implementation Ideas

General

In general, everything will be Object based. Developers can create objects of form fields, fielsets, legends, etc, and then pack them all together. This will be similar to Java's Swing API, where you can create a button, configure it, and then add it to a panel, which you can then add to a window frame.

How do action parameters look like ?

Actions are normally submitted by submit buttons. Often there is more then one submit button in the form. For different languages they have different values. This doesn't work:

 // english:
 <button type="submit" name="tx_myExt[action]" value="save">
 // german:
 <button type="submit" name="tx_myExt[action]" value="speichern">
That results in different values for the action.
PHP script:
  // english:
  $this->piVars['action'] = "save";
  // german:
  $this->piVars['action'] = "speichern";

One possible solution.

 // english: 
 <button type="submit" name="tx_myExt[action][update]" value="save">
 <button type="submit" name="tx_myExt[action][delete]" value="delte">
 // german: 
 <button type="submit" name="tx_myExt[action][update]" value="speichern">
 <button type="submit" name="tx_myExt[action][delete]" value="löschen">
PHP script:
  if( isset($this->piVars['action']['update'])) {
    ... update the dataset ...
  } elseif( isset($this->piVars['action']['delete'])) {
    ... delete the dataset ...
 }

Templating

The forms need to have support for templates. There should be 2 ways of templating. One individual where every marker for LABEL and FORMFIELD can be set manually in the template and a generic one that creates a form in a loop based only on the TCA / TS information. For the generic way then of course you have a subpart in the template that is filled with the data being looped.

Individual markers example

Fields could be defined in TS like so:
TS TypoScript:
 tx_cwtcommunity_pi1 {
   sections {
     contactInfo {
       label = Contact Info     
       fields {
         username.label = Username
         name.label = Name
         email.label = Email
       }
     }
     miscInfo {
       label = Miscelaneous Information
       fields.birthday.label = Birthday
     }
   }
 }

And then replaced in the template like this:

###TX_CWT_COMMUNITY_PI1-CONTACTINFO###
###TX_CWT_COMMUNITY_PI1-CONTACTINFO-USERNAME###
.
.
.

Generic markers example

Here a PHP function would traverse the TCA, merge it with possible TS overrides, takin care of defined excludeFields and then output a label tag (with ID and label of cause) and the formfield itself. The advantage e: You don't have to setup and edit long marker lists in case you have many table columns you want to display / edit that don't neccessarily need individual styling.

template example:

###ALLITEMS###
   ###FORMFIELD###
      ###FORMFIELD_LABEL### ###FORMFIELD_TAG###
   ###FORMFIELD###
###ALLITEMS###

Other

Back-end editor

As the information for each form is hierarchical in nature, it is rather straightforward to make an editor in the back-end that is alike the current MailForm editor. Storage could either be in a database or in a hierarchical definition language such as XML or TypoScript. A consideration would be to allow a mix of the beforementioned:

Store Forms, Pages, Sections, Fields and FieldTypes in a database. Store Predicate information in an attribute of the beforementioned database relations, possibly in XML or TypoScript. Store render specific information in an attribute of the beforementioned database relations. Allow overriding here.


Evaluation of existing fe editing libraries

Here, we should put descriptions of the existing front end libraries, underlining their advantages or disadvantages.

mth_feedit

mth_feedit It's based on the old fe_adminLib, building the form templates for this library based on TCA and TS configurations.

Current extensions using this lib:

sg_zfelib

sg_zfelib The library written bei Stefan Geith actually seems to me as the most complete one. Has got thousands of TS parameters to configure it precisely. Unfortunately this also is a problem for less experienced users - even for early state ext developers. At least I haven't got it to work yet. Which is a pity as everything in the documentations looks very promising. Maybe someone could give some hints how to set it up properly? So that we can have a closer look at it. ... Ok, I found a stupid mistake of mine of cause! :) Will have a closer look now and give a report on this later on... --JochenRieger 10:49, 26 January 2006 (CET)

It basically uses a PCA array which is derived from the TCA and completed by additional TS. It's using html templates and supports multiple table extensions via configurable JOIN queries.

Current extensions using this lib:

cwt_community forms library

Also a working example, but not a separate extension yet. Example on the dev site for cwt_community. It uses the approach detailed below for individual markers and can be used to built on or combine with other already existing extensions.

Current extensions using this lib:

th_mailformplus

th_mailformplus In its early concept phase. Contains a nice OO approach to creating forms

ameos_formidable

ameos_formidable Seems quite mature, configuration based on XML. Has OO approach. Comes close to what is described below in the requirements. Documentation in the wiki: Formidable documentation Homepage of the projet: http://formidable.typo3.ug

frontendformslib

frontendformslib Looks nice but is in a very early state. Currently only rendering INPUT TEXT fields as far as I could find out.

sr_feedit

sr_feedit TCA-driven front end rendering of table entry editing forms by Stanislas Rolland based on Sebastian Faulhaber's CWT Frontend Edit extension. Seems to be quite complete but has already come into age as it is not making use of the actual TYPO3_DB methods for queries.

Current extensions using this lib:

TYPO3 class.tslib_fetce.php

Form-data processing class: class.tslib_fetce.php by Kasper Skaarhoj. This class seems to be only used by tt_guest and tt_board and has been marked as deprecated. So something similar is needed to be used from tt_guest and tt_board.

Current extensions using this lib:

How complex can it get?

All this might seem to be overkill, but most of the implementation is actually quite straightforward. I do believe (although I have not tested this for really complex forms), that it is possible to create a user-interface to create such forms (which is still understandable by a novice user). There is experience with creating such systems based on Cocoon in combination with JavaFlow.

MVC framework and Forms project relationship

This question is of interest because the existing MVC Framework extensions contain form functions themselvs. On the other hand the draft of the forms project contains actions and BE panel. So it also conatains MVC functionality.

How can we prevent to do it all in double and make it work together? Let me make a proposal:

 --------------------------------------------------------------------------------
                        The MVC Framework
 --------------------------------------------------------------------------------
          MVC                       // abstract set of 3 classes
       /      \                     //         extends to
BE MVC          FE MVC              // successors of t3lib_SCbase and pi_base
   |               |                //         extend to
 --------------------------------------------------------------------------------
   |               |     The Generic FE Form System (as MVC implementation)
 --------------------------------------------------------------------------------
Module          Plugin              //  BE panel and FE plugin
   V ?             V                //         use
 --------------------------------------------------------------------------------
   V ?             V     The $TCA Configured Forms Library
 --------------------------------------------------------------------------------
 $TCA evaluation layer              // configuration of inputs
           V                        //         based on
 --------------------------------------------------------------------------------
           V             The General (x)Forms Library
 --------------------------------------------------------------------------------
 input elements library             // a simple library of inputs, js and checks


The point is, that the "Generic FE Form System" is only one possible implementation of it all. The FE and BE extensions you build with it, would in the same way extend the "MVC Framework". They could use the "$TCA Configured Forms Library" or only the "General Forms Library" or none of them.

"successors" of t3lib_SCbase and pi_base means that we don't remove them. But we we offer one alternative based on a MVC model.

For BE modules the question is, if they also should be able to use the forms library. They have the $TCE available.

Relations