Our blog! | Send us feed | Ask us questions
main | downloads | documentation | comunity | about lionframework

Class: __FileBoxComponent


Class Overview

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail
This class represents a file uploader component.

A filebox has 2 working modes:

  • Synchronous mode: The filebox uploads the file just when the container form is submitted to
  • Asynchronous mode: The filebox uploads the file as soon as it has been selected by the user

The mode can be set by setting the uploadMode attribute. By default a filebox is synchronous.

In asynchronous mode, as soon as a filebox finish uploading the file it shows a checkbox checked with the name of the already uploaded file.
The user can unchek the checkbox, cancelling (reseting) the uploaded file

In synchronous mode, the filebox works as an HTML file element.

Note: If APC extension is present, a filebox can show a progressbar showing the the upload progress (only in asynchronous mode)

FileBox tag is filebox

i.e. 

  1.    <comp:filebox name = "client_picture"
    2. 

  2.            uploadMode = "asynchronous"
    3. 

  3.          showProgress = "yes"/>
    4.

A upload component can show the upload progress by setting the showProgress property to true.

While a filebox component is uploading a file to the server in asynchronous mode, the container form will wait until the component has uploaded the file. We can also show a progress bar to the submit button by setting the container form into the waitingComponents attribute.

i.e.

  1.    <comp:form name="client_form">
    2. 

  2.  
    3. 

  3.      ...
    4. 

  4.      <comp:filebox name = "client_picture"
    5. 

  5.              uploadMode = "asynchronous"
    6. 

  6.            showProgress = "yes"
    7. 

  7.       waitingComponents = "client_form"/>
    8. 

  8.      ...
    9. 

  9.  
    10. 

  10.      <comp:commandbutton type = "submit"
    11. 

  11.                          name = "submit_client_form"
    12. 

  12.                       caption = "Submit"/>
    13. 

  13.  
    14. 

  14.    </comp:form>
    15.

waitingComponents property accepts a comma-separated list of components that will wait until the filebox is uploading a file.

We can restrict type/size of files to be uploading by adding a validation rule to restrict both parameters
i.e. 

  1.   <comp:filebox name = "client_picture"
    2. 

  2.           uploadMode = "asynchronous"
    3. 

  3.         showProgress = "yes"
    4. 

  4.    waitingComponents = "client_form"/>
    5. 

  5.  
    6. 

  6.   <comp:validationrule component = "client_picture"
    7. 

  7.               validateOnlyOnBlur = "true"
    8. 

  8.                      maxFileSize = "5242880"
    9. 

  9.                allowedExtensions = "jpg,gif,png"/>
    10.

Once we have upload a file by ussing this component, we can save the file by ussing the save method, i.e. 

  1.    public function client_form_submit(__UIEvent &$event) {
    2. 

  2.  
    3. 

  3.        //save the picture to the harddrive:
    4. 

  4.        $client_picture = $this->getComponent('client_picture');
    5. 

  5.        $client_picture->save('destination_path_and_filename.jpg');
    6. 

  6.  
    7. 

  7.    }
    8.

In asynchronous mode, a filebox raises the uploaded event once a file has been uploaded successfully to the server.
We can also save the picture as soon as it's uploaded to the server by handling this event.

i.e. 

  1.    public function client_picture_uploaded(__UIEvent &$event) {
    2. 

  2.  
    3. 

  3.        //save the picture to the harddrive once it has been uploaded:
    4. 

  4.        $client_picture = $this->getComponent('client_picture');
    5. 

  5.        $client_picture->save('destination_path_and_filename.jpg');
    6. 

  6.  
    7. 

  7.    }
    8.

We do not recommend to use the uploaded event with a filebox inside a form, but handle it within the submit event.
The uploaded event could be usefull for filebox outside form components.



See the filebox component in action here: http://www.lionframework.org/components/filebox.html


Author:  Antonio Parraga Navarro
Version:  1.1.125 beta
Copyright:  Copyright (c) 2008 Antonio Parraga Navarro
See:  __ItemListComponent, __ListBoxComponent 
__UIComponent
   |
   --__UIContainer
      |
      --__InputComponent
         |
         --__FileBoxComponent

Properties

Methods
[ Top ]

Inherited Properties, Constants, and Methods

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail
Inherited Properties Inherited Methods Inherited Constants

Inherited From __InputComponent

Inherited From __UIContainer

Inherited From __UIComponent

Inherited From __InputComponent

Inherited From __UIContainer

Inherited From __UIComponent

[ Top ]

Properties Summary

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail
mixed   $_current_size  
mixed   $_filename  
mixed   $_icon  
mixed   $_rate  
mixed   $_size  
mixed   $_status  
mixed   $_temp_file  
mixed   $_type  
mixed   $_upload_mode  

[ Top ]

Method Summary

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail
void   clearFile()   Alias of __FileBoxComponent::reset() method
integer   getCurrentSize()   Get the in-progress uploaded portion size in bytes
string   getFilename()   Get the filename represented by the current filebox
void   getHandledEvents()  
string   getIcon()   Get the url of the image to be shown in case the status is UPLOAD_STATUS_DONE
integer   getRate()   Get the upload rate
integer   getSize()   Get the uploaded file size in bytes
integer   getStatus()   Get a value representing the status of the current filebox
string   getTempFile()   Gets the name of the file where the uploaded file is stored as temporally
void   getType()  
integer   getUploadMode()   Get a value representing the upload mode
void   handleEvent()  
void   isEventHandled()  
void   reset()   Reset the filebox value
void   save()   Saves the uploaded file in the given path.
void   setCurrentSize()   To be used internally by the framework, set the in-progress uploaded file portion size
void   setFilename()   Set the filename represented by the current filebox.
void   setIcon()   Set the url to an image to be shown closet to the filebox in case the status is UPLOAD_STATUS_DONE.
void   setRate()   To be used internally by the framework, set the current upload rate
void   setSize()   To be used internally by the framework, set the uploaded file size
void   setStatus()   Set a value representing the status of the current filebox component.
void   setTempFile()   To be used internally by the framework, to set the name of the temporal file where the uploaded file is stored temporally
void   setType()  
void   setUploadMode()   Set a value representing the upload mode, which it can be:
void   setValue()   Alias of setFilename
void   updateStatus()   To be used internally by the framework, and just in case the APC extension is present.

[ Top ]

Properties

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail
mixed   $_current_size = null
Access:  protected


mixed   $_filename = null
Access:  protected


mixed   $_icon = null
Access:  protected


mixed   $_rate = null
Access:  protected


mixed   $_size = null
Access:  protected


mixed   $_status = __IUploaderComponent::UPLOAD_STATUS_READY
Access:  protected


mixed   $_temp_file = null
Access:  protected


mixed   $_type = null
Access:  protected


mixed   $_upload_mode = __IUploaderComponent::UPLOAD_MODE_SYNCHRONOUS
Access:  protected


Methods

Class Overview | Inherited Properties, Constants, and Methods | Properties Summary | Properties Detail | Method Summary | Methods Detail

clearFile


  void clearFile( )

Alias of __FileBoxComponent::reset() method

Access:  public



getCurrentSize


  integer getCurrentSize( )

Get the in-progress uploaded portion size in bytes

Return:  The uploaded file portion size in bytes
Access:  public



getFilename


  string getFilename( )

Get the filename represented by the current filebox

Access:  public



getHandledEvents


  void getHandledEvents( )

Access:  public

Redefinition of:
__UIComponent::getHandledEvents()


getIcon


  string getIcon( )

Get the url of the image to be shown in case the status is UPLOAD_STATUS_DONE

Access:  public



getRate


  integer getRate( )

Get the upload rate

Return:  The upload rate in bytes
Access:  public



getSize


  integer getSize( )

Get the uploaded file size in bytes

Return:  The file size in bytes
Access:  public



getStatus


  integer getStatus( )

Get a value representing the status of the current filebox

Access:  public



getTempFile


  string getTempFile( )

Gets the name of the file where the uploaded file is stored as temporally

Access:  public



getType


  void getType( )

Access:  public



getUploadMode


  integer getUploadMode( )

Get a value representing the upload mode

Access:  public



handleEvent


  void handleEvent( __UIEvent &$event  )


Parameters:
TypeNameDescription
__UIEvent &$event

Access:  public

Redefinition of:
__UIComponent::handleEvent()


isEventHandled


  void isEventHandled( $event_name  )


Parameters:
TypeNameDescription
$event_name

Access:  public

Redefinition of:
__UIComponent::isEventHandled()


reset


  void reset( )

Reset the filebox value

Access:  public

Redefinition of:
__InputComponent::reset()


save


  void save( string $dest_path  )

Saves the uploaded file in the given path.


Parameters:
TypeNameDescription
string $dest_path The path to save the file to

Access:  public



setCurrentSize


  void setCurrentSize( integer $current_size  )

To be used internally by the framework, set the in-progress uploaded file portion size


Parameters:
TypeNameDescription
integer $current_size The in-progress uploaded file portion size in bytes

Access:  public



setFilename


  void setFilename( string $filename  )

Set the filename represented by the current filebox.

The filename is the value of a filebox from the point of view of a __IValueHolder.



Parameters:
TypeNameDescription
string $filename

Access:  public



setIcon


  void setIcon( string $icon  )

Set the url to an image to be shown closet to the filebox in case the status is UPLOAD_STATUS_DONE.

The image is usually an image representing the uploaded file (i.e. an icon corresponding to the file type, or a thumbnail)



Parameters:
TypeNameDescription
string $icon

Access:  public



setRate


  void setRate( integer $rate  )

To be used internally by the framework, set the current upload rate


Parameters:
TypeNameDescription
integer $rate

Access:  public



setSize


  void setSize( integer $size  )

To be used internally by the framework, set the uploaded file size


Parameters:
TypeNameDescription
integer $size The size in bytes

Access:  public



setStatus


  void setStatus( integer $status  )

Set a value representing the status of the current filebox component.

Status are defined within the __IUploaderComponent, being the most important:



Parameters:
TypeNameDescription
integer $status

See:  __IUploaderComponent
Access:  public



setTempFile


  void setTempFile( string $temp_file  )

To be used internally by the framework, to set the name of the temporal file where the uploaded file is stored temporally


Parameters:
TypeNameDescription
string $temp_file

Access:  public



setType


  void setType( $type  )


Parameters:
TypeNameDescription
$type

Access:  public



setUploadMode


  void setUploadMode( integer $upload_mode  )

Set a value representing the upload mode, which it can be:



Parameters:
TypeNameDescription
integer $upload_mode

Access:  public



setValue


  void setValue( string $value  )

Alias of setFilename


Parameters:
TypeNameDescription
string $value

Access:  public

Redefinition of:
__InputComponent::setValue()


updateStatus


  void updateStatus( )

To be used internally by the framework, and just in case the APC extension is present.

This method updates the status of the current component by asking to APC about the upload progress


Access:  public



Copyright (c) 2008, www.lionframework.org