Fileshelf (EN)

Download management for Joomla with a protected storage folder, counter, password protection and Smart Search · Version 1.10.1 · Stand 12.11.2026

Fileshelf at a glance
Requirements and installation
Storage folder and self-test
Creating and maintaining downloads
Categories
Password protection
Downloads on the website
Fitting your template
Shortcodes in articles
Editor button
The module
Search (Smart Search)
Media manager
Tools
Options and permissions
Action log
Free version and Pro version
Download statistics (Pro)
Versions and expiry date (Pro)
Links and download by e-mail (Pro)
Download limits (Pro)
Notifications (Pro)
Privacy (Pro)
Memberships with Membership Pro (Pro)
YOOtheme Pro (Pro)
JCE editor (Pro)
Download all (Pro)
Upload on the website (Pro)
Switching from other download extensions (Pro)
For developers: events
Changelog

Fileshelf at a glance

Fileshelf manages downloads in Joomla 6 with Joomla's own means: categories, tags, access levels, fields and versions come from the core, not from a system of its own. Each download has exactly one file, one main category and, if you like, further categories in which it appears as well.

The list of downloads in the backend with version, access level and counter — The list of downloads: title, categories, version, access level and how often each file was downloaded.

What Fileshelf does for you

Store files protected. The files lie in a storage folder of their own, which Fileshelf locks against direct access and checks itself. Visitors only get a file through Fileshelf – with access check and counter.
Control access. Joomla access levels, a password per download or per category, publishing period.
Show them on the website. Menu items for categories, single downloads and the latest downloads, a module, shortcodes for articles and a button in the editor.
Let them be found. The site search (Smart Search) finds downloads by title, description, file name and tag.
Maintain. Tools reorder files, adopt files uploaded by FTP and check file details.

The parts

Fileshelf is installed as one package. It contains:

Part	Task
Component Fileshelf	Downloads, storage, website views, tools
System - Fileshelf	Category password, protection against deleting categories in use
Content - Fileshelf	Shortcodes in articles and modules
Button - Fileshelf	The button “Download” in the editor
Smart Search - Fileshelf	Downloads in the site search
FileSystem - Fileshelf	The area “Downloads” in the media manager
Module Fileshelf - Downloads	Latest, most popular, featured downloads or those of a category

The plugins are enabled on the first installation. Always keep “System - Fileshelf” enabled; you can disable the others if you do not use their feature.

Requirements and installation

Requirements

Joomla 6
PHP 8.3 or newer
MySQL 8.0.13 or newer, or MariaDB 10.4 or newer

Installing

Download the package pkg_fileshelf-<version>.zip.
In the backend open System → Install Extensions and drop the ZIP file into the field.
After the installation Joomla shows an overview of the package with links to the dashboard. In the Free version it also carries a short note on the Pro version.

On installation Fileshelf creates the storage folder fileshelf/ in the Joomla folder and writes protection files into it. Then open Components → Fileshelf → Dashboard: it shows whether the folder is protected (see Storage folder and self-test).

The dashboard

Needs your attention – appears only when something is to do, highlighted right below the toolbar, with the number of matters and for each the way to mend it: for example a download without a file (“Assign a file”), a storage folder whose protection is not confirmed, the switched-off plugin “System – Fileshelf” (“Open plugin”) or plans that stay locked without Membership Pro.
Welcome line – in two sentences what Fileshelf is and does, with the installed version and this manual.
Figures – cards of the same height with a head: downloads (published and unpublished), categories, in the Pro version the hits (today, last 7 days, last 30 days and all time), and the storage folder. At the bottom of each card is the way on, such as “All downloads”.
Storage folder – where the folder is and what it is for: the files are kept here, and visitors get a file only through Fileshelf, with access, password and limits checked. With “Check now”, the settings and this guide. With nothing to do the card is called Status and says “Nothing to do”.
Quick access – the pages you need most often, as tiles; at the end import (in the Pro version) and tools. The options are at the top right of the toolbar.
Changed last and Most popular downloads – the five downloads edited last and next to them the five published ones fetched most often in total.
Fileshelf plugins – at the foot across the full width, in two columns: every installed plugin of the package with “on” or “off” and the link to its settings, plus the number of modules on the website.
In the Free version a box at the top names the Pro version, and the row “In the Pro version” explains its features, each on a page of its own.

Every page of Fileshelf has the button Help at the top right: it opens this manual. All pages, including those of the Pro version, are also in the menu under Components → Fileshelf.

Updates

New versions appear under System → Update → Extensions. An update keeps your downloads, files and settings; it works from any earlier version.

Uninstalling

When you uninstall the package, Joomla removes the tables of Fileshelf. The storage folder with your files stays – delete it by hand if you no longer need it.

Storage folder and self-test

All files lie in a storage folder. No download is handed out through the address of its file, but always through Fileshelf: Fileshelf first checks whether the visitor may get the file, then counts the download and sends the file. So that this cannot be bypassed, the folder must be locked against direct access.

The self-test

The dashboard checks the folder itself: Fileshelf places a test file and tries to fetch it through its address. It tests again after a day or when the folder changes; with “Allow software packages” on, every page of Fileshelf in the backend makes up for a missing test. The result comes in three colours:

Result	Meaning
Green	Protected: the files cannot be reached by their address, or the folder lies outside the web directory.
Red	Not protected: files can be downloaded past protection and counter. The dashboard shows how to close the folder.
Yellow	Not testable: the website did not answer the test request. Check again later.

Check now repeats the test, for example after you changed the server configuration.

Apache

Fileshelf places an .htaccess file into the folder. If the test stays red, your server does not allow .htaccess files. Ask your host to allow AllowOverride for this folder.

nginx

nginx does not read .htaccess files. Add the rule the dashboard shows to the server configuration (through your host if need be). For the default folder it reads:

location ^~ /fileshelf/ { deny all; }

Outside the web directory

Safest is a folder that has no address at all. Enter an absolute path outside the web directory under Options → Storage → Storage folder, for example /home/customer/fileshelf. Existing files are not moved when you change it – copy them into the new folder yourself.

Delivery by the web server

Under Options → Storage → Delivery you can let the web server send the file instead of PHP: X-Sendfile (Apache with mod_xsendfile) or X-Accel-Redirect (nginx with an internal address). Only choose this if your host has set it up; when in doubt, keep PHP. Protection and counter apply in all three cases.

Creating and maintaining downloads

A download is an entry with exactly one file. You create it under Components → Fileshelf → Downloads → New.

The form of a download: the file at the top, the description below, status, category and additional categories on the right — The tab “File and description”: the file at the top, the description below, status, category, additional categories and tags on the right.

The form has at most seven tabs: File and description, Access, in the Pro version Sharing, Versions and Statistics, plus Publishing and Permissions. Custom fields get a tab of their own, as with articles.

Tab “File and description”

Category – the main category. It decides the address of the download, its inherited permissions and the folder its file lies in.
Additional categories – the download also appears in the lists of these categories. Address and inherited settings still come from the main category.
Description – appears on the page of the download. It is edited with the same editor as an article, with images, media and the editor buttons; content plugins work in it as in articles. If the field shows only an empty frame, the editor is the cause: check the editor under Users → your profile → “Basic Settings” and, with JCE, whether an editor profile is published and applies to your user group.
Tags and fields as with articles.

The file

The section File with the current file, the field to replace it and the choice of free files — Upload, or choose an existing file from the storage folder; below it the facts about the file.

Upload a file – the file is stored in the folder of the main category when you save.
Or choose a file from the storage folder – lists files that do not belong to a download yet, such as ones copied there by FTP. Fileshelf reads the folder only when you click Show free files in the storage folder; the list shows up to 200 files.
If the same file already belongs to another download, Fileshelf shows a note.
Version – under “About the file”, free text such as 2.1. Visitors see it in the lists. In the Pro version the facts about the file stand at the top of the tab “Versions”.
License – appears there once an import from another download extension has created the field (Pro version). On the website it carries the label “License” in the visitor's language.

Allowed are the file types from Options → Storage → Allowed file types. Programs and web pages (for example php, svg, html) are never accepted, not even in names like report.php.pdf. Fileshelf also checks whether the content matches the extension, and Joomla checks the file as well.

Extensions and other software packages

A ZIP with an extension for Joomla, Shopware or WordPress contains PHP files. Joomla refuses such archives on upload, and Fileshelf then says what to do. To offer extensions, switch on Options → Storage → Allow software packages. Fileshelf then accepts zip, tar, gz and tgz archives with program code:

only on upload in the backend (form, multiple upload, import), never from the website;
only while the self test reports the storage folder as protected – otherwise Fileshelf refuses the package with a hint to the self test;
never with a forbidden part in the name such as package.php.zip.

For tar.gz and tgz also add gz and tgz to the allowed file types. Programs such as .exe or .msi stay blocked. Visitors always get a package as a file to save; the checksum on the page of the download helps them verify it.

Tab “Access”

Here you set a password for this one download (see Password protection). In the Pro version you also bind the download to plans of Membership Pro there.

Tab “Sharing” (Pro version)

One-time and time-limited links (see Links) and the notifications (see Notifications).

Tab “Publishing”

Status, access level, language, start and end of publishing, author and counter. An unpublished or expired download does not exist for visitors – not even through an old link.

On saving, Fileshelf checks the permissions, whichever way the download comes (form, several files, upload from the website): only who may change the state in the category can publish – otherwise a new download stays unpublished. Only one's own access levels can be chosen, and an additional category only where one may create downloads.

The list

For every download the list shows the main category, the file with type and size, version, access level and counter. A download without a file is marked red. Above the list are quick filters with their numbers: All, Published, Unpublished and – if there are any – Without file. The filter options also filter by status, featured, file, category (main or additional) and level, access level, author, language and tag.

Download in the backend – the file name in the column “File” fetches the file without counting it. The user needs the permission “Download in the backend” for it.
Batch processing – set access level, language and tags, add or remove additional categories, move to another main category. Copying is not offered, because a file belongs to one download only.

Password protection

In addition to access levels, a password can protect a download. The visitor enters it once and then downloads without needing a user account.

Password for one download

The tab Access of a download with password field and status — The tab “Access” only shows whether a password is set – never the password itself.

Enter a password in the tab Access and save.
Leaving it empty keeps the current password.
Remove the password lifts the protection.

Password for a category

The tab Fileshelf in the category form with the category password — A category password protects every download of the category and its subcategories.

A category password applies to every download of the category and its subcategories that has no password of its own. Whoever entered it once can fetch all these downloads.

What the visitor sees

The form to unlock a protected download on the website — The form appears when a visitor opens a protected download.

Lists show a lock with the link Enter password instead of the button.
After the right password the download starts at once.
For the time in Options → Downloads → Password valid for (minutes) Fileshelf does not ask again (default 120 minutes; 0 until the browser session ends).
After five wrong attempts the visitor has to wait briefly; the wait grows with every further wrong attempt, up to one minute. If a captcha is set up in Joomla, it is added from the tenth wrong attempt on.
Fileshelf counts wrong attempts on the server, per password and visitor. A new browser window or deleted cookies do not reset the count. The visitor's address is stored for this only encrypted and deleted after a day.
If 100 wrong attempts come together for one password within an hour, from whoever, Fileshelf locks it for everyone for 15 minutes. This slows down attacks from many addresses; afterwards it works as usual.

Fileshelf stores passwords only encrypted (as a hash). They appear neither in the form nor in the version history nor in an address. Simply set a forgotten password anew.

Downloads on the website

Type	Shows	Important settings
Categories	The categories below the chosen root as tiles or as a compact list, with image, description, number of downloads and subcategories	Root category, layout, top level category description, category image, description, show number, levels (1 = without subcategories)
Category	The downloads of a category and its subcategories	Layout, ordering, number per page, category image and its layout, details (size, version, date, counter, tags), show locked downloads
Single download	The page of a download	Send the file directly instead of showing the page
Latest downloads	The most recently created downloads	Number, categories, period in days

Above the tiles stand title, description and image of the chosen root category (switched off in the menu item under “Top Level Category Description” and “Category Image”). Every tile has an image area in the format 16 : 9; the image is fitted, never cropped, so logos stay whole.

Category image and description

At the top of every category stand its title, description and the image from the field “Image” of the category. The image stands beside the text, at most 220 × 160 pixels and never cropped; on narrow screens it stands above. If you like, it appears as a banner across the full width in the format 3 : 1 – good for photos, but cropped. You choose both in the options or per menu item (“Category Image”, “Category image layout”). The alternative text comes from the image field of the category; with “No Description” ticked there, the image counts as decoration.

Headings

Every page has exactly one main heading (h1). In a category it is its title – or the page heading of the menu item when “Show Page Heading” is on and the menu item shows this very category. Below it the small sections Subcategories and Downloads structure the page (h2), the downloads in them are h3. Pages without a title of their own, such as “Latest downloads”, keep their main heading with the page heading switched off – then for screen readers only. This helps screen readers and search engines.

Heading and introduction of the overview

Above the categories of the download overview a heading and an introduction of your own can stand. Enter both in the Fileshelf options (tab “Display”) for every overview, or in the menu item of the overview for that one only; an empty field in the menu item takes the value from the options. A heading entered there is the main heading of the page and is always shown, even with “Show Page Heading” off. Without one, the rules above apply.

Browser page title

The “Browser Page Title” of a menu item (tab “Page Display”) applies to the page the menu item shows: the overview, the category, the download or “Latest downloads”. Pages below it, such as a subcategory, carry their own title. The site name is added if Joomla's global configuration says so.

Three layouts of a category

Each layout leads through the categories in its own way. You choose it in the menu item, in the category (tab “Fileshelf: Display”) or for all in the options.

List with category tree (default) – on the left the tree of the categories below the menu item, with the number of downloads; it opens only along the way to the category shown. On a phone it stands below the list.
Cards – above the downloads the way back to the parent category and the subcategories (without subcategories the categories of the same level); the downloads as cards.
Table – “Change category” as a choice, the subcategories to click, the downloads as a table whose column headers sort. On narrow screens every row becomes a block with labelled values.

In every layout the file type stands as a coloured label (“PDF”, “ZIP” …); the colour helps to scan, the word names the type.

Without a page per download

Every download has a page of its own with description and details. To list downloads with a direct link only, set A page per download to “No” in the options (tab “Display”) or in the menu item. Then:

The title leads straight to the file, with the same checks as the button “Download”, which stays. If a download needs a password or a login, the note beside it shows the way.
Old addresses of the page lead permanently (301) to the file. A menu item “Single download” for exactly this download keeps showing its page.
The module, the shortcodes, YOOtheme, the search, the mails of notifications and the editor dialog then link the file as well.
What is only on the page is missing on the website: “Notify me” and the earlier versions (Pro version). The form and unlocking of a link (Pro version) are reached through the note.

Above the list visitors can search (title and file name), sort and – with several file types – filter by type. The choice is part of the address, so a filtered link can be passed on. Switch it off with Search and sorting in the menu item or in the options. Joomla's breadcrumbs show the way from the menu item to the category or the download.

Fileshelf takes the look of buttons, fields and tables from the template: every button carries the classes of Bootstrap (Cassiopeia and many other templates) and of UIkit (YOOtheme Pro) at once. For more, create overrides for com_fileshelf/category and the layout fileshelf/item.

A category as a list with the category tree on the left, search and sorting above the list — Layout “List with category tree” (default): the tree on the left, search and sorting above the list.

A category as a table with “Change category” and sortable columns — Layout “Table”: “Change category” at the top, the column headers sort.

A category in the layout cards — Layout “Cards”: the way back and the subcategories at the top.

Locked downloads

Downloads whose access level the visitor lacks are hidden. With Show locked downloads (options or menu item) they appear with a lock and a link to log in. Password-protected downloads always stand in the list, with the link Enter password.

The page of a download

The download box names the file with type and size, carries the button Download (or the lock with its reason) and the details version, date and – if switched on – the number of downloads. On request it shows the checksum (SHA-256) to unfold, so visitors can verify a downloaded file; it is switched on in the options or in the menu item “Single download”. In a narrow area – on a phone or in a narrow column – the box stands above the description.

If a download appears in several categories, its page tells search engines that the address under the main category is the authoritative one (canonical). So it does not count twice.

Addresses

With search engine friendly URLs switched on, the addresses look like this:

Page of a download: …/price-lists/price-list-2026
File: …/price-lists/price-list-2026/file
Password form: …/price-lists/price-list-2026/unlock

The option Remove IDs from URLs (Options → Integration) decides whether the number of the download stands in the address. The alias of a download must be unique per category.

Fitting your template

Fileshelf follows your template instead of painting over it. Without any setting, lists, cards, tables and the page of a download take the type, colours, buttons and fields of the template – tested with Cassiopeia, YOOtheme Pro, Helix Ultimate and Astroid. This page shows how to adjust it further, from the colour picker to your own override.

Without code: the options

Under Options → Appearance you choose an accent colour and the corners, or you switch off the Fileshelf stylesheet (see Options and permissions).

With one line of CSS: the variables

Colours, lines and corners of Fileshelf hang on variables. Set them in the user.css of your template (Cassiopeia: the file media/templates/site/cassiopeia/css/user.css):

.com-fileshelf {
  --fsh-accent: #b8322b;   /* buttons and markers */
  --fsh-on-accent: #fff;   /* text on the accent colour */
  --fsh-border: #d0d4da;   /* lines and frames */
  --fsh-radius: 0;         /* corners */
  --fsh-gap: 1.5rem;       /* space between entries */
}

Without values of your own, Fileshelf takes the colours of the template: with Cassiopeia its primary and border colour, with Bootstrap templates (Helix Ultimate, Astroid, T4) the Bootstrap variables, otherwise it derives lines from the text colour. That is why Fileshelf stays readable on dark sections as well.

Your own rules always win

The look of Fileshelf (colours, frames, buttons, fields) stands in a CSS layer of its own (@layer fileshelf). Every rule of your template or your user.css takes precedence – without !important. Only the arrangement (grids, spacing) and the choice under “Appearance” stand outside.

Narrow columns

Lists, cards and the page of a download follow the width of the area they stand in – not the width of the screen. In a sidebar the list becomes compact and the button shows only a symbol; screen readers still read its name.

Classes of buttons and fields

Buttons, fields and tables carry the classes of Bootstrap 5 and UIkit 3 at once – each framework takes its own. If your template uses another one, create the file templates/<your-template>/html/com_fileshelf/ui.json and name the classes of your framework per building block:

{
  "button": "button is-primary",
  "button-secondary": "button",
  "input": "input",
  "select": "select",
  "table": "table is-striped"
}

Building blocks: button, button-secondary, button-link, button-small, input, textarea, select, label, field, table, card, section (the small section headings). Fileshelf's own classes (com-fileshelf-…) always stay. With a child template, its file applies before the parent's.

Replacing the stylesheet

A template can replace the Fileshelf stylesheet with its own: an entry named com_fileshelf.site in its joomla.asset.json. Or switch it off under Options → Appearance.

Overrides

All views and building blocks can be overridden the usual Joomla way, under System → Site Templates → your template → Create Overrides → Components → com_fileshelf or Layouts → com_fileshelf. The most important layouts:

fileshelf/item – one entry in lists, cards, module and shortcodes;
fileshelf/file – the download box on the page of a download;
fileshelf/lock – the lock with its reason;
fileshelf/items – the list around the entries;
fileshelf/categoryhead – title, image and description at the top of category and overview.

Since 1.9.0: a category has the sections “Subcategories” and “Downloads”, the downloads in them are h3, and the head comes from the layout fileshelf/categoryhead (the former fileshelf/categoryicon is gone). If you overrode category/default_head.php, category/default_filter.php, category/default_cards.php, category/default_table.php or category/default_entries_*.php, take these changes into your override, else sections or the image are missing there.

Shortcodes in articles

With shortcodes you place downloads in articles, modules and every other text that runs through the content plugins. The easiest way is the button Download in the editor (see Editor button); you can also write them by hand.

An article with link, button, counter and list from shortcodes and the module — An article with every kind of shortcode and, below, the module.

The forms

Shortcode	Result
`{fileshelf id=12}`	Link with the title of the download
`{fileshelf id=12 text="Get the form"}`	Link with your own text
`{fileshelf id=12 button}`	Button
`{fileshelf id=12 button class="uk-button uk-button-primary"}`	Button with your own CSS classes
`{fileshelf id=12 count}`	Only the number of times the download was fetched
`{fileshelf cat=3}`	List of the downloads of a category (main or additional)
`{fileshelf cat=3 layout=cards limit=5 order=popular}`	Cards, at most 5, most popular first

{fsh …} is the short form of {fileshelf …}. order knows title (default), rtitle, newest, oldest, popular and ordering; limit goes up to 100.

What visitors see

If the visitor may fetch the download, the link or button appears.
If it is protected, the title and a lock with the link Enter password or Log in appear.
An unknown, unpublished or expired download does not appear at all. In Joomla's debug mode an HTML comment with the reason stands in its place.

A list that stands alone in a paragraph replaces the paragraph. So write {fileshelf cat=…} on a line of its own.

Editor button

Below the editor, or in TinyMCE's menu CMS Content, you find the button Download. It opens a selection dialog and inserts the matching shortcode.

The selection dialog of the button Download with the choice link, button or number — At the top you choose the form, below it the download. In the tab “Categories” you insert a whole category as a list.

Place the cursor where you want the download and click Download.
Choose under Insert as: link, button or number of downloads.
Click the download. Search, filters and ordering work as in the list.
For a list, open the tab Categories and click the category.

TinyMCE's link dialog

The downloads are also offered as a source in TinyMCE's link dialog. So you link selected text directly to the page of a download.

Who sees the button

The button appears in the backend for users with the permission “Access Administration Interface” on Fileshelf. It is not offered in the frontend editor.

The module

The module Fileshelf - Downloads shows downloads in a module position. Create it under Content → Site Modules → New → Fileshelf - Downloads.

Settings

Setting	Meaning
Show	Latest downloads, Most downloaded, Downloads of a category or Featured downloads
Categories	Only downloads of these categories (main or additional). Required for “Downloads of a category”, optional otherwise.
Number of Downloads	At most this many entries (up to 100)
Display	List or cards
Title Heading	Heading level of the download titles, one below the module title
File Type and Size, Date, Downloads Count	Show, hide or as in the Fileshelf options

The module uses the same access check as the category view: locked downloads appear with a lock. It uses Joomla's module cache; the cache distinguishes access levels, language and unlocked passwords, so that nobody gets another visitor's view.

Search (Smart Search)

The plugin Smart Search - Fileshelf adds downloads to the site search (Smart Search). It finds title, description, file name – including its parts, so price-list-2026.pdf is found under “price” –, version and tags.

The result of a search for price list with the matching download — The search finds the download by title, file name or tag.

Setting up

Check that the plugins Smart Search - Fileshelf and Content - Smart Search are enabled.
Open Components → Smart Search and click Index once, so that existing downloads are added.

From then on Fileshelf keeps the index up to date itself: when a download is saved, published, unpublished or deleted, and when the access level or status of a category changes.

Who finds what

The search only shows a visitor downloads whose access level – and that of the main category – they have. Password-protected downloads are found; the file still comes only after the password.

Type, category (additional ones included), author, tag and language are available as search filters.

Media manager

The plugin FileSystem - Fileshelf shows the storage folder in the media manager as the area Downloads. So you see folders and files, upload files and create folders without FTP.

What differs from normal folders

Address: a file a download uses has the address of the download – not that of the file. Whoever inserts it links through Fileshelf, with protection and counter. Files without a download have no address.
Uploading: the same checks as in the download form apply.
Protection: a file a download uses cannot be deleted, moved or overwritten here – nor can a folder holding such files. Change or delete the download first.
Visible is the area only to users who may manage Fileshelf.
Content and address of a file (preview, download in the media manager) only come with the permission Download in the backend – as for the button in the download form. Who may only manage Fileshelf sees the file names, but not their content.

Limit

The media manager only shows file types allowed in its own options (Media → Options). If extensions such as zip or docx are missing there, such files do not appear in the area although Fileshelf manages them. Add the extensions there if you want to see them in the media manager. New downloads are best created in the download form; files uploaded through the media manager can be chosen there under Or choose a file from the storage folder or adopted with the tools.

Tools

You reach the tools from the dashboard or the menu Components → Fileshelf → Tools. They are only available to users with the permission “Configure ACL & Options” on Fileshelf (Super Users and administrators with this permission).

The page has three groups: Storage folder and files, Try it out (the demo data) and Cannot be undone (reset counters, remove demo data). Each tool shows beforehand what it would do. It only runs once you tick the confirmation box and click the button; for the demo data and the counters both stand in a dialog that names the consequences.

What is wrong in the storage folder (misplaced or unlinked files) Fileshelf looks for only when you click Check the storage folder now under Check the storage folder at the top – one run for both tools, with many files that takes a moment. One run moves up to 300 files; the message says how many are left.

Tool	When you need it
Demo data	You want to see what Fileshelf looks like on your website before you create downloads of your own. “Create demo data” creates six categories (one with the password `demo`), twelve downloads with small sample files, two tags and, in the main menu, the menu item “Fileshelf demo” with one sub item each for the layouts list, cards and table, a single download and the latest downloads. “Remove demo data” removes exactly that again, files included. Whatever you changed since, or downloads of your own in a demo category, stay; the preview names them. The password `demo` is known – remove the demo data before the website goes public.
Reorder files	A file stays in its folder when its download gets another main category. The tool moves it into the folder of the main category; the links stay the same.
Adopt unlinked files	You copied files into the storage folder by FTP or the media manager. Choose files and category; each file becomes an unpublished download with the file name as title. Files that do not pass the upload checks are left alone.
Check file details	You replaced a file by FTP. The tool reads each file again and stores size, type and checksum; it names missing files. It works in steps of 300 files; after each step Continue checking goes on.
Reset download counters	Sets the counters of all downloads, or of those of one main category, to 0. This cannot be undone.

Options and permissions

You reach the options with the button Options on the dashboard and in the list of downloads.

Storage

Option	Default	Meaning
Storage folder	`fileshelf`	Relative to the Joomla folder or an absolute path. Safest outside the web directory.
Allowed file types	pdf, zip, docx, xlsx, pptx, jpg, jpeg, png, mp3, mp4	Extensions, separated by commas. Programs and web pages are never accepted.
Allow software packages	No	Accepts archives with program code, such as extensions for Joomla, Shopware or WordPress (see Creating and maintaining downloads). In the backend only, and only with a protected storage folder.
Maximum file size (MB)	100	0: no limit of its own. The server's limit always applies.
Delivery	PHP	PHP, X-Sendfile or X-Accel-Redirect (see Storage folder and self-test)

Downloads

Option	Default	Meaning
Access through additional categories	Main category only	“Strictest”: the access levels of the additional categories must allow it as well.
Password valid for (minutes)	120	0: until the browser session ends.
Versions	Yes, 10	Version history of the downloads as with articles.

Display

Layout (list with category tree, cards, table), search and sorting, and which details the lists show: file type and size, version, date, number of downloads, tags – and whether locked downloads appear with a lock. Menu items and the module can choose each detail differently. Checksum shows the SHA-256 checksum of the file on the page of a download (default: off). Category Image shows the category's image at the top of the category and in the overview (default: on); Category image layout puts it beside the text (default, never cropped) or as a banner across the full width. Heading of the overview and Introduction of the overview stand above the categories of the download overview; a menu item can override both (see Downloads on the website).

Appearance

How Fileshelf fits into your template (see Fitting your template). Left empty, the colours and corners of the template apply.

Load the Fileshelf stylesheet – “No” for templates that style Fileshelf themselves. Then the arrangement of grids and spacing is missing too.
Accent colour – for buttons, markers and, if it reads well on white, links. Fileshelf picks light or dark text on buttons itself.
Corners – as the template, square or rounded.

Integration

Remove IDs from URLs (default: yes) and Enable custom fields as with articles.

Permissions

Permissions follow the pattern of articles and are inherited from the component through the category to the download: create, edit, edit own, edit state, delete. In addition:

Download in the backend – allows fetching a file in the backend without it being counted.
View statistics – shows the download statistics of the Pro version (page, tab, tile). In the Free version it has no effect; it is there so the setting survives a switch.
Upload on the website – allows uploading files into the category through the page “Upload a file” of the Pro version; they wait for approval. This permission is in the Free version, too.

Who may download on the website is decided by access levels (and a password, if any), not by permissions. The tools require the permission “Configure ACL & Options”.

Action log

Fileshelf writes to Joomla's action log. Under Users → User Actions Log you see who created, changed, published or deleted which download and when, and who set or removed a password. The filter Fileshelf hides everything else.

User Actions Log filtered to Fileshelf, with entries about downloads and an import — Entries of Fileshelf in the User Actions Log.

What is logged

Creating, changing, publishing, unpublishing, trashing and deleting downloads – each with a link to the download.
A password set or removed on a download or a download category. The password itself never appears in the log.
Categories of Fileshelf are logged by Joomla itself, like all categories.
In the Pro version also: uploads from the website approved or rejected, and every finished import.

Switching it on and off

On its first installation Fileshelf adds itself under Users → User Actions Log → Options → Extensions to log. If you take Fileshelf out there, it writes nothing more to the log; a later update does not change this setting. How long entries are kept is set in Joomla's plugin System - User Actions Log.

Free version and Pro version

Fileshelf comes as a Free version and a Pro version. The Free version is a complete product: everything this handbook describes without the note “(Pro)” belongs to it. The Pro version contains the whole Free version and adds plugins of its own.

What the Pro version adds

Download statistics per day and per download, without storing IP addresses, with export.
Versions and expiry date: earlier files stay available, downloads can expire.
Links and download by e-mail: once and expiring links, downloads after a confirmed address.
Download limits per user group, category or download.
Notifications: subscriptions to new versions, reports about downloads.
Privacy: access and erasure through Joomla's privacy requests, retention periods.
Memberships with Membership Pro: bind downloads and categories to plans, “My downloads”, welcome mail.
YOOtheme Pro: dynamic content and an element for download lists.
JCE editor: downloads in the link dialog, shortcodes through a tab.
Download all: all downloads of a category as one ZIP archive.
Upload on the website: uploads by visitors with checking and approval.
Import: switching from Phoca Download, jDownloads, Dropfiles and the plan documents of Membership Pro with preview, report, redirects and new shortcodes.

Each feature has a page of its own in this manual with “(Pro)” in its title. The Pro version creates three scheduled tasks during installation (retention, notifications, deletion periods).

Which version is installed?

From the Free to the Pro version

Download the package of the Pro version.
Install it under System → Install Extensions – simply over the existing Free version. Downloads, files and settings stay.
Enter your download key under System → Update Sites or at the extension, so that updates of the Pro version arrive.

The Pro version has no licence switch: what is installed keeps running – also after the membership ends. The download key only controls the updates.

Back to the Free version

Install the package of the Free version over the Pro version. The plugins of the Pro version stay installed (Joomla removes no parts on a package update); uninstall them under System → Manage Extensions if you like.

Download statistics (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

The Pro version does not only count how often a file was fetched, it records every download: when, which file, whether it arrived complete. That is what the statistics are made of – without storing any IP address.

The page “Statistics”

The statistics page with period, totals, a bar chart per day and the most downloaded downloads — Downloads per day, dark the completed ones, light the interrupted ones.

Period: the last 30, 90 or 365 days – a click on the button shows it at once.
Totals: downloads, how many completed, and the share not completed – for example because someone interrupted the download.
Chart: one bar per day. The same numbers are under Show the numbers per day as a table – for screen readers and for copying.
The top 20 downloads of the period, with a link to each.
CSV export of the chosen period: per day and download the number of downloads and of completed ones. The export contains no users and no addresses.

In the download and on the dashboard

Every download has the tab Statistics with its last 30 days. The dashboard shows the figure Hits in four fields: today, last 7 days, last 30 days and all time. “All time” is the sum of the counters of all downloads, the same number as in “Most popular downloads”, imported counts included. “Open statistics” at the foot of the card leads here.

The Statistics tab of a download with totals and the chart of the last 30 days — The tab “Statistics” of a download.

What is counted

Every download on the website, the preview included. When a program fetches the file in parts – a browser resumes an interrupted download or a download manager fetches several pieces at once –, it counts once, with the part that holds the end of the file, or as soon as the parts together make up the whole file.
Completed means: the whole file arrived.
Downloads in the backend are not counted.

Privacy and retention

Fileshelf stores no IP address. Instead there is a value computed from the address and a key of the day; the key is deleted the next day. Downloads of one day can be related to each other (for limits), but never to an address again. For logged-in visitors the user is stored.

Every night the scheduled task Fileshelf - Retention of the download log adds up the downloads of the day before per day and download. The statistics read these daily numbers and compute only today from the single entries – so they stay fast even with millions of downloads. If the task did not run once, the statistics compute the missing days from the entries; they are just slower then.

Fileshelf keeps single downloads for 365 days; then the task deletes the single entries in small batches, and the statistics keep counting them through the daily numbers. Change the period in the task under System → Scheduled Tasks. When a download is deleted, its entries go with it.

Who sees the statistics

The permission View statistics in the options of Fileshelf (tab Permissions). Super Users always have it.

Versions and expiry date (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

When you replace the file of a download, the earlier file stays as a version. Visitors find it on the download page, with what changed. A download can also get an expiry date.

Adding a new version

Open the download and upload the new file in the tab File and description (or choose one from the storage folder).
Enter the new version label in the tab Versions under “About the file”, e.g. 2026.2.
Write what is new under Changes in this version in the tab Versions.
Save.

The earlier file moves to a subfolder _versions of its category folder and keeps its label and its changes. Tools and media manager treat it as in use.

The Versions tab with changes, expiry date and the list of earlier versions with their status — The tab “Versions”: changes, expiry date and earlier versions.

Managing earlier versions

Each earlier version has a label, changes, a counter of its own and a status:

Active: listed on the download page and downloadable.
Archived: no longer listed; existing links keep working.
Locked: cannot be downloaded.

Whether visitors may download earlier versions at all is set in the plugin Fileshelf - Versions (Earlier versions public, default: yes).

On the website

Download page with the section Versions: what is new in this version and an earlier version with a link — Below the file: what is new, and the earlier versions.

Expiry date

Enter a moment under Expires on in the tab Versions. From then on the download stays visible on the website but shows a lock saying it has expired. In the backend you can still download the file. Clear the field and the download is available again.

Unlike Finish Publishing (tab Publishing): there the download disappears from the website altogether.

Links and download by e-mail (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

Two ways to hand out a file on purpose: links that work without login and password, and downloads by e-mail address, where visitors get the file only after confirming their address.

Creating a link

Open the download, tab Sharing, section Links.
Choose under New link: Once (valid for one complete download) or Valid until a date (7 days without a date, optionally with a maximum number of downloads).
Enter an address under Send to if you like – Fileshelf mails the link – and a note for yourself.
Save. The link appears once in the message at the top; copy it.

The section Links in the tab Sharing with the switch for downloads by e-mail address, the fields for a new link and the list of links — The section “Links” in the tab “Sharing”.

A link also works for downloads that only registered users see or that have a password. It works for this one download only. An interrupted download does not use it up. If a program fetches the file in parts (resumed download, download manager), that counts together as one download as soon as the whole file has arrived. Fileshelf stores only a fingerprint of the link – that is why it cannot be shown again later.

Revoking: tick the link in the list Links of this download and save. It stops working at once.

Download by e-mail address

Switch on Only for an e-mail address in the tab Sharing under Links. Then:

Visitors see a form instead of the button: e-mail address, name (optional) and consent to storing it.
They get a mail with a confirmation link, valid for 48 hours.
After confirming they get the download button. It works three times within 48 hours and only for this address. Opening the confirmation mail again gives the same link with the downloads left, not a new one.

The e-mail address replaces only this one hurdle. Everything else still applies: a download in a category for registered users stays reserved for them, a password has to be entered first, a membership plan or a download limit applies with the link, too. The form appears only if the visitor could reach the download without this hurdle.

Download page with the form: e-mail address, name, consent and the button Send link — The form on the download page.

In the plugin Fileshelf - Links you set: the validity in hours, the number of downloads per confirmation, the address of your privacy policy (linked in the consent) and the captcha. Without a choice of its own the captcha of the global configuration applies; if none is set there, Fileshelf picks an enabled captcha plugin on its first installation. An invisible field stops automated requests as well, the same address gets at most one mail for the same download every ten minutes, and the form accepts at most five requests per hour from one visitor.

The page “Links”

On the dashboard under Links: all links that still work and all confirmed addresses, with a CSV export. Because the page shows addresses, only Super Users and administrators with the permission “Configure ACL & Options” see it.

The Links page with the valid links and the confirmed addresses — Valid links and confirmed addresses.

Edit the texts of both mails under System → Mail Templates (extension Fileshelf - Links). How long addresses are kept is described under Privacy.

Download limits (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

Limits say how often visitors may download – for example ten downloads a day for registered users, or three a month for a particular file.

The Limits page with two limits and the forms for user group, category and single download — The page “Limits”.

Adding a limit

On the dashboard under Limits (Super Users and administrators with the permission “Configure ACL & Options” only). There are three kinds:

User group: counts all downloads of a user in this group.
Category: counts the downloads of this category – as main or additional category, without subcategories.
Single download: counts only this download (its ID is in the download list).

Each limit has the number allowed and the period: per day, per week (from Monday), per month or in total. Periods follow the calendar in the time zone of the site.

How limits combine

If someone belongs to several user groups, the most generous group limit of a period applies. So a group “Premium” gets more than “Registered”, although its members are registered as well.
Limits of a category or a download apply in addition; the strictest wins.
When a limit is reached, the list shows a lock with the moment downloading is possible again.
Visitors who are not logged in can only be counted per day, because Fileshelf stores no addresses. So only per day limits apply to them.
In total reaches as far back as the download log keeps single downloads (default 365 days).
Links from the tab Sharing (section Links) are not limited.

In the plugin Fileshelf - Limits you choose what counts: only completed downloads (default) or every started one.

Notifications (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

Two kinds of mail: visitors hear about new versions, and you hear how often a download was fetched. Fileshelf sends both in the background – never while someone waits for a page.

Subscribing to new versions

Logged-in visitors see Subscribe to new versions on the download page. When the download gets a new file, they receive a mail with the new version label and a link to the page. Every mail has an unsubscribe link that works without logging in. The number of subscribers is shown in the tab Sharing, section Notifications.

Download reports

The section Notifications in the tab Sharing with the switch, recipients and the number of subscribers — The section “Notifications” in the tab “Sharing”.

In the plugin Fileshelf - Notifications you set the throttle in hours and, optionally, an address that gets a report of all downloads.

Sending

The scheduled task Fileshelf - Send notifications sends what is due every 15 minutes. Fileshelf creates it during installation; you find it under System → Scheduled Tasks. The links in the mails never take the address of a request on the website – a visitor could forge it. They come from the global configuration (Live Site) or, if nothing is set there, from the address under which you last opened Fileshelf in the backend (Fileshelf notes it then, also when installing).

The scheduled tasks of Fileshelf: send notifications, retention of the download log, delete addresses after the retention — The three tasks of the Pro version.

Edit the texts of the mails under System → Mail Templates (extension Fileshelf - Notifications).

Privacy (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

The Pro version stores some personal data. This page says which, for how long, and how to answer requests for access and erasure.

What is stored

Data	What for	How long
Download log: time, download, completed, for logged-in visitors the user; instead of the IP address a value that can only be related within the same day	Statistics, limits	365 days as single entries, then only numbers per day without personal reference
E-mail address, name (optional), time of consent for downloads by e-mail	Confirming and sending the download	365 days (adjustable)
Links with an address	Sending, validity	up to 365 days after they expire
Subscriptions to new versions (user)	Notification	until unsubscribed

The scheduled task Fileshelf - Delete addresses after the retention deletes daily what is older than the retention, and everything that belongs to deleted user accounts. Set the retention in the task.

Access and erasure

Fileshelf takes part in Joomla's privacy requests (Users → Privacy → Requests):

Access contains download log and subscriptions of the user account, and requests, links and report recipients with the address – only the data of this person.
Erasure removes the user from the log (the statistics keep counting) and deletes subscriptions, requests, links with the address and the address in recipient lists.

For this the plugin Privacy - Fileshelf has to be enabled.

Text for your privacy policy

A suggestion to adapt to your site – not legal advice:

Downloads. When you download a file, we store the time, the file and – if you are logged in – your user account, to count downloads and to apply download limits where they exist. We do not store your IP address; we derive a value from it that cannot be related to any address once the day is over. We delete single entries after 365 days.

Downloads by e-mail address. For some downloads we ask for your e-mail address and, optionally, your name. We send you a confirmation link and store address, name and the time of your consent for 365 days. The legal basis is your consent, which you can withdraw at any time.

Notifications. If you subscribe to new versions, we send you a mail when a new version is published. You can unsubscribe with the link in every mail.

Memberships with Membership Pro (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

With Membership Pro you sell memberships; Fileshelf binds downloads and categories to their plans. Members with a matching active plan download, everyone else is shown the way there: to the login, the subscription or the renewal. The bridge is tested with Membership Pro 4.7.1.

Assigning plans

You choose the plans in the download (tab Access, section Plans) and in the category (tab Plans). One or more are possible. Which plans apply:

the plans of the download, if it has its own;
otherwise the plans of the main category – or of the nearest one above it, because a category also covers its subcategories;
otherwise the plans of the first additional category that has some.

Without plans a download needs no membership. With several plans one of them is enough; in the plugin Fileshelf - Membership Pro you can switch to “All plans are needed”.

The Plans tab of a download with the plan Premium selected — The plans of a download.

What visitors see

Guests see a lock with the name of the plan and go to the login.
Members without the plan go to the subscription of the plan in Membership Pro.
Members whose plan has run out go to the renewal.

A link of the Pro version (single-use or expiring link) opens a download without a plan, too – whoever hands out the link decides.

My downloads

Welcome mail

If you like, a member gets a mail as soon as their membership becomes active – with the downloads it opens and a link to “My downloads”. Switch on the Welcome mail in the plugin Fileshelf - Membership Pro. The mails are sent by the scheduled task Fileshelf - Send notifications; edit the text under System → Mail Templates.

When Membership Pro changes

When Membership Pro is installed, the dashboard of Fileshelf shows a tile Membership Pro as the last one of the quick access, with the version and the number of downloads and categories with plans. If its tables look different than expected after an update, downloads with plans stay locked – never open – and the tile names the reason. If Membership Pro is newer than the tested version, the tile says so; plans keep working.

When Membership Pro is not installed or switched off, there is no tile. If downloads or categories still have plans, they stay locked, and the dashboard reports it under Needs your attention with a link to the extensions. The form then shows the tab Plans only for entries that still have plans.

YOOtheme Pro (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

With YOOtheme Pro you design download areas in the page builder. Fileshelf brings dynamic content and an element of its own. Without YOOtheme Pro the plugin System - Fileshelf for YOOtheme Pro does nothing.

Dynamic content

Choose one of the sources of the group Fileshelf under Dynamic Content of an element:

Fileshelf download – one download you choose;
Fileshelf downloads – the downloads of one or more categories (also as additional category), featured only if you like, with order and quantity;
Fileshelf categories – the categories below a category, with the number of their downloads.

A download offers title, description, link to the download page, download link, file type and size, version, category, earlier versions and – for locked downloads – the lock text and the way past the lock (password, login, membership), among others. The download link is empty as long as the visitor may not load the file; bind the lock text to a field next to it. Access and lock reasons are the same as on the pages of Fileshelf.

The element “Fileshelf Downloads”

For a ready list, drag the element Fileshelf Downloads onto the page. It shows the downloads of categories, the featured, the newest or the most downloaded ones – as list, cards or table, with button or lock as on the pages of Fileshelf.

JCE editor (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

If you work with the JCE editor (2.9 or newer), pick downloads right in the link dialog. The plugin JCE - Fileshelf links adds Fileshelf to the dialog; the button Fileshelf below the editor (see Editor button) works in JCE as well.

Inserting a link

Select the spot or the word in the text, open the link dialog and expand Fileshelf in the tree. Below the categories you find the downloads; a click takes over the link. It always goes through Fileshelf – with counter and access check –, never straight to the file. You only see categories and downloads you may see yourself.

The JCE link dialog with the Fileshelf tree expanded and the price list selected — The Fileshelf tree in the link dialog.

Inserting a shortcode

Instead of a plain link, the tab Fileshelf inserts a shortcode: choose a download or a category in the tab Link, switch to the tab Fileshelf and choose the form – for a download link with file details, button or number of downloads, for a category list or cards. Insert puts the shortcode into the text; Fileshelf shows it with the current file, size and lock (see Shortcodes in articles).

The tab Fileshelf in the link dialog with the choice link with file details, button or number — The “Fileshelf” tab.

Download all (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

Above the list of a category with at least two downloads there is the button Download all (ZIP). It gives visitors all downloads of the category in one ZIP archive.

The category Forms with the button Download all (ZIP) above the list — The button above the list.

What goes into the archive

Every file is checked like a single download: access level, password, membership, limits. It is counted and kept in the statistics. What the visitor may not load is missing from the archive; the file README.txt in the archive names these downloads with the reason. If a limit applies, every file of the archive counts – so an archive cannot get round a limit.

Limits

In the plugin Fileshelf - Download all you set how many files (default 100) and how many megabytes (default 500) an archive holds at most; what no longer fits is named in the read-me. You can also hide the button there. The archive is built while it is sent and takes no space on the server.

Upload on the website (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

Logged-in visitors upload files on the website, for example dealers their documents. Every upload waits unpublished until you have checked and approved it.

Setting up

In the category (tab Permissions) or under Options → Permissions, give the right user groups the permission Upload on the website.
Create a menu item of the type Fileshelf → Extension page and choose the page Upload a file.

The form only offers categories the visitor may upload to. Whoever has the permission nowhere sees a note instead of the form; guests go to the login.

The form Upload a file with title, category, description and file — The form on the website.

What is checked

Every file runs through the same checks as in the backend: allowed file types, no executable content, Joomla's own checks. Images (JPG, PNG, GIF, WebP) are saved anew, so that nothing but the picture is kept. In the plugin Fileshelf - Upload on the website you set the largest file (default 20 MB) and the number of uploads per user and hour (default 5).

Checking and approving

Until it is approved, the file lies in the folder _quarantine of the storage folder; Fileshelf never delivers it from there, not even if someone publishes the download by hand. You find the waiting uploads on the dashboard under Approve uploads (permission “Edit State”). Whoever is denied this permission in a category does not see its uploads there and cannot approve them. The page shows type, size and folder of every file; you look at the file and decide:

Approve moves the file into the folder of its category and publishes the download.
Reject deletes download and file – only after ticking Delete.

When nothing waits, the page says whether uploading is set up at all and links what is missing: the menu item of the page “Upload a file” or a user group with the right “Upload on the website”.

The page Approve uploads with where files come from and wait, and what is still missing — The page “Approve uploads”: when nothing waits, it names what is still missing for uploads.

If you enter addresses under Tell about new uploads in the plugin, they get a mail about every new upload. The mails are sent by the scheduled task Fileshelf - Send notifications.

Many files at once in the backend

On the dashboard under Upload many files (permission “Create”) you choose many files at once or drop them onto the field. Every file becomes a download of its own with the common settings of the page: category, additional categories, status, access level and tags. Title and alias come from the file name (“Price_list_2026.pdf” becomes “Price list 2026”); if the alias already exists in the category, Fileshelf adds a number.

The files go to the server one after the other, so the size limit applies per file. Every file is checked as with a single upload. At the end every file shows whether its download was created (with a link) or why it was rejected; a rejected file leaves nothing behind. Without JavaScript the page sends all files at once and reports the result in one message.

The page Upload many files with the common settings and the result per file — “Upload many files”: the common settings on the left, the result per file on the right.

Switching from other download extensions (Pro)

Pro version. This feature is part of the Pro version of Fileshelf. What the Free version does is covered under Free version and Pro version.

The page Fileshelf → Import takes over categories, downloads, files and download counts from another download extension of the same site. The old extension stays as it is and keeps working: Fileshelf only reads, files are copied. Super Users see the page.

Source	What is taken over
Phoca Download 6	Categories with image, downloads, counts, version, tags, license
jDownloads 4	Categories, downloads, counts, version, tags, license, passwords; optionally the same file in several categories becomes one download
Dropfiles 6	Categories with image, files, counts, version, tags, several categories per file
Membership Pro	The documents of the plans, bound to their plans (see Memberships with Membership Pro)

If a source is not installed or its tables differ from the known version, the page says why and imports nothing.

How an import runs

Choose Preview and import for the source. The preview shows the category tree and the first downloads with what will happen to them – nothing has changed yet.
Choose where the categories go:
- New category "Import from …" (default): it keeps the import together and stays unpublished until you have checked it.
- Take the structure 1:1 (top level): the top categories of the source stand on the top level of Fileshelf, the tree stays as in the source. They start unpublished. If a category with the same address already exists there, the new one gets "-2" added.
- Under an existing category: the top categories of the source go under the chosen category.
Choose what is imported. At first everything is ticked. A category brings its subcategories and downloads; under Choose downloads one by one single downloads can be left out. If only a subcategory is chosen, its parent category comes along empty so the tree is right. A later import adds what is still missing and doubles nothing.
Leave Take over the download counts ticked if the counts should go on.
Start the import. It runs step by step; keep the page open until the report appears. You can cancel at any time; starting again continues.

Preview of the import from Phoca Download with category tree, first downloads and options — The preview before the import.

An import can be repeated: what was taken over is skipped; a taken-over download deleted since then comes back.

What is not taken over

Files Fileshelf does not accept: every file is checked like an upload (allowed file types, size, content). Refused files are listed with the reason in the report; adjust the options if needed and start the import again.
Files outside the site: links, files in a cloud (Google Drive, Dropbox, OneDrive). Fileshelf only delivers its own files.
Passwords stored only encrypted: such downloads and categories arrive unpublished; set a new password and publish them.
Single download records: only the count is taken over.

Access levels that do not exist on this site become "Special". License texts go into the field License, which the import creates once.

The report

The report says what was taken over and what was skipped, and leads through the next steps.

Report of the import with counts, aftercare and checklist — The report with aftercare and checklist.

Publish the import: the button publishes the category of the import and every category that is published in the source. It stays while one of these categories is still unpublished, so a publish that stopped can be finished.
Replace shortcodes: articles and custom modules with shortcodes of the old extension get those of Fileshelf. Articles keep the old text in their versions. What cannot be replaced is listed under "By hand".
Redirects: old addresses of downloads and categories lead to the new ones. An old download link gives the file at once, as the old extension did; access level, password and limits apply as for every download. This also works for menu items you have switched to Fileshelf, and after the old extension is uninstalled, as long as the plugin "Fileshelf - Import" stays switched on. In addition, Publish the import creates redirects in Joomla; the plugin "System - Redirect" must be switched on for them. If some are still missing, the overview of the import shows Open redirects with a button to create them.
Switch menu items: menu items of the old extension then show the matching page of Fileshelf.

Uninstall the old extension only after you have checked the report.

The import and its aftercare also change articles, modules and menu items. Fileshelf asks for the permission to configure Fileshelf for it (Super User or “Configure ACL & Options”), not the permissions of articles or menus – so give the import only to people who know the whole website. Category images are taken only as image files (jpg, png, gif, webp).

For developers: events

Fileshelf can be extended with plugins of your own – exactly the way the Pro version does it. Fileshelf loads all plugins of the group fileshelf before it fires its events. The classes are in Graup\Component\Fileshelf\Administrator\Event.

The events are Fileshelf's public interface. Their names, arguments and public methods only change with a new major version.

The events

Event	Class	When	What a plugin can do
`onFileshelfResolveToken`	`ResolveTokenEvent`	The request carries a token (`t`).	`grant()` skips access level and password, `reject()` locks with reason `token`.
`onFileshelfAccess`	`AccessEvent`	After status, token, access level and password; also in lists (context `list`).	`deny($reason, $message, $redirect)` locks. In lists, never count or write.
`onFileshelfBeforeSend`	`BeforeSendEvent`	Access granted, before counting.	`setFile()` swaps the file; Fileshelf checks it against the storage again.
`onFileshelfAfterCount`	`AfterCountEvent`	After counting, before the first byte.	Notification only; `getRequestId()` links it to the next event.
`onFileshelfAfterSend`	`AfterSendEvent`	After sending, also when the visitor broke off.	`isCompleted()`, `getBytesSent()`, `getMethod()`.
`onFileshelfDownloadDisplay`	`DownloadDisplayEvent`	Download page, per position.	`addHtml()` with finished, escaped HTML.
`onFileshelfDashboard`	`DashboardEvent`	Backend dashboard.	`addTile($id, $title, $html, $order, $area)` (`$area`: `status`, `content`, `insight` or `setup`); from 1.8.0 `addAttention($id, $text, $link, $count, $label)` for “Needs your attention”, only for a need for action with a way out; check your own right first.
`onFileshelfAdminPages`	`AdminPagesEvent`	Dashboard and every plugin page.	`addPage($name, $title, $right, $icon)` announces a page `view=page&page=…`; Fileshelf checks the right.
`onFileshelfAdminPage`	`AdminPageEvent`	The plugin page is shown.	`addHtml()`, `addAction($action, $label, $icon, $confirm)`.
`onFileshelfAdminAction`	`AdminActionEvent`	An action of the page runs; token, right and confirmation are checked.	`handled($message, $type)`.
`onFileshelfFilesInUse`	`FilesInUseEvent`	Tools, download form and media manager ask which files of the storage belong to plugins.	`claim($path)` for your own files (e.g. older versions); they never count as unlinked.
`onFileshelfSitePages`	`SitePagesEvent`	Menu item “Extension page” and every call of such a page.	`addPage($name, $title, $login)` announces a website page; with `$login` Fileshelf sends guests to the login.
`onFileshelfSitePage`	`SitePageEvent`	The page is shown.	`addHtml()` with escaped HTML, `setTitle()`, `getOptions()` (menu item).
`onFileshelfSiteAction`	`SiteActionEvent`	A form of the page was sent; token, page and login are checked.	`handled($message, $type, $redirect)`; Fileshelf escapes the message.
`onFileshelfCategoryDisplay`	`CategoryDisplayEvent`	Category page, positions `beforeList` and `afterList`.	`addHtml()` with escaped HTML; `getTotal()` gives the number of listed downloads.
`onFileshelfActionLog`	`ActionLogEvent`	Since 1.3.0: Fileshelf or a plugin reports an action for the action log (password, approval, import).	Message only: `getAction()`, `getKind()` (`download`, `category`, `import`), `getItemId()`, `getTitle()`, `getDetails()`. The plugin "Action Log - Fileshelf" writes it.
`onFileshelfImportSources`	`ImportSourcesEvent` (Pro)	Since 1.3.0: the page "Import" collects its sources.	`addSource()` with a class implementing `SourceInterface` of the import plugin (categories, downloads, table check).
`onFileshelfResolveScopes`	`ResolveScopesEvent`	Fired by the Pro version (limits) as soon as a limit uses a scope type of another plugin; the Free version does not fire it.	`addScope($type, $id)`.

The download comes as a read-only DownloadRecord (without the password hash), never as a table object. Reasons of your own start with x-<plugin>-; the website then shows only the message.

Example

final class Example extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onFileshelfAccess' => 'onAccess'];
    }

    public function onAccess(AccessEvent $event): void
    {
        if ($event->getContext() !== 'list' && !$this->allowed($event->getUser())) {
            $event->deny('x-example-hours', 'Downloads are possible on working days only.');
        }
    }
}

Plugins add form tabs to the download as with articles, with onContentPrepareForm (form com_fileshelf.download), and store them in onContentAfterSave (context com_fileshelf.download).

Pages on the website

With the menu item type Fileshelf → Extension page a plugin gets a page of its own on the website, without a component of its own. Forms of that page send task=extension.action, page, action and the form token to Route::_('index.php?option=com_fileshelf') – always build the address with Route::_(), a relative address is wrong under search engine friendly URLs. Plugins add tabs to the category form with onContentPrepareForm on the form com_categories.categorycom_fileshelf; Fileshelf loads the group fileshelf for it.

Changelog

This changelog lists every released version of Fileshelf, the most recent first.

This page is generated automatically from the product's changelog file when a release is made. Changes made by hand are lost at the next synchronisation.

Version 1.10.1 – 12 November 2026

Changed

The “Membership Pro” card now stands as the last tile of the quick access on the dashboard.

Fixed

With “Allow software packages” extensions are accepted again, also after the options were saved.

Version 1.10.0 – 12 November 2026

Added

Extensions for Joomla, Shopware and the like can be offered as downloads: switch on “Allow software packages” in the options. Programs such as .exe stay blocked.
Above the categories of the download overview you can now show a heading and an introduction of your own, set in the options and per menu item.

Changed

The dashboard is tidier: downloads show today, 7 days, 30 days and all time, the plugins stand at the foot in two columns.

Fixed

The browser page title of a menu item is now used, and the site name appears in the title if Joomla is set up that way.

Version 1.9.0 – 12 November 2026

Added

The dashboard shows “Needs your attention” only when something is to do, and highlights it. New: a welcome line, the most popular downloads and the state of the plugins.
The category image is no longer cropped: it stands beside title and description, or as a banner if you like. The overview of categories shows description and image of its category.

Changed

The website pages have a clean outline: one main heading, below it the sections “Subcategories” and “Downloads”. This helps screen readers and search engines.

Fixed

The dashboard opens quickly with MariaDB and many thousands of downloads as well.

Notes

If you changed the category view in your template (overrides), take over the new sections; the manual lists the files under “Fitting your template”.

Version 1.8.1 – 12 November 2026

Fixed

The lists “Latest downloads” and “Most downloaded” appear without delay even with many thousands of downloads.

Version 1.8.0 – 11 November 2026

Added

The import can take over the structure 1:1 on the top level, and single categories and downloads can be chosen before it starts.
New overview of categories as tiles or a compact list; the page of each download can be switched off, the title then leads straight to the file.
A clearer dashboard: cards with a head, the card “Storage folder” explains where and why, and “Membership Pro” shows only when it is installed.

Fixed

The import is more reliable: “Publish import” no longer stops, and old download links of Phoca Download and jDownloads then lead straight to the file.
In the backend “Options” stands next to “Help” again, titles in the list of downloads wrap only between words, and PHP 8.5 shows no warning any more.

Version 1.7.0 – 11 November 2026

Added

New options under “Appearance”: accent colour, corners and whether Fileshelf loads its own stylesheet.

Changed

Downloads fit better into every template, including dark areas and narrow columns such as sidebars.
The page of a download is rearranged: file and button in a box beside the description.

Version 1.6.0 – 11 November 2026

Added

Every backend page has a “Help” button that opens the manual in your language.

Changed

New dashboard: figures at a glance, what needs your attention, quick access and the downloads changed last.
The list of downloads shows file type and size, marks downloads without a file and has quick filters.
The download form is clearer: the file comes first, fewer tabs.
The tools are grouped by task; anything that cannot be undone asks first in a dialog.

Version 1.5.1 – 11 November 2026

Fixed

Pro version: Fixed: in rare cases a download could not be deleted once the statistics had already summed it up.

Version 1.5.0 – 11 November 2026

Security

Lists no longer show downloads from categories whose parent category is unpublished or closed to the visitor – not even as a title.
Pro version: one-time links and download limits count downloads in several parts exactly once; the link for an e-mail address replaces only this one hurdle now.
Wrong passwords are counted on the server: a new browser window no longer gets round the wait, many wrong attempts lock the password briefly for everyone.
Uploads and the form check every permission; mails always link the real address of the website, never one forged by a visitor.

Changed

Large collections stay fast: category pages, lists, statistics and the download form load quickly even with tens of thousands of downloads.

Version 1.4.0 – 10 November 2026

Added

Pro version: upload many files at once, one download per file; “Check uploads” is now called “Approve uploads” and explains where the files come from.
Categories on the website with a category tree, as cards or as a sortable table, plus search, sorting, a file type filter and a path back.
Under Tools you create demo data including menu items with one click to try Fileshelf on your website, and remove them just as easily.

Changed

New dashboard: storage folder and inventory at the top, below it ordered by task; every page has “Dashboard” and “Options” at the top and the installed version at the bottom.

Fixed

Fixed: “Download” and unlocking with a password work again on category pages; “Version” and “License” stand with the facts about the file, the license in your language.

Version 1.3.0 – 10 November 2026

Added

Fileshelf writes to Joomla's action log: who creates, changes, publishes or deletes downloads and who sets or removes passwords.
Pro version: a new import takes over categories, downloads, files and counts from Phoca Download, jDownloads and Dropfiles, and plan documents of Membership Pro.
Pro version: after an import, Fileshelf can replace the old shortcodes in articles, create redirects for old addresses and switch menu items.

Version 1.2.0 – 10 November 2026

Added

New menu item type "Extension page": extensions for Fileshelf can offer their own pages on the website, if desired only for logged-in visitors.
Pro version: downloads and categories can be bound to plans of Membership Pro. Members find their downloads under "My downloads", with a welcome mail if you like.
Pro version: downloads in the YOOtheme Pro page builder (dynamic content, element for download lists) and in the link dialog of the JCE editor, there as a shortcode, too.
Pro version: "Download all" loads all downloads of a category as one ZIP archive; a read-me inside names what is not allowed.
Pro version: authorised users upload files on the website; they appear only after you approve them under "Check uploads".

Version 1.1.0 – 10 November 2026

Added

New: the Pro version. It shows download statistics per day and per download with export – without storing IP addresses. The dashboard names the installed version.
Pro version: when you replace a file, the earlier one stays available as a version with its changes; downloads can get an expiry date and then stay visible with a lock.
Pro version: download links that work once or until a date, and downloads visitors only get after confirming their e-mail address.
Pro version: download limits per user group, category or download – per day, week, month or in total; the list says when downloading is possible again.
Pro version: subscriptions to new versions and download reports by mail; Joomla's privacy requests include Fileshelf's data, addresses are deleted after a period.

Version 1.0.0 – 9 November 2026

Added

Initial release.

Fileshelf (EN)

Fileshelf at a glance

What Fileshelf does for you

The parts

Requirements and installation

Requirements

Installing

The dashboard

Updates

Uninstalling

Storage folder and self-test

The self-test

Apache

nginx

Outside the web directory

Delivery by the web server

Creating and maintaining downloads

Tab “File and description”

The file

Extensions and other software packages

Tab “Access”

Tab “Sharing” (Pro version)

Tab “Publishing”

The list

Categories

Additional tabs

The image as icon

Access through additional categories

Deleting

Password protection

Password for one download

Password for a category

What the visitor sees

Downloads on the website

The menu item types

Category image and description

Headings

Heading and introduction of the overview

Browser page title

Three layouts of a category

Without a page per download

Locked downloads

The page of a download

Addresses

Fitting your template

Without code: the options

With one line of CSS: the variables

Your own rules always win

Narrow columns

Classes of buttons and fields

Replacing the stylesheet

Overrides

Shortcodes in articles

The forms

What visitors see

Editor button

TinyMCE's link dialog

Who sees the button

The module

Settings

Search (Smart Search)

Setting up

Who finds what

Media manager

What differs from normal folders

Limit

Tools

Options and permissions

Storage

Downloads

Display

Appearance

Integration

Permissions

Action log

What is logged

Switching it on and off

Free version and Pro version

What the Pro version adds

Which version is installed?