TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/11.3/Feature-92518-IntroduceFileViewHelper.rst

@@ -0,0 +1,73 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-92518-1668719172:
+
+==========================================
+Feature: #92518 - Introduce FileViewHelper
+==========================================
+
+See :issue:`92518`
+
+Description
+===========
+
+With :doc:`#92518 <../11.3/Feature-92518-DownloadAndFilenameOptionsAddedToFileDumpController>`,
+the :php:`\TYPO3\CMS\Core\Controller\FileDumpController` has been extended with
+new options to force the download of a file, as well as the option to define a
+custom filename.
+
+To ease the use of the file dump functionality, especially the newly introduced
+options, a new ViewHelper :php:`TYPO3\CMS\Fluid\ViewHelpers\Link\FileViewHelper`
+is added, which allows extension authors to easily create links to both public
+and non-public files.
+
+The usage is as following:
+
+.. code-block:: html
+
+   <f:link.file file="{file}" download="true" filename="alternative-name.jpg">
+      Download file
+   </f:link.file>
+
+The above example will create a link to the given file, forcing a direct
+download, while using the alternative filename.
+
+In case the file is publicly accessible, a direct link will be used. Otherwise
+the file dump functionality comes into play.
+
+.. code-block:: html
+
+   <!-- Public file -->
+   <a href="https://example.com/fileadmin/path/to/file.jpg"
+      download="alternative-name.jpg"
+   >
+      Download file
+   </a>
+
+   <!-- Non-public file -->
+   <a href="https://example.com/index.php?eID=dumpFile&t=f&f=123&dl=1&fn=alternative-name.jpg&token=79bce812">
+      Download file
+   </a>
+
+.. note::
+
+   The :php:`file` argument accepts a
+   :php:`\TYPO3\CMS\Core\Resource\FileInterface`. So either a
+   :php:`\TYPO3\CMS\Core\Resource\File`,
+   a :php:`\TYPO3\CMS\Core\Resource\FileReference` or a
+   :php:`\TYPO3\CMS\Core\Resource\ProcessedFile` can be provided.
+
+.. note::
+
+   The :html:`filename` argument accepts an alternative filename. In case the
+   provided filename contains a file extension, this must be the same
+   as from the :html:`file` object. If file extensions is omitted, the original
+   file extension is automatically appended to the given filename.
+
+Impact
+======
+
+The new ViewHelper allows creating links to files - even non-public ones -
+in a straightforward way within Fluid templates.
+
+.. index:: FAL, Fluid, ext:fluid