フォーム
========
:code:`Phalcon\Forms` is a component that aids you in the creation and maintenance of forms in web applications.
The following example shows its basic usage:
.. code-block:: php
add(
new Text(
"name"
)
);
$form->add(
new Text(
"telephone"
)
);
$form->add(
new Select(
"telephoneType",
[
"H" => "Home",
"C" => "Cell",
]
)
);
Forms can be rendered based on the form definition:
.. code-block:: html+php
Contacts
Each element in the form can be rendered as required by the developer. Internally,
:doc:`Phalcon\\Tag <../api/Phalcon_Tag>` is used to produce the correct HTML for each element and you can pass additional HTML attributes as the second parameter of :code:`render()`:
.. code-block:: html+php
render("name", ["maxlength" => 30, "placeholder" => "Type your name"]); ?>
HTML attributes also can be set in the element's definition:
.. code-block:: php
add(
new Text(
"name",
[
"maxlength" => 30,
"placeholder" => "Type your name",
]
)
);
フォームの初期化
------------------
As seen before, forms can be initialized outside the form class by adding elements to it. You can re-use code or organize your form
classes implementing the form in a separated file:
.. code-block:: php
add(
new Text(
"name"
)
);
$this->add(
new Text(
"telephone"
)
);
$this->add(
new Select(
"telephoneType",
TelephoneTypes::find(),
[
"using" => [
"id",
"name",
]
]
)
);
}
}
:doc:`Phalcon\\Forms\\Form <../api/Phalcon_Forms_Form>` extends :doc:`Phalcon\\Di\\Injectable <../api/Phalcon_Di_Injectable>`
so you have access to the application services if needed:
.. code-block:: php
security->getToken();
}
public function initialize()
{
// Set the same form as entity
$this->setEntity($this);
// Add a text element to capture the 'email'
$this->add(
new Text(
"email"
)
);
// Add a text element to put a hidden CSRF
$this->add(
new Hidden(
"csrf"
)
);
}
}
The associated entity added to the form in the initialization and custom user options are passed to the form constructor:
.. code-block:: php
add(
new Hidden(
"id"
)
);
} else {
$this->add(
new Text(
"id"
)
);
}
$this->add(
new Text(
"name"
)
);
}
}
In the form's instantiation you must use:
.. code-block:: php
true,
]
);
バリデーション
--------------
Phalcon forms are integrated with the :doc:`validation ` component to offer instant validation. Built-in or
custom validators could be set to each element:
.. code-block:: php
addValidator(
new PresenceOf(
[
"message" => "The name is required",
]
)
);
$name->addValidator(
new StringLength(
[
"min" => 10,
"messageMinimum" => "The name is too short",
]
)
);
$form->add($name);
Then you can validate the form according to the input entered by the user:
.. code-block:: php
isValid($_POST)) {
$messages = $form->getMessages();
foreach ($messages as $message) {
echo $message, " ";
}
}
Validators are executed in the same order as they were registered.
By default messages generated by all the elements in the form are joined so they can be traversed using a single foreach,
you can change this behavior to get the messages separated by the field:
.. code-block:: php
getMessages(false) as $attribute => $messages) {
echo "Messages generated by ", $attribute, ":", "\n";
foreach ($messages as $message) {
echo $message, " ";
}
}
Or get specific messages for an element:
.. code-block:: php
getMessagesFor("name");
foreach ($messages as $message) {
echo $message, " ";
}
フィルタリング
--------------
A form is also able to filter data before it is validated. You can set filters in each element:
.. code-block:: php
setFilters(
[
"string",
"trim",
]
);
$form->add($name);
$email = new Text(
"email"
);
// Set one filter
$email->setFilters(
"email"
);
$form->add($email);
.. highlights::
Learn more about filtering in Phalcon by reading the :doc:`Filter documentation `.
Forms + Entities
----------------
An entity such as a model/collection/plain instance or just a plain PHP class can be linked to the form in order to set default values
in the form's elements or assign the values from the form to the entity easily:
.. code-block:: php
add(
new Text(
"name"
)
);
$form->add(
new Text(
"year"
)
);
Once the form is rendered if there is no default values assigned to the elements it will use the ones provided by the entity:
.. code-block:: html+php
render("name"); ?>
You can validate the form and assign the values from the user input in the following way:
.. code-block:: php
bind($_POST, $robot);
// Check if the form is valid
if ($form->isValid()) {
// Save the entity
$robot->save();
}
Setting up a plain class as entity also is possible:
.. code-block:: php
add(
new Select(
"timezone",
[
"America/New_York" => "New York",
"Europe/Amsterdam" => "Amsterdam",
"America/Sao_Paulo" => "Sao Paulo",
"Asia/Tokyo" => "Tokyo",
]
)
);
$form->add(
new Select(
"receiveEmails",
[
"Yes" => "Yes, please!",
"No" => "No, thanks",
]
)
);
Entities can implement getters, which have a higher precedence than public properties. These methods
give you more freedom to produce values:
.. code-block:: php
` namespace:
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| Name | Description |
+==================================================================================+=============================================================+
| :doc:`Phalcon\\Forms\\Element\\Text <../api/Phalcon_Forms_Element_Text>` | Generate INPUT[type=text] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Password <../api/Phalcon_Forms_Element_Password>` | Generate INPUT[type=password] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Select <../api/Phalcon_Forms_Element_Select>` | Generate SELECT tag (combo lists) elements based on choices |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Check <../api/Phalcon_Forms_Element_Check>` | Generate INPUT[type=check] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\TextArea <../api/Phalcon_Forms_Element_TextArea>` | Generate TEXTAREA elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Hidden <../api/Phalcon_Forms_Element_Hidden>` | Generate INPUT[type=hidden] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\File <../api/Phalcon_Forms_Element_File>` | Generate INPUT[type=file] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Date <../api/Phalcon_Forms_Element_Date>` | Generate INPUT[type=date] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Numeric <../api/Phalcon_Forms_Element_Numeric>` | Generate INPUT[type=number] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
| :doc:`Phalcon\\Forms\\Element\\Submit <../api/Phalcon_Forms_Element_Submit>` | Generate INPUT[type=submit] elements |
+----------------------------------------------------------------------------------+-------------------------------------------------------------+
イベント・コールバック
----------------------
Whenever forms are implemented as classes, the callbacks: :code:`beforeValidation()` and :code:`afterValidation()` can be implemented
in the form's class to perform pre-validations and post-validations:
.. code-block:: html+php
getMessagesFor(
$element->getName()
);
if (count($messages)) {
// Print each element
echo '
";
}
?>
Or reuse the logic in your form class:
.. code-block:: php
get($name);
// Get any generated messages for the current element
$messages = $this->getMessagesFor(
$element->getName()
);
if (count($messages)) {
// Print each element
echo '
";
}
}
In the view:
.. code-block:: php
renderDecorated("name");
echo $element->renderDecorated("telephone");
フォーム要素の作成
----------------------
In addition to the form elements provided by Phalcon you can create your own custom elements:
.. code-block:: php
forms->set(
"login",
new LoginForm()
);
Using the unique name, forms can be accessed in any part of the application:
.. code-block:: php
forms->get("login");
echo $loginForm->render();
外部資料
------------------
* `Vökuró `_, is a sample application that uses the forms builder to create and manage forms, [`Github `_]