[TASK] Update Filelist section (#577)

Releases: main, 13.4, 12.4

Co-authored-by: lina.wolf <[email protected]>

Documentation/Concepts/Backend/FileModule/Index.rst

@@ -1,70 +1,93 @@
 .. include:: /Includes.rst.txt
-.. index::
-   Modules; Filelist
-   Filelist
 .. _file-module:
 
 ===================
 The Filelist module
 ===================
 
-The **FILE > Filelist** module is where you can manage
-all the media associated with your TYPO3 web site.
+The :guilabel:`File > Filelist` module is where you can manage
+all the :ref:`media and downloads <media>` associated with your TYPO3 web site.
 
-.. index::
-   Files; Management
-   Directories; fileadmin
-.. _managing-files:
+The Editors Guide describes how to
+:ref:`manage media in the TYPO3 backend <t3editors:managing-files-in-typo>`.
 
-Managing files in the TYPO3 CMS
-===============================
+Do not store :ref:`assets <assets>` needed for your theme here. Store these in
+the folder :path:`Resources/Public` of your :ref:`site package <creating-a-site-package>`
+or another :ref:`extension <create-own-extension>`.
+leuchtfeuer/secure-downloads
 
-Files including documents and images are managed in the
-Filelist module. Similar to the **WEB > List** module,
-it displays a navigation tree, which corresponds to the file
-structure on the server, and a list of all files for the
-selected directory.
+.. _file-module-fileadmin:
 
-.. include:: /Images/AutomaticScreenshots/FilelistModule/FilelistModule.rst.txt
+Fileadmin - the default file storage
+====================================
 
-For admin users, the folder displayed by default is called
-"fileadmin/ (auto-generated)" and corresponds to the
-:file:`fileadmin/` folder located under the document root
-folder on your web server.
+By default all media managed via the Filelist module is stored in the folder
+:path:`public/fileadmin`.
 
-Using these files inside content elements to display them
-or link to them in your web site is covered in the
-:ref:`Editors Tutorial <t3editors:images>`.
+This folder is publicly accessible and it is possible for attackers to access
+any file herein when they have or guess the correct path.
 
-.. note::
+Third party extensions like :composer:`leuchtfeuer/secure-downloads` can help
+you if downloads should only be available to logged-in frontend users.
 
-   There are extensions which make it possible to connect to remote
-   storage pools (like a WebDAV server or an Amazon S3 account) and work
-   with the files as if they were on the TYPO3 CMS server.
+.. _file-module-storages:
 
+File storages
+=============
 
-.. index:: pair: Files; Clipboard
+It is possible to configure additional file storages, including private and
+read only ones. This topic is beyond the scope of this guide. It is explained in
+TYPO3 Explained, chapter :ref:`File storages <t3coreapi:fal-administration-storages>`.
 
-.. _file-module-clipboard:
+.. _file-module-fal:
 
-Clipboard
----------
+File abstraction layer (FAL)
+============================
 
-There's a clipboard just like in the *List* module.
+All media and download files managed in the Filelist module are managed via
+an abstraction layer. You can find the documentation of this layer in TYPO3
+Explained, chapter :ref:`File abstraction layer (FAL) <t3coreapi:fal_introduction>`.
 
-.. include:: /Images/AutomaticScreenshots/FilelistModule/FileClipboard.rst.txt
+On uploading, each file get a unique identifier assigned to
+it. This identifier is used to link to files and also to attach meta data to
+them.
 
-Using the action icons, files can be renamed or replaced
-(just hover over the icons and you will get a help text).
+This allows your editors to rename and move files without breaking the frontend.
+It also allows to test weather a file is still being used on deletion and to
+automatically delete unused media if desired.
 
+However you can only use the full power of the FAL if you do not link directly
+to files but only use the API to access them:
 
-.. index:: Files; Upload
-.. _uploading-files:
+In Fluid link files using the
+:ref:`Image ViewHelper <f:image> <t3viewhelper:typo3-fluid-image>` with property
+:typo3:viewhelper-argument:`image <t3viewhelper:typo3-cms-fluid-viewhelpers-imageviewhelper-image>`
+for images and the :ref:`Link.file ViewHelper <f:link.file> <t3viewhelper:typo3-fluid-link-file>`
+for download links.
 
-Uploading new files
--------------------
+In TypoScript the :ref:`typolink function with the file property <t3tsref:typolink-handler-file>`
+can be used to link downloads.
 
-You can upload files to a given folder by using the context menu
-or to the current directory by using the action icon in the docheader.
+For usage in PHP there is an API: :ref:`Working with files, folders and file
+references <t3coreapi:fal-using-fal-examples-file-folder>`
 
-.. include:: /Images/AutomaticScreenshots/FilelistModule/FileUpload.rst.txt
+..  note::
+    Never link to a file in the fileadmin from CSS or or JavaScript. Such files
+    like logos, icons, background images etc. should be stored as
+    :ref:`Assets in extensions and site packages <assets>`.
+
+.. _file-module-meta-data:
+
+File meta data
+==============
+
+A number of meta data fields for media uploaded in the Filelist module is
+available out-of-the-box. Additional meta data fields are available if the
+system extension :composer:`typo3/cms-filemetadata` is installed.
+
+For accessibility reasons images should always have an alt text defined.
+Editors can input an alt text either in the file metadata in the Filelist module
+or override it in the file relation when they use an image in a content element.
+
+By using the :ref:`Image ViewHelper <f:image> <t3viewhelper:typo3-fluid-image>`
+the alt text is automatically output unless you override it with property 'alt'.