Download the PHP package flsouto/htwidget without Composer
On this page you can find all versions of the php package flsouto/htwidget. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package htwidget
HtWidget
Overview
This class can be used to define different types of widgets. But what is a widget? A widget is an interactive field/element which has some sort of state and allows users to communicate with a server or a backend. Notice that not all form fields are interactive. A hidden field, for instance, even though it has a state, it does not provide any form of direct interaction. A button is also not a widget, in my opinion, because it doesn't allow any complex interaction other than just clicking on it. An input text field or a checkbox, on the other hand, can be considered to be a widget because they do have a state and require some kind of interaction. In this documentation we are going to see how to implement a simple TextField class which inherits from HtWidget.
Notice: A lot of functionality is inherited from a more basic abstract class called HtField. If you find difficulties in understanding some of the features being reused here, please refer to this documentation.
Installation
Run composer:
Usage
Below we are going to implement a simple TextField
class. Pay attention to it because we are going to use it through out this document in order to learn about all the functionality inherited from HtWidget
:
In the next example we instantiate the newly defined class and render it.
Notice that by default the widget is rendered in "writable mode":
Switch to readonly mode
To render the readonly version of your widget, simply call the readonly
setter with a positive argument:
Output:
Understanding how it works
All those extra tags surrounding the main element are produced by default. When we echo $field
the HtWidget::render()
method gets called which produces a wrapper containing the output of HtWidget::renderInner()
, which in turn decides which mode we are in and calls the respective renderReadonly
or renderWritable
method, along with error messages. So, if you wanted to display only the inner content, without the wrapper, you would have to call the renderInner()
method:
Show the widget inline
By default the widget is rendered in block mode, which means it occupies the entire line. If you want it to appear in the same line as whatever was printed before, use the inline
setter:
Output:
Labels
By default the widget is rendered without an associated label. You have to specify one if you want it to be displayed:
Output:
You can change the label's tag attributes by passing an associative array. In that case you have to use the special text
attribute in order to set the label's text:
Output:
By default, the label is rendered above the widget.
If you want it to be displayed in the same line you can use the special inline
attribute:
Output:
Set the field as required
Call the required
method passing the error message to be shown in case the field is left blank:
Output:
Activate error messsages
By default, error messages are not displayed along the field if any validation error occurs internally. You can change that by calling the error
method with a positive value:
Output:
You can customize the error message tag by passing an array of attributes to the error function.
Output:
Notice that in this case we enable the error display by setting the 'display' attribute.
Disable error displaying by passing a negative (i.e. false) argument:
Output:
Notice: you could instead pass the 'display' attribute set to false
Make error tag display in the same line using inline
option:
Output:
Specify a default value
You can setup a default value to be used in case the field is left blank and/or a validation error occurs:
Output: