.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../../Includes.txt

File
^^^^

First, a quick explanation, what this abstraction layer is capable of doing:

- run through a specified directory
- get all files (no folders, no ., no ..)
- get meta information on the files

For the data columns to be specified, here is a list of available "columns" in this handler.

==================  =========== ==========================  =============
Name                Type        Description                 Example
==================  =========== ==========================  =============
file                string      filename (without folder)   my_file.txt
name                string      filename without extension  my_file
size                number/int  size in bytes               123510
extension           string      small-letter extension      txt
content             string      the whole content           ...
mime                string      mime type                   text/plain
tstamp_creation     number/int  Unix timestamp of creation  1383724742
tstamp_lastaccess   number/int  timestamp of last access    1383725011
tstamp_modified     number/int  timestamp of last change    1383734253
permissions         number/int  system-dep. permissions     *varies*
usergroup           number/int  system-dep. usergroup       *varies*
user                number/int  system-dependant user       *varies*
type                string      indicator of filetyp        textfile
inode               number/int  Unix-only ID of file        51348
is_writable         boolean     true if file is writable    false
==================  =========== ==========================  =============

bGetSubDirectoryViaParam
------------------------

Boolean. If set to true (default: false) the SQL Frontend checks whether it finds the parameter specified in aSubDirectoryParam in order to apply that as sub directory.

aSubDirectoryParam
------------------

This configuration array/string follows the same principle as dbal/aDefault (ref) but with only one parameter. So it could either be just a string value indicating the directory (this would, however, not make much sense as you could then just configure it normally via dbal/sTable) or (more meaningful) a configuration array with three options specified.

- **sSource** which defines the area where to get the value from
- **sField** indicates which value to take
- **sWrap** might change/adapt it a little

Example for receiving the folder to search for via GET/POST (e.g. from a Directory listing): ::

    'aSubDirectoryParam' => array(
        'sSource' => 'GP',
        'sField' => 'tx_mhomsqlio_pi1[dir]',
        'sWrap' => '|/'
    )

**Note:** The slash in the end of the sWrap option is not obligatory, it will otherwise be appended automatically.

**Caution:** In case the parameter contains a parent directory indicator (*../*) it won't be used in order to stick to the parent directory (which, by the way, cannot be set via parameters). Thus, it is highly recommended that you in fact use a meaningful parent directory rather than a door-opening */*.