1.. include:: ../../Includes.txt
2
3==========================================
4Feature: #92518 - Introduce FileViewHelper
5==========================================
6
7See :issue:`92518`
8
9Description
10===========
11
12With :doc:`#92518 <../11.3/Feature-92518-DownloadAndFilenameOptionsAddedToFileDumpController>`,
13the :php:`\TYPO3\CMS\Core\Controller\FileDumpController` has been extended with
14new options to force the download of a file, as well as the option to define a
15custom filename.
16
17To ease the use of the file dump functionality, especially the newly introduced
18options, a new ViewHelper :php:`TYPO3\CMS\Fluid\ViewHelpers\Link\FileViewHelper`
19is added, which allows extension authors to easily create links to both public
20and non-public files.
21
22The usage is as following:
23
24.. code-block:: html
25
26   <f:link.file file="{file}" download="true" filename="alternative-name.jpg">
27      Download file
28   </f:link.file>
29
30The above example will create a link to the given file, forcing a direct
31download, while using the alternative filename.
32
33In case the file is publicly accessible, a direct link will be used. Otherwise
34the file dump functionality comes into play.
35
36.. code-block:: html
37
38   <!-- Public file -->
39   <a href="https://example.com/fileadmin/path/to/file.jpg"
40      download="alternative-name.jpg"
41   >
42      Download file
43   </a>
44
45   <!-- Non-public file -->
46   <a href="https://example.com/index.php?eID=dumpFile&t=f&f=123&dl=1&fn=alternative-name.jpg&token=79bce812">
47      Download file
48   </a>
49
50.. note::
51
52   The :php:`file` argument accepts a
53   :php:`\TYPO3\CMS\Core\Resource\FileInterface`. So either a
54   :php:`\TYPO3\CMS\Core\Resource\File`,
55   a :php:`\TYPO3\CMS\Core\Resource\FileReference` or a
56   :php:`\TYPO3\CMS\Core\Resource\ProcessedFile` can be provided.
57
58.. note::
59
60   The :html:`filename` argument accepts an alternative filename. In case the
61   provided filename contains a file extension, this must be the same
62   as from the :html:`file` object. If file extensions is omitted, the original
63   file extension is automatically appended to the given filename.
64
65Impact
66======
67
68The new ViewHelper allows creating links to files - even non-public ones -
69in a straightforward way within Fluid templates.
70
71.. index:: FAL, Fluid, ext:fluid
72