| core_html

# 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): andrej arn <at blueshoes dot org> #### Version: 4.3.$Revision: 1.6 $ $Date: 2003/12/14 09:52:03 $ #### Copyright: blueshoes.org | ### Variables $allowedTypes $diskStorage $fileInfo $fileSizeUpdateIni $maxFileSize $minFileSize $showCurrentFile $showCurrentFilePrefixPath | ### Methods Bs_FormFieldFile getField inputValidate postReceiveTrigger setValueFromPreviousSubmit _makeTempFullPath
### Inherited Variables #### Class: Bs_FormFieldTxt Bs_FormFieldTxt::$size #### 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 #### Class: Bs_FormElement Bs_FormElement::$accessRights Bs_FormElement::$caption Bs_FormElement::$container Bs_FormElement::$elementLayout Bs_FormElement::$elementStringFormat Bs_FormElement::$elementType Bs_FormElement::$FormID Bs_FormElement::$hideCaption Bs_FormElement::$name Bs_FormElement::$orderId Bs_FormElement::$persister Bs_FormElement::$persisterID Bs_FormElement::$persisterVarSettings Bs_FormElement::$visibility Bs_FormElement::$_form | ### 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