This article only concerns dynamic files (images, medias, ...)

Contents files are the files indexed by database rows.
Static images must be called trough CSS only.

File field

Mimes & extensions

The mime type is contained in the header file. If a user change the extension, still the application recognize the file's original type.
BUT, the header can be corrupted for a malicious intention, so you must consider the mime check, only as an ergonomy feature only. Not a a security check.

Know issue : Mime detection is not working on your server:

Cook is trying various ways to read the mime type, but still it is possible that none of the proposed methods works.
Basicly, you can skip the mime detection if you face issues on your serveur, it is very common bug.

Field properties

You can add or remove files types.
Uncheck a type to forbid it.
Add a new entry with the [+] button
Until the line is not complete (green), the type is not valid.

Protected files

Using indirect mode, the full path is never revealed, so the user cannot know where the physical file is stored.
A content image can also contains access restrictions, in this way, the database is asked to retreive the image full path, including access control.

How it works ?

Instead of calling the image with its file name, it call the component engine :

index.php?option=com_mycomponent&task=file...&path=[DIR_MYALIASDIRECTORY]/myimage.png

Then the component analyse the query and return the file bit per bit with corresponding headers.
When your query handle options, the file can be resampled. Thumbs creation, for instance.

Directory aliases

Your component has registered a list of directory aliases, wich contain the full base paths.
Each different field will use a different alias, always in capitals letters.

Per default, the directory alias are constructed following this rule :

[DIR_TRIAD_FIELD]

TRIAD is the table alias (plural alias)
FIELD is the field name which stores the image.

Very important : This documentation expose the default name convention.
So, you should (must) change these directories in the component config if you want to really hide the paths.

Open the component configuration

Then choose a directory path.
Example : [COM_MEDIAS]/com_files/images

You can use predefined aliases :

[ROOT] : Joomla root
[COM_ADMIN] : Component admin root
[COM_SITE] : Component site root
[ADMIN] : Administrator root
[IMAGES] : Site images root
[MEDIAS] : Site media root

Aliased path

$path is an aliased string:

Alias directory + file relative directory + file name + extension

Example:

[DIR_FILES_IMAGE]/2014-03/myimage.png

Note : The relative directory can be created with the 'renaming' rules of your file at upload. (see uploader)

Building the url

Cook offer you the possibility to build the image link automatically from a static helper call.

Physical file (not URL)

Uses this method when you want to retreive the real file. This method should ony be used for PHP purposes.

Direct url : (unprotected)

This will return a direct file access, using URL.

Indirect url : (recommended)

Database index (secure)

Double protection:
In this case, you even do not send the image file name.
If a restriction applies on the item, the file will not return. (ex: publishing, authoring, accesslevel)

$view : (same than triad) : plural alias.
$key : table field name when filename is stored. 
$id : primary key of the item.

Thumbs, options, resampling

Some parameters can be sent to customize the image.

Using JDom for images

JDom can instance images in a very fast and reliable way.

The previous examples are given only to explain how to get only the URL of the image.
For rendering in HTML, the image need to be called from a HTML markup with its properties. Let's use JDom for it.

JDom is gonna call the previous functions and options automatically.

Here a basic example :