Fetches an object that was persisted with persist()
Class Details
[line 38]
Form Element Class
basic implementation of an html form element. is never instanced alone,
only extended by one of the following classes:
- FormField - FormText
- FormContainer - FormHtml
- FormImage - FormPhp
- FormLine - ...
data structure: hash where key is the named user/group. value is a string or a hash again. if it's a hash then the key is the 'mode' (view, add, edit ...). if it's a string then it's the value directly, something like 'normal', show' etc (see $visibility).
moved this var from Bs_FormField to Bs_FormElement in bs-4.5.
the title for this field. in this example, the caption is 'your birthday': your birthday: <input type="text" name="birthday"> usually a string, can be a hash because it's language dependant.
a layout string for the element. if not given then the setting from Bs_Form->elementLayout will be used. if used then $this->hideCaption will be ignored.
example for a text form field:
__CAPTION_FOR_FORM_OUTPUT__
__ELEMENT__
placeholders:
__ELEMENT__ => the field or form element.
__CAPTION_FOR_FORM_OUTPUT__ => the element caption as html (with accessKey or whatever).
__CAPTION__ => the element caption. better use the other one.
this feature is being demonstrated in: http://www.blueshoes.org/_bsCore/html/form/examples/elementLayout.php
Tags:
since:
bs4.3
see:
$this->getElementLayout(), var Bs_Form->elementLayout
you may want to not only spit out the element but spit it out with other things, like some html code on both sides. so if used, this is the format argument of the sprintf function.
example: here we add an image that'll be displayed after the element (form field). $elementStringFormat = "%s <img src='someImage.gif'>"; this feature is being demonstrated in: http://www.blueshoes.org/_bsCore/html/form/examples/elementLayout.php
structure: usually a string, can be a hash because it's language dependant.
the name of the element. must be unique for this form.
note: for form fields the name can be like an array: foo['bar'] (not foo[bar]) with that feature you can 'explode' fields too. a good example is the dsn db information. you want to have the values in one var called dbDsn. but in the form you don't want the explode-feature because every value (host, port ...) needs to be validated differently.
it's possible that we may not allow the user to change the value of this input field. if $visibility is not set, the visibility/changeability depends on Bs_FormField->editability. it will be visible and editable, or visible but not editable.
otherwise this value 'overwrites' Bs_FormField->editability.
these values are accepted:
FIELD VISIBLE EDITABLE STORE (=use value)
- 'normal' x x x
- 'read' x - x
- 'readonly' x - -
- 'show' x - -
- 'invisible' - - x
- 'omit' - - -
some background information for the coder:
normal => well... field is sent the normal way, value will be used on the
server.
read => value is not changeable by the user, but will be used on the
server. same as readonly, except it's used.
i have spent about an hour to find names for these vars, and
did not come up with something better. sucks.
readonly => will make the field hopefully not changeable by the user.
eg for a text field that means set the params readonly (html 4.0)
and disabled (ie4+)
in some cases we prolly need to omit sending an input field and
send the existing value as raw text so it's not changeable.
if it happens that the user still can change it, it doesn't matter
cause the value will be ignored on the receiving server anyway.
conused about the name? and why the value won't be stored?
it's "read only", so it can "only be read", not more.
show shows the value "printed out". without a form field. just printed
out like this text here. like 'readonly' but looks different.
example difference to 'readonly': for a radio button field
'readonly' will show all options using images that look like radio
buttons. the user sees all options and which one is selected. for
'show' the user only sees the selected value, no other options.
invisible => add the existing (default) value in a .
it's a little security hole cause someone could change the value.
needs to be checked on the server side (todo).
omit => field/value are not sent at all. however, it's possible that some
invisible information is sent so the receiving server knows this
field exists.
caution: see vars $equalTo and $notEqualTo.
moved this var from Bs_FormField to Bs_FormElement in bs-4.5.