File Upload
===========

File management is an important feature in web applications like image or file galleries and so on. Since file download is quite simple managing it with standard anchor links directly to the files (which will be requested as objects with a proper HTTP request by the browser), this guide will explain the basic knowledge to deal with file uploads and directories reading.

----------------------------------------------------
The upload frontend: building a form for file upload
----------------------------------------------------
Preparing a frontend page for file upload is really simple using HTML forms. When you need to pass data from user interaction to a part of your web application, you usually could use forms, providing settings for the script to be called (and will manage sent data) and others such as the method used for data sending: specifically GET or POST methods. Data could then be collected organising it with ``input`` form elements and givng the user the ability to decide when to send them with a special ``submit`` item. Let's give and example:
::

	<form action="my_script.pyhp" method="get">
	   <input type="text" name="first_field" value="Default text 1" />
	   <input type="text" name="second_field" value="Default text 2" />
	   <input type="submit" value="Send" />
	</form>

The ``method`` clause determines how data will be sent: an HTTP GET method will encode data into the URI/URL, using an HTTP POST method instead will send data in a structure attached inside the HTTP request message. Since the GET method is much simpler and encodes data into the location mnemonic address string, it is limited in size (up to 256 characters): to send much more data like in file uploads you will need to select the POST method, which is only limited to the HTTP server settings for maximum transfer data. Anyway, this isn't enough: forms have also an encoding option specification, which is set by default to ``x-www-url-encoding`` even if unspecified, but this does not correctly encode data contained inside files. To tell the browser to correctly send data, you should also specify the ``enctype="multipart/form-data"`` clause in form tag declaration.

This is an example of correct form setup allowing file upload mechanisms:
::

	<form action="my_script.pyhp" method="post" enctype="multipart/form-data" >
	   <input type="text" name="text_field" value="Default text" />
	   <input type="file" name="file_field" />
	   <input type="submit" value="Send" />
	</form>


-----------------------------------------------
Second step: managing the just uploaded file(s)
-----------------------------------------------
Once you file (or files, if you specified multiple ``file`` input fields) has been uploaded, it will be saved by PyHP to the temporary upload folder specified by the configuration options (see ConfigurationOptions page for further details). This (or those) file(s) will be kept there for the entire execution of the target script: at the end of the script, it/they will be permanently removed for security reasons.

This means you'll have to manage the uploaded temporary files, checking them if necessary and then saving/copying them to a proper location. PyHP exposes uploaded files using the ``uploads`` object. Every item into the ``pyhp.uploads`` object is a ''File'' dictionary object, which it again contains three values:
 - ``filename`` a string containing the uploaded original file name
 - ``mime`` a string containing the MIME type of the file
 - ``file`` a ``File`` object referring to the actual file into the temporary folder

At this point, you could easily use Python file management tools, such as the ``shutil`` Python library. The easiest way is to iter into the ``pyhp.uploads`` collection, reading the ``filename`` and ``file`` fields and copying files with the ``shutil.copy()`` method. Let's give an example:
::

	<? pyhp
	import shutil

	for item in pyhp.uploads.itervalues():
	    shutil.copy(item['file'].name, "./my_subfolder/"+item['filename'])
	?>
	

This will copy every uploaded file into ``my_subfolder``. You can obviously check, read and manipulate those files using the ``shutil`` library and the ``shutil.os`` object. For more information about this Python features, see a more specific Python guide.

.. note:: 
	the initial file system path is set to the script file ./ point. The example above will gain access to files into the temporary folder through the file reference given by the ``file`` object into the ``pyhp.uploads['my_field_name']`` dictionary. The ''my_subfolder'' folder is instead accessed from ./ as stated by the path passed as second argument of the ``shutil.copy()`` method.

--------------------------------------------------------
Managing already saved files reading directories content
--------------------------------------------------------
Once having your file uploaded, you might want to manage them at a later moment. Since the ``pyhp.upload`` content and the files in the temporary folder exist only during the execution of the target script launched after the form submission, you'll have to use a proper organisation. Using the system file access as stated in the previous paragraph will allow you to use the same ``shutil`` library to browse your web application file system and manipulate files and data. If you prefer to use database BLOB storing, refer to the DatabaseInterface page. Note that it isn't recommended to store big files on databases.

This is an example reading the entire content of a ''images'' subfolder, printing every file in an ``IMG`` tag, like for a simple photo gallery:
::

	<?pyhp
	for entry in shutil.os.listdir('./images'):
	    print '<img src="images/'+entry+'" />'
	?>


You might also want to insert link to a binary downloadable file: you could easily do this using an anchor link as below:
{{{
<a href="my_file_path/my_file">Click here to download <em>my_file</em></a>
}}}




{{{
#!html
<hr/>
}}}
Go back to SessionManagement - 
Step forward to DatabaseInterface