blueshoes php application framework and cms            core_html
[ class tree: core_html ] [ index: core_html ] [ all elements ]

 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:

Class: Bs_FormElement

Source Location: /core/html/form/Bs_FormElement.class.php

Class Overview

Bs_Object
   |
   --Bs_FormElement

Form Element Class


Author(s):

Version:

  • 4.3.$Revision: 1.4 $ $Date: 2003/10/29 17:48:38 $

Copyright:

  • blueshoes.org

Variables

Methods


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__
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