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

Class: Bs_FormFieldFile

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

Class Overview

Bs_Object
   |
   --Bs_FormElement
      |
      --Bs_FormField
         |
         --Bs_FormFieldTxt
            |
            --Bs_FormFieldFile

FILE Form Field Class (for uploading files to the server).


Author(s):

Version:

  • 4.3.$Revision: 1.6 $ $Date: 2003/12/14 09:52:03 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Class: Bs_FormField

Bs_FormField::$additionalCheck
Bs_FormField::$additionalTags
Bs_FormField::$advancedStyles
Bs_FormField::$bsDataInfo
Bs_FormField::$bsDataManipulation
Bs_FormField::$bsDataManipVar
Bs_FormField::$bsDataType
Bs_FormField::$case
Bs_FormField::$codePostLoad
Bs_FormField::$codePostManipulate
Bs_FormField::$codePostReceive
Bs_FormField::$dbAttributes
Bs_FormField::$dbAutoIncrement
Bs_FormField::$dbDataType
Bs_FormField::$dbFieldName
Bs_FormField::$dbForeignKey
Bs_FormField::$dbIndexFulltext
Bs_FormField::$dbKey
Bs_FormField::$dbNotNull
Bs_FormField::$dbPrimaryKey
Bs_FormField::$dbUnique
Bs_FormField::$defaultErrorMessage
Bs_FormField::$direction
Bs_FormField::$editability
Bs_FormField::$enforce
Bs_FormField::$equalTo
Bs_FormField::$errorMessage
Bs_FormField::$errorType
Bs_FormField::$events
Bs_FormField::$explodeEval
Bs_FormField::$fieldType
Bs_FormField::$isUsed
Bs_FormField::$level
Bs_FormField::$maxLength
Bs_FormField::$minLength
Bs_FormField::$must
Bs_FormField::$mustBeUnique
Bs_FormField::$mustContain
Bs_FormField::$mustEndWith
Bs_FormField::$mustIf
Bs_FormField::$mustOneOf
Bs_FormField::$mustOneOfIf
Bs_FormField::$mustStartWith
Bs_FormField::$notContain
Bs_FormField::$notEndWith
Bs_FormField::$notEqualTo
Bs_FormField::$notStartWith
Bs_FormField::$onEnter
Bs_FormField::$onlyIf
Bs_FormField::$onlyOneOf
Bs_FormField::$onlyOneOfIf
Bs_FormField::$regularExpression
Bs_FormField::$remove
Bs_FormField::$removeI
Bs_FormField::$replace
Bs_FormField::$replaceI
Bs_FormField::$saveToDb
Bs_FormField::$styles
Bs_FormField::$trim
Bs_FormField::$valueDefault
Bs_FormField::$valueDefaultType
Bs_FormField::$valueDisplay
Bs_FormField::$valueInternal
Bs_FormField::$valueReceived
Bs_FormField::$_Bs_String
Bs_FormField::$_explodeArray
Bs_FormField::$_must

Inherited Methods

Class: Bs_FormFieldTxt

Bs_FormFieldTxt::Bs_FormFieldTxt()
constructor
Bs_FormFieldTxt::getField()
Return some html code to display the field on a website in a form.

Class: Bs_FormField

Bs_FormField::Bs_FormField()
Constructor.
Bs_FormField::addEnforceCheckbox()
add enforce checkbox if needed.
Bs_FormField::applyOnEnterBehavior()
merges the onEnter javascript call into the events array if needed.
Bs_FormField::getAdvancedStyle()
returns the advanced style for the given key.
Bs_FormField::getAdvancedStyleHelper()
returns the advanced style for the field itself or the caption, taking the current mode into account.
Bs_FormField::getCaption()
Return the caption string (for the current language).
Bs_FormField::getCaptionForFormOutput()
returns the caption string to use in the form output. so expect html here and not plaintext.
Bs_FormField::getDbDataType()
returns the db datatype to use for this field.
Bs_FormField::getDbFieldName()
returns the db field name you should use for this field.
Bs_FormField::getElement()
Return some html code to display all the exploded fields on a website in a form.
Bs_FormField::getError()
returns the error message for the current field, or an empty string if no error.
Bs_FormField::getErrorMessage()
returns a textual error message for the given error type.
Bs_FormField::getField()
overwrite this method in your subclass.
Bs_FormField::getFieldAsHidden()
Return some html code to send to the client. same as getField() but returns the field like a hidden field, no matter what field type it is.
Bs_FormField::getHelp()
returns the help text
Bs_FormField::getLabel()
Return the label tag (for the current language).
Bs_FormField::getOnEnterBehavior()
tells how this form field should behave when the user hits enter.
Bs_FormField::getOnEnterCode()
returns some javascript code (the call) to behave the way the coder wants.
Bs_FormField::getValue()
returns the value.
Bs_FormField::hasJavascript()
tells whether the client browser has javascript support or not.
Bs_FormField::inputManipulate()
manipulate the user inputs according to the object vars.
Bs_FormField::inputValidate()
validate the user inputs according to the object vars.
Bs_FormField::isExplodable()
tells if this is an explodable field.
Bs_FormField::isFilledIn()
tells if the user filled in this field *somehow*. does not tell if the input was ok/accepted.
Bs_FormField::isMust()
tells if the field has to be filled in according to the current settings.
Bs_FormField::postManipulateTrigger()
gets called after the user input has been set to the form fields, and the needed automatic manipulations have been done.
Bs_FormField::postReceiveTrigger()
gets called right after the user input has been set to the form fields.
Bs_FormField::setExplode()
explode this field into multiple ones?
Bs_FormField::shouldPersist()
tells if the received value should be persisted (used) this time.
Bs_FormField::unpersistTrigger()
gets executed automatically in some circumstances:
  • by the ObjPersister. read there for more info.
Bs_FormField::validateAdditionalCheck()
additionalCheck
Bs_FormField::validateDataType()
bsDataType/bsDataInfo
Bs_FormField::validateEqualTo()
equalTo
Bs_FormField::validateMaxLength()
checks the maxLength case.
Bs_FormField::validateMinLength()
checks the minLength case.
Bs_FormField::validateMust()
must
Bs_FormField::validateMustBeUnique()
checks the mustBeUnique case. the check is made non-case-sensitive.
Bs_FormField::validateMustContain()
mustContain
Bs_FormField::validateMustEndWith()
mustEndWith
Bs_FormField::validateMustStartWith()
mustStartWith
Bs_FormField::validateNotContain()
notContain
Bs_FormField::validateNotEndWith()
notEndWith
Bs_FormField::validateNotEqualTo()
notEqualTo
Bs_FormField::validateNotStartWith()
notStartWith
Bs_FormField::validateOnlyIf()
onlyIf
Bs_FormField::validateOnlyOneOf()
onlyOneOf
Bs_FormField::validateRegularExpression()
regularExpression

Class: Bs_FormElement

Bs_FormElement::Bs_FormElement()
Constructor.
Bs_FormElement::getCaption()
Return the caption string (for the current language).
Bs_FormElement::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.
Bs_FormElement::getElement()
Return some html code to display the element on a website in a form.
Bs_FormElement::getElementLayout()
returns the layout string for this element.
Bs_FormElement::getLanguageDependentValue()
returns the value of a [language dependant] [object] var for the current or given language.
Bs_FormElement::getLevel()
returns the level this element belongs to.
Bs_FormElement::getVisibility()
returns how this field/element should be visible and editable to the user.
Bs_FormElement::hasFormObject()
tells if we have a reference to a form object where we can grab some information.
Bs_FormElement::setFormObject()
set a reference to a form object.

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 67]
FILE Form Field Class (for uploading files to the server).

example tag: <input name="fieldname" type="file" size="20">

 what's special about this tag?
   - $valueDefault  => there is no, no, no way to give the form field a default value.
                       forget it, even js does not help. believe me.
                       if you could set a default value, you could auto-submit
                       a hidden form and steal files from the users computer.
                       so valueDefault is the value (path) we currently have. and that's
                       what we show (next to the field).
   - $valueReceived => the original file/path we got from the browser, that is
                       where the file was on the clients machine.
   - $valueDisplay  => same as $valueReceived, but makes no sense to use/display it.
   - $valueInternal => same as $valueReceived, but makes no sense to use it.
   - keep file      => if a file has been uploaded, but the form has not been
                       completely accepted (errors in other fields) we keep
                       the temp file on the server. the user does not need
                       to resubmit the file, but he may do that (to overwrite).
 

validating: all validation rules etc are for the given file name. for example a maxLength of 20 here means that the user file (the fullpath on the users machine, as submitted) may not be longer than 20 characters. if it makes sense to use these validators here is up to you. if you want to check the file size (bits) then use the special vars of this class.

WARNING: until things get stable here this class has to be considered experimental. there are things that could go wrong with the complexity of the form classes (multilevel forms, different values like valueDisplay, etc). 2003-01-07 --andrej please don't use the explode functionality here [yet], things would go wrong.

general file upload issues:

   1) Another issue with large file sizes. Make sure you set the ammount of
      memory to be higher in the PHP.ini file if you want to transfer files over
      8MB(default) or it won't transfer, you'll get a "page cannot be displayed".
   2) don't put an underscore _ in the file form field name. it won't work on mac and maybe win98.
   3) If the upload file size exceeds MAX_FILE_SIZE, $userfile will be set to 'none'.
   4) The http proxy "Squid" limits PUT/POST requests to 1 MB per default!
      see http://squid.visolve.com/squid24s1/tuning.htm#request_body_max_size
 

dependencies: Bs_FormFieldTxt, Bs_FileSystem

reading: http://www.php.net/manual/en/features.file-upload.php




Tags:

copyright:  blueshoes.org
pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.6 $ $Date: 2003/12/14 09:52:03 $
author:  andrej arn <at blueshoes dot org>


[ Top ]


Class Variables

$allowedTypes =

[line 80]

the file types we accept.

by default anything goes. array('doc', 'xls') means all we accept is .doc and .xml files, case does not matter. int 1 means we only accept web images (jpg, jpeg, gif, png)




Tags:

access:  public

Type:   mixed


[ Top ]

$diskStorage =  NULL

[line 151]

hash with the keys:

'path' //'name' //'extension'




Tags:

since:  bs4.3
access:  public

Type:   array


[ Top ]

$fileInfo =  0

[line 139]

array with information about the uploaded file.

gets set in $this->_keepUploadedFile().

has these keys:

   'origFullPath' => the file full path (or name only, depending on browser) as it was on the clients machine. very interesting :-)
   'tmpFullPath'  => the full path to the temporary file.
   'mimeType'     => like 'image/gif', 'text/html' etc. if provided by the browser.
   'sizeBytes'    => the file size in bytes
   'errorCode'    => int, 0 = everything ok, >0 = not ok.
                     read http://www.php.net/manual/en/features.file-upload.errors.php
                     even if the user has an older version than php4.2 we set this var.
   'errorText'    => textual error message. empty by default.
   'extension'    => the file extension, eg 'gif' for a file uploaded as '/dir/foo.xy.gif'
 

if you wanna know if a valid file was submitted then always check 'errorCode' and nothing else.

    0  => everything ok, file uploaded correctly.
    ERROR (not 0, means no file recieved)
    1  => The uploaded file exceeds the upload_max_filesize directive in php.ini.
    2  => The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the html form.
    3  => The uploaded file was only partially uploaded.
    4  => No file was uploaded. (that may be ok if there is no need to upload!)
    5  => Uploaded file size 0 bytes (undocumented php constant)
    9  => unknown error (in pre-php-4.2 versions, that means a file upload was attempted but failed. like error code 1-3 or 5.)
   99  => unknown system problem (could not rename temp file).
   treat every other number > 0 as "something failed, but dunno what".
 




Tags:

var:  (hash, see above)

Type:   array


[ Top ]

$fileSizeUpdateIni =  TRUE

[line 103]

if the maxFileSize specified here is larger than the value specified in the ini file then we'll automatically update the ini (for this request, right?).



Tags:

todo:  all (that won't work, as far as i see it. --andrej)
access:  public

Type:   bool


[ Top ]

$maxFileSize =

[line 87]

max file size in bytes, if any.



Tags:

access:  public

Type:   int


[ Top ]

$minFileSize =

[line 94]

min file size in bytes, if any.



Tags:

access:  public

Type:   int


[ Top ]

$showCurrentFile =  1

[line 171]

should there be a note about the currently saved file?

    1 = as text (default)
    2 = as text with link to file in new window
    3 = as text with link to file in popup (not coded yet, falls back to option 2)
    4 = as text, and show file directly in browser if it is an image (gif, jpg or png),
        otherwise put a link to target "_blank" just as option 2. only recommended for small images.
        todo: check that it's an image. maybe check image size and width/height, and set some limit.
              if over limit then fall back to link.
 




Tags:

see:  var $this->showCurrentFilePrefixPath
since:  bs4.3
access:  public

Type:   int


[ Top ]

$showCurrentFilePrefixPath =  ''

[line 190]

if var $showCurrentFile is set to 2-4 then we need to know the full path of the file.

we may not have that information in $valueDefault, it most probably is a subpath. anyway, you can give a prefix path here. note that if your file is not located in the webroot and you still want to link to it, you can give a prefix path like "/showFile.php?file=" which will take the file name as param, and spit it out.

examples: $showCurrentFilePrefixPath = '/foo/'; $showCurrentFilePrefixPath = 'http://www.host.com/foo/'; $showCurrentFilePrefixPath = '/showFile.php?file=';




Tags:

see:  var $this->showCurrentFile
since:  bs4.3
access:  public

Type:   string


[ Top ]



Class Methods


constructor Bs_FormFieldFile [line 205]

Bs_FormFieldFile Bs_FormFieldFile( )

constructor



[ Top ]

method getField [line 222]

string &getField( [mixed $explodeKey = NULL], [bool $addEnforceCheckbox = TRUE])

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

overwrites parent method.




Tags:

return:  some html code
see:  $this->getFieldAsHidden(), $this->addEnforceCheckbox()
access:  public


Overrides Bs_FormFieldTxt::getField() (Return some html code to display the field on a website in a form.)

Parameters:

mixed   $explodeKey   (int or string)
bool   $addEnforceCheckbox   default is TRUE. adds the enforce checkbox automatically, if needed. see (parent::)addEnforceCheckbox().

[ Top ]

method inputValidate [line 381]

mixed inputValidate( [mixed $paramValue = NULL])

overwrites parent method, look there.

we do all checks except validateDataType and validateMustBeUnique.




Tags:

return:  (see above)
access:  public


Overrides Bs_FormField::inputValidate() (validate the user inputs according to the object vars.)

Parameters:

mixed   $paramValue   (only used internally, for explodable fields.)

[ Top ]

method postReceiveTrigger [line 477]

void postReceiveTrigger( )

overwrites and uses parent method.

needs to be specialized because we need to rename the uploaded file in its temp location, otherwise it gets automatically deleted once the pages life ends.




Tags:

see:  parent method
access:  public


Overrides Bs_FormField::postReceiveTrigger() (gets called right after the user input has been set to the form fields.)

[ Top ]

method setValueFromPreviousSubmit [line 349]

void setValueFromPreviousSubmit( string $dataSerialized, string $md5)

sets the values we have included in the form as hidden fields; the information of a previous file upload.

when we get called that means that no new file has been uploaded, there has not even been an attempt.




Parameters:

string   $dataSerialized  
string   $md5  

[ Top ]

method _makeTempFullPath [line 579]

void _makeTempFullPath( string $dir, string $filePrefix, string $fileName, [int $fileSuffix = 0])

calls itself recursively.



Tags:

access:  public


Parameters:

string   $dir  
string   $filePrefix  
string   $fileName  
int   $fileSuffix   (used on recursive calls only.)

[ Top ]


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