HTML_QuickForm

Das PEAR::HTML_QuickForm-Package bietet Methoden zur Erzeugung, Überprüfung und Verarbeitung von HTML-Formular.

Einführung

Inhaltsverzeichnis
QuickStart -- Tutorial für HTML_QuickForm
QuickHelp -- Answers to most Frequently Asked Questions
QuickForm element types -- What elements can be added to QuickForm
Migration to version 3.2 -- API changes to observe
Subpackages -- An overview about subpackages and packages that use QuickForm

QuickForm ist eine umfangreiche Bibliothek zum Umgang mit HTML-Formularen. Es bietet die Validierung von Eingaben auf Client-Seite (über JavaScript) und Server-Seite und ist auf viele Arten anpass- und erweiterbar. QuickForm umfasst viele Dateien. Die Hauptdatei ist QuickForm.php und sollte sich im Verzeichnis pear/HTML befinden. Weitere wichtige Dateien sind element.php, die alle relevanten Methoden für Formularelemente enthält, und group.php, welche Methoden enthält, die sich auf Gruppen von Elementen beziehen. Beide befinden sich im Verzeichnis HTML/QuickForm mit den anderen Formularobjekten. Die Datei input.php enthält eine allgemeine Klasse für alle Eingabeelemente (Text, Password ...). QuickForm besitzt Objekte alle üblichen Formularelemente: Select, Text, Password, Checkbox, File, Submit, Reset, Button, Image, Radio, Hidden, Textarea. QuickForm ermöglicht die Erzeugung eigener Elemente, solange sie übereinstimmen mit dem allgemeinen Befehlssatz.

Grundlegende Formularerzeugung

Inhaltsverzeichnis
constructor HTML_QuickForm::HTML_QuickForm() -- Class constructor
HTML_QuickForm::addElement() -- Adds an element into the form
HTML_QuickForm::apiVersion() -- Returns the current API version
HTML_QuickForm::createElement() -- Creates a new form element of the given type
HTML_QuickForm::elementExists() -- Checks if element is in the form
HTML_QuickForm::errorMessage() -- Returns an error message for error code
HTML_QuickForm::getElementType() -- Returns the type of an element
HTML_QuickForm::getElement() -- Returns a reference to the element
HTML_QuickForm::getMaxFileSize() -- Returns the value of MAX_FILE_SIZE hidden element
HTML_QuickForm::getRegisteredTypes() -- Returns registered element types
HTML_QuickForm::insertElementBefore() -- Inserts a new element right before the other element
HTML_QuickForm::isError() -- Tells whether a result is an error
HTML_QuickForm::isTypeRegistered() -- Checks whether the form element type is supported
HTML_QuickForm::registerElementType() -- Registers a new element type
HTML_QuickForm::removeElement() -- Removes an element
HTML_QuickForm::setMaxFileSize() -- Sets the value of MAX_FILE_SIZE hidden element
HTML_QuickForm::updateElementAttr() -- Updates Attributes for one or more elements

Klassen für die Fomularelemente

Basisklassen

Inhaltsverzeichnis
Class Summary HTML_QuickForm_element -- Base class for form elements
constructor HTML_QuickForm_element() -- Class constructor
HTML_QuickForm_element::accept() -- Accepts a renderer
HTML_QuickForm_element::apiVersion() -- Returns the current API version
HTML_QuickForm_element::exportValue() -- Returns a 'safe' element's value (bezogen auf Package-Entwickler)
HTML_QuickForm_element::freeze() -- Freezes the element
HTML_QuickForm_element::getFrozenHtml() -- Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() -- Returns the label for the element
HTML_QuickForm_element::getName() -- Returns the element name
HTML_QuickForm_element::getType() -- Returns the element type
HTML_QuickForm_element::getValue() -- Returns the value of the form element
HTML_QuickForm_element::isFrozen() -- Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() -- Called by HTML_QuickForm whenever form event is made on this element (bezogen auf Package-Entwickler)
HTML_QuickForm_element::setLabel() -- Sets a label for the element
HTML_QuickForm_element::setName() -- Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() -- Sets whether element value should persist on freeze()
HTML_QuickForm_element::setValue() -- Sets the value of the form element
HTML_QuickForm_element::unfreeze() -- Unfreezes the element
Class Summary HTML_QuickForm_input -- Base class for input form elements
constructor HTML_QuickForm_input() -- Class constructor
HTML_QuickForm_input::setType() -- Sets the element type

Standard-HTML-Elemente

Inhaltsverzeichnis
Class Summary HTML_QuickForm_button -- HTML class for a button type element
constructor HTML_QuickForm_button() -- Class constructor
Class Summary HTML_QuickForm_checkbox -- HTML class for a checkbox type field
constructor HTML_QuickForm_checkbox() -- Class constructor
HTML_QuickForm_checkbox::getChecked() -- Returns whether a checkbox is checked
HTML_QuickForm_checkbox::getText() -- Returns the checkbox text
HTML_QuickForm_checkbox::setChecked() -- Sets whether a checkbox is checked
HTML_QuickForm_checkbox::setText() -- Sets the checkbox text
Class Summary HTML_QuickForm_file -- HTML class for a file type element
constructor HTML_QuickForm_file() -- Class constructor
HTML_QuickForm_file::getSize() -- Returns size of file element
HTML_QuickForm_file::getValue() -- Returns information about the uploaded file
HTML_QuickForm_file::isUploadedFile() -- Checks if the element contains an uploaded file
HTML_QuickForm_file::moveUploadedFile() -- Moves an uploaded file into the destination
HTML_QuickForm_file::setSize() -- Sets size of file element
Class Summary HTML_QuickForm_hidden -- HTML class for a hidden type element
constructor HTML_QuickForm_hidden() -- Class constructor
Class Summary HTML_QuickForm_image -- HTML class for a image type element
constructor HTML_QuickForm_image() -- Class constructor
HTML_QuickForm_image::setAlign() -- Sets alignment for image element
HTML_QuickForm_image::setBorder() -- Sets border size for image element
HTML_QuickForm_image::setSource() -- Sets source for image element
Class Summary HTML_QuickForm_password -- HTML class for a password type field
constructor HTML_QuickForm_password() -- Class constructor
HTML_QuickForm_password::setMaxlength() -- Sets maxlength of password element
HTML_QuickForm_password::setSize() -- Sets size of password element
Class Summary HTML_QuickForm_radio -- HTML class for a radio type element
constructor HTML_QuickForm_radio() -- Class constructor
HTML_QuickForm_radio::getChecked() -- Returns whether radio button is checked
HTML_QuickForm_radio::getText() -- Returns the radio text
HTML_QuickForm_radio::setChecked() -- Sets whether radio button is checked
HTML_QuickForm_radio::setText() -- Sets the radio text
Class Summary HTML_QuickForm_reset -- HTML class for a reset type element
constructor HTML_QuickForm_reset() -- Class constructor
Class Summary HTML_QuickForm_select -- Class to dynamically create an HTML SELECT
constructor HTML_QuickForm_select() -- Class constructor
HTML_QuickForm_select::addOption() -- Adds a new OPTION to the SELECT
HTML_QuickForm_select::getMultiple() -- Returns the select mutiple attribute
HTML_QuickForm_select::getPrivateName() -- Returns the element name (possibly with brackets appended)
HTML_QuickForm_select::getSelected() -- Returns an array of the selected values
HTML_QuickForm_select::getSize() -- Returns the select field size
HTML_QuickForm_select::load() -- Loads options from different types of data sources
HTML_QuickForm_select::loadArray() -- Loads the options from an associative array
HTML_QuickForm_select::loadDbResult() -- Loads the options from DB_result object
HTML_QuickForm_select::loadQuery() -- Queries a database and loads the options from the results
HTML_QuickForm_select::setMultiple() -- Sets the select mutiple attribute
HTML_QuickForm_select::setSelected() -- Sets the default values of the select box
HTML_QuickForm_select::setSize() -- Sets the select field size, only applies to 'multiple' selects
Class Summary HTML_QuickForm_submit -- HTML class for a submit type element
constructor HTML_QuickForm_submit() -- Class constructor
Class Summary HTML_QuickForm_text -- HTML class for a text field
constructor HTML_QuickForm_text -- Class constructor
HTML_QuickForm_text::setMaxlength() -- Sets maxlength of text field
HTML_QuickForm_text::setSize() -- Sets size of text field
Class Summary HTML_QuickForm_textarea -- HTML class for a textarea type field
constructor HTML_QuickForm_textarea() -- Class constructor
HTML_QuickForm_textarea::setCols() -- Sets width in cols for textarea element
HTML_QuickForm_textarea::setRows() -- Sets height in rows for textarea element
HTML_QuickForm_textarea::setWrap() -- Sets wrap type for textarea element
Class Summary HTML_QuickForm_xbutton -- Class for HTML 4.0 <button> element
constructor HTML_QuickForm_xbutton() -- Class constructor
HTML_QuickForm_xbutton::setContent() -- Sets the contents of the element

Custom-Elemente

Inhaltsverzeichnis
Class Summary HTML_QuickForm_advcheckbox -- HTML class for an advanced checkbox type field
constructor HTML_QuickForm_advcheckbox() -- Class constructor
HTML_QuickForm_advcheckbox::getOnclickJs() -- Create the javascript for the onclick event
HTML_QuickForm_advcheckbox::getPrivateName() -- Gets the private name for the element
HTML_QuickForm_advcheckbox::setValues() -- Sets the values used by the hidden element
Class Summary HTML_QuickForm_autocomplete -- HTML class for a text field with autocompletion feature
constructor HTML_QuickForm_autocomplete -- Class constructor
HTML_QuickForm_autocomplete::setoptions() -- Sets the options for the autocomplete input text element
Class Summary HTML_QuickForm_date -- Class for a group of elements used to input dates (and times).
constructor HTML_QuickForm_date() -- Class constructor
Class Summary HTML_QuickForm_header -- A pseudo-element used for adding headers to form
constructor HTML_QuickForm_header() -- Class constructor
Class Summary HTML_QuickForm_hiddenselect -- Creates hidden elements with select's values
constructor HTML_QuickForm_hiddenselect() -- Class constructor
Class Summary HTML_QuickForm_hierselect -- Class to dynamically create chained HTML Select elements, each select changes the content of the next.
constructor HTML_QuickForm_hierselect() -- Class constructor
HTML_QuickForm_hierselect::setOptions() -- Sets the options for the select elements
HTML_QuickForm_hierselect::setMainOptions() -- DEPRECATED: Sets the options for the first select
HTML_QuickForm_hierselect::setSecOptions() -- DEPRECATED: Sets the options for the secondary select
Class Summary HTML_QuickForm_html -- A pseudo-element used for adding raw HTML to form (deprecated)
constructor HTML_QuickForm_html() -- Class constructor
Class Summary HTML_QuickForm_link -- HTML class for a link type field
constructor HTML_QuickForm_link() -- Class constructor
HTML_QuickForm_link::setHref() -- Sets the links href
Class Summary HTML_QuickForm_static -- HTML class for static data
constructor HTML_QuickForm_static() -- Class constructor
HTML_QuickForm_static::setText() -- Sets the text

Gruppierung

Inhaltsverzeichnis
HTML_QuickForm::addGroup() -- Adds an element group
Class Summary HTML_QuickForm_group -- HTML class for a form element group
constructor HTML_QuickForm_group() -- Class constructor
HTML_QuickForm_group::getElementName() -- Returns the name of an element inside the group
HTML_QuickForm_group::getElements() -- Gets the grouped elements
HTML_QuickForm_group::getGroupType() -- Gets the group type based on its elements.
HTML_QuickForm_group::setElements() -- Sets the grouped elements

Mit Elementwerten umgehen

Dieser Abschnitt beschreibt die Methoden zum Umgang mit den Werten von Elementen und der erhaltenen Werte.

Erhalten, setzen und verabeiten von Werten

Inhaltsverzeichnis
HTML_QuickForm::setConstants() -- Sets constant form values
HTML_QuickForm::setDefaults() -- Sets default form values
HTML_QuickForm::exportValue() -- Returns the element's "safe" value
HTML_QuickForm::exportValues() -- Returns "safe" elements' values
HTML_QuickForm::getElementValue() -- Returns the element's raw value
HTML_QuickForm::getSubmitValue() -- Returns the submitted element's value
HTML_QuickForm::getSubmitValues() -- Returns the values submitted by the form
HTML_QuickForm::process() -- Performs the form data processing

Validierung und Filter

Inhaltsverzeichnis
Introduction - validation and filters -- How to process submitted data
HTML_QuickForm::addRule() -- Adds a validation rule for the given field
HTML_QuickForm::addGroupRule() -- Adds a validation rule for the given group
HTML_QuickForm::addFormRule() -- Adds a global validation rule
HTML_QuickForm::isElementRequired() -- Returns whether the form element is required
HTML_QuickForm::validate() -- Performs the server side validation
HTML_QuickForm::getElementError() -- Returns error corresponding to validated element
HTML_QuickForm::setElementError() -- Set error message for a form element
HTML_QuickForm::registerRule() -- Registers a new validation rule
HTML_QuickForm::getRegisteredRules() -- Returns registered validation rules
HTML_QuickForm::isRuleRegistered() -- Returns whether the rule is supported
HTML_QuickForm::applyFilter() -- Applies a filter for the given field(s)

QuickForm unterstützt Regeln zur Überprüfung von Werten. Sie können eigene Validierungsregeln anlegen, sie in QuickForm registrieren und in Ihren Skripten aufrufen. Standardmäßig beherrscht QuickForm die Überprüfung über reguläre Ausdrücke (preg_match-Stil) und die Prüfung auf erforderliche Elemente. Wenn eine client-seitige Validierung notwendig ist, dann wird der entsprechende JavaScript-Code ebenfalls generiert. Die server-seitige Validierung ist automatisch aktiv.

QuickForm kann auch Filter für den Datenübertragung zum Formular benutzen oder zur Verarbeitung übertragener Formulardaten. Filter funktionieren genauso wie Regeln, müssen aber nicht in QuickForm registriert werden. Sie können Ihre eigenen Filter-Funktionen schreiben und sie in einem Skript aufrufen. Jede PHP-Funktion, wie z.B. trim, addslashes, htmlentities, etc., kann benutzt und nacheinander auf die Werte der Elemente angewendet werden.

Ausgabe des Formulars

Sie können das Formular auf vielfältige Arten anpassen. QuickForm kann verschiedene Arten von Renderen benutzen, der standardmäßige, der die Anpassung des Formulars, seiner Elemente, der Fehlermeldungen, der Überschriften und der Hinweistexte und Markierungen für erforderlichen Elemente. Sie können auch ihren eigenen Render einsetzen.

Formular-Anpassungen und Ausgabehilfen

Inhaltsverzeichnis
HTML_QuickForm::freeze() -- "Freezes" the form's elements
HTML_QuickForm::isElementFrozen() -- Checks whether the element is frozen
HTML_QuickForm::isFrozen() -- Checks whether the form is frozen
HTML_QuickForm::setRequiredNote() -- Sets required note
HTML_QuickForm::setJsWarnings() -- Sets JavaScript warning messages
HTML_QuickForm::getRequiredNote() -- Returns the required note
HTML_QuickForm::getValidationScript() -- Returns the client side validation script
HTML_QuickForm::accept() -- Accepts a renderer
HTML_QuickForm::defaultRenderer() -- Returns a reference to default renderer object
HTML_QuickForm::toArray() -- Returns the form's contents in an array
HTML_QuickForm::toHtml() -- Returns an HTML version of the form
HTML_QuickForm::display() -- Outputs an HTML version of the form

Basis-Renderer

Diese Renderer basieren auf dem Code für HTML_QuickForm-Version kleiner 3 und benötigen keine zusätzlichen Klassen zum funktionieren.

Template-basierte Renderer

Inhaltsverzeichnis
HTML_QuickForm_Renderer_ArraySmarty -- A renderer for 'static' Smarty templates
constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() -- Constructor
HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() -- Sets the way elements with validation errors are rendered
HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() -- Sets the way required elements are rendered
HTML_QuickForm_Renderer_ITDynamic -- Dynamic renderer for Integrated Templates
constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() -- Constructor
HTML_QuickForm_Renderer_ITDynamic::setElementBlock() -- Sets the block to use for element rendering
HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() -- Sets the name of a block to use for header rendering
HTML_QuickForm_Renderer_ITStatic -- Static renderer for Integrated Templates
constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() -- Constructor
HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() -- Sets the way elements with validation errors are rendered
HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() -- Sets the way required elements are rendered
HTML_QuickForm_Renderer_QuickHtml -- Render form elements into HTML in an easy and flexible manner
constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() -- Constructor
HTML_QuickForm_Renderer_QuickHtml::toHtml() -- Returns the HTML
HTML_QuickForm_Renderer_QuickHtml::elementToHtml() -- Renders a specific form element into HTML

Diese Renderer benutzen Templates, um das HTML für das Formular zu erzeugen.

Renderer-Infrastruktur

Inhaltsverzeichnis
HTML_QuickForm_Renderer -- Abstract base class for renderers (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::startForm() -- Start visiting a form (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::finishForm() -- Finish visiting a form (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::startGroup() -- Start visiting a group (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::finishGroup() -- Finish visiting a group (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::renderElement() -- Visit an element (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::renderHeader() -- Visit a header (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::renderHidden() -- Visit a hidden element (bezogen auf Package-Entwickler)
HTML_QuickForm_Renderer::renderHtml() -- Visit a raw HTML/text element (bezogen auf Package-Entwickler)

Wenn Sie die existierenden Renderer modifizieren wollen oder einen neuen schreiben wollen, dann ist dieser Abschnitt für Sie relevant.