| core_html

# Class: Bs_FormElement Source Location: /core/html/form/Bs_FormElement.class.php
### Class Overview
    Bs_Object
       |
       --Bs_FormElement
Form Element Class #### Author(s): andrej arn <at blueshoes dot org> #### Version: 4.3.$Revision: 1.4 $ $Date: 2003/10/29 17:48:38 $ #### Copyright: blueshoes.org | ### Variables $accessRights $caption $container $elementLayout $elementStringFormat $elementType $FormID $hideCaption $name $orderId $persister $persisterID $persisterVarSettings $visibility $_form | ### Methods Bs_FormElement getCaption getCaptionForFormOutput getElement getElementLayout getLanguageDependentValue getLevel getVisibility hasFormObject setFormObject
### Child classes: Bs_FormCode Form Code Class Bs_FormContainer Form Container Class Bs_FormField Abstract Form Field Class Bs_FormHtml Html Element Class Bs_FormImage Form Image Class Bs_FormLine Form Line Class Bs_FormText Form Text Class | ### Inherited Variables | ### Inherited Methods #### Class: Bs_Object Bs_Object::Bs_Object() Bs_Object::getErrors() Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack. Bs_Object::getLastError() Basic error handling: Get last error string from the global Bs_Error-error stack. Bs_Object::getLastErrors() Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors(). Bs_Object::persist() Persists this object by serializing it and saving it to a file with unique name. Bs_Object::setError() Basic error handling: Push an error string on the global Bs_Error-error stack. Bs_Object::toHtml() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::toString() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::unpersist() 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        - ...
dependencies: Bs_ObjPersisterForMySql #### Tags:
copyright: | blueshoes.org
pattern: | singleton: (pseudostatic)
access: | public
version: | 4.3.$Revision: 1.4 $ $Date: 2003/10/29 17:48:38 $
author: | andrej arn <at blueshoes dot org>
[ Top ] ### Class Variables #### $accessRights = [line 226] if set then it will overwrite the Bs_FormField->editability and $visibility vars. the current user/group comes from Bs_Form->user.
     example:
       $myField->accessRights = array(
         'user'  => array(
           'add'   => 'normal',
           'edit'  => 'show',
         ),
         'admin' => 'normal',
       );
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. #### Tags:
see: | $this->getVisibility(), vars Bs_FormField->editability, Bs_FormElement::$visibility, var Bs_Form->user
access: | public
Type: | array
[ Top ] #### $caption = NULL [line 175] 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. #### Tags:
see: | $this->getCaption(), Bs_FormElement::getCaptionForFormOutput()
Type: | mixed
[ Top ] #### $container = [line 111] the container to which this element belongs. note: container may be of type Bs_FormContainer or Bs_DaFormPageControl.
Type: | string
[ Top ] #### $elementLayout = [line 147] 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
access: | public

Type: | string

[ Top ]

#### $elementStringFormat =

[line 166]

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.

#### Tags:

see: | $this->_doElementStringFormat()
access: | public

Type: | mixed

[ Top ]

#### $elementType =

[line 98]

one of

- field
- container
- image
- line
- text
- html
- php

Type: | mixed

[ Top ]

#### $FormID =

[line 104]

form id, means to which form this element belongs.

Type: | int

[ Top ]

#### $hideCaption =

[line 196]

if the caption should be hidden. by default this is off.

if $this->elementLayout is used then this will be ignored.

especially useful for checkbox fields. often it looks better to have X do you want our newsletter? instead of do you want our newsletter? X newsletter

1. = use the caption. default (but overwritten in some form elements, namely the non-fields.)
2. = just don't use the caption in the output
3. = don't use the caption, and align the field to the left.

not set or null means 0.

#### Tags:

since: | bs4.3
access: | public

Type: | int

[ Top ]

#### $name =

[line 86]

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.

Type: | string

[ Top ]

#### $orderId =

[line 118]

the order number (in the container, if set) in that the element should be spitted out to the browser. the higher the number, the higher the priority.

Type: | int

[ Top ]

#### $persister = NULL

[line 47]

instance of Bs_ObjPersisterForMySql to persist the settings.

Type: | object

[ Top ]

#### $persisterID =

[line 53]

reserved var for the persister. don't fuck with this.

Type: | int

[ Top ]

#### $persisterVarSettings = array('name' => array('mode'=>'lonely', 'metaType'=>'string', 'index'=>TRUE),'elementType'=>array('mode'=>'lonely','metaType'=>'string','index'=>TRUE),'FormID'=>array('mode'=>'lonely','metaType'=>'integer','index'=>TRUE),'container'=>array('mode'=>'stream'),'orderId'=>array('mode'=>'stream'),'elementStringFormat'=>array('mode'=>'stream'))

[line 55]

Type: | mixed

[ Top ]

#### $visibility =

[line 283]

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.

#### Tags:

see: | $this->getVisibility(), vars Bs_FormField->editability, Bs_FormElement::$accessRights
access: | public

Type: | string

[ Top ]

#### $_form =

[line 71]

a reference to the form object holding this form field.

this is needed for various information, like the language we're in.

Type: | object

[ Top ]

### Class Methods

### constructor Bs_FormElement [line 289]

`Bs_FormElement Bs_FormElement( )`

Constructor.
[ Top ]

### method getCaption [line 329]

`string getCaption( )`

Return the caption string (for the current language).

#### Tags:

return: | the caption for this field.
see: | var $this->caption, $this->getLabel().
access: | public

Overridden in child classes as:

Bs_FormField::getCaption()
  Return the caption string (for the current language).

Bs_FormFieldCheckbox::getCaption()
  Return the caption string (for the current language).

[ Top ]

### method getCaptionForFormOutput [line 341]

`string getCaptionForFormOutput( )`

returns the caption. here in Bs_FormElement it's the same getCaption() but in Bs_FormField which overwrites these methods it makes a difference.

#### Tags:

return: | the caption for this field.
see: | var $this->caption, $this->getCaption().
access: | public

Overridden in child classes as:

Bs_FormField::getCaptionForFormOutput()
  returns the caption string to use in the form output. so expect html here and not plaintext.

[ Top ]

### method getElement [line 353]

`string getElement( )`

Return some html code to display the element on a website in a form.

better overwrite this method.

#### Tags:

access: | public

Overridden in child classes as:

Bs_FormCode::getElement()
  Return some html code to display the element on a website in a form.

Bs_FormContainer::getElement()
  Return some html code to display the element on a website in a form.

Bs_DaFormPageControl::getElement()
  Return some html code to display the element on a website in a form.

Bs_FormField::getElement()
  Return some html code to display all the exploded fields on a website in a form.

Bs_FormHtml::getElement()
  Return some html code to display the element on a website in a form.

Bs_FormImage::getElement()
  Return some html code to display the element on a website in a form.

Bs_FormLine::getElement()
  Return some html code to display the element on a website in a form.

Bs_FormText::getElement()
  Return some html code to display the element on a website in a form.

[ Top ]

### method getElementLayout [line 429]

`string getElementLayout( )`

returns the layout string for this element.

#### Tags:

since: | bs4.3
see: | vars $this->elementLayout, Bs_Form->elementLayouts
throws: | bool FALSE (if nothing available)
access: | public

[ Top ]

### method getLanguageDependentValue [line 529]

`string getLanguageDependentValue( mixed $var, [string $lang = null])`

returns the value of a [language dependant] [object] var for the current or given language.

#### Tags:

todo: | i have moved this method to bs_textutil. we should use it instead to avoid double-maintenance.
throws: | NULL if var is not set [correctly].
access: | public

#### Parameters:

mixed | $var | (the var where the values are in. string or array (hash).)
string | $lang | (default is null. if not given then the lang setting of the form is used.)

[ Top ]

### method getLevel [line 365]

`int getLevel( )`

returns the level this element belongs to.

throws null for unknown or not set.

#### Tags:

throws: | null
access: | public

Overridden in child classes as:

Bs_FormContainer::getLevel()
  returns the level this container belongs to.

[ Top ]

### method getVisibility [line 383]

`string getVisibility( )`

returns how this field/element should be visible and editable to the user.

moved this var from Bs_FormField to Bs_FormElement in bs-4.5.

#### Tags:

return: | one of 'read', 'readonly', 'show', 'invisible', 'omit', 'normal' (default).
see: | vars Bs_FormField->editability, $this->visibility, $this->accessRights
access: | public

[ Top ]

### method hasFormObject [line 303]

`bool hasFormObject( )`

tells if we have a reference to a form object where we can grab some information.

#### Tags:

access: | public

[ Top ]

### method setFormObject [line 314]

`bool setFormObject( object &$form)`

set a reference to a form object.

#### Tags:

return: | true on success, false on failure.
access: | public

#### Parameters:

object | &$form |

[ Top ]

Documentation generated on Mon, 29 Dec 2003 21:09:24 +0100 by phpDocumentor 1.2.3