Phoca Download Source (EN)

• Phoca Download Source at a glance
• Requirements and installation
• Download key and updates
• Using the Phoca Download source in the builder
• The three source types
• Fields and properties
• Categories and subcategories
• Practical examples
• Common questions and troubleshooting
• Changelog

Phoca Download Source at a glance

Phoca Download Source connects the download manager Phoca Download with the page builder of YOOtheme Pro. Your documents, files and download categories thus become available as a dynamic content source in every builder element — in grids, lists, sliders, cards or headlines, however you want to design your download areas.

What the plugin does

• Three source types: a single document, a document list (compiled by hand or built automatically from categories) and a category list.
• All relevant fields: title, description, version, file name, file size (formatted), file type icon, author, licence, images, download and detail link, hit counts, tags — and all custom Joomla fields you have created.
• Automatic subcategories: category queries include up to four levels of subcategories on request.
• Sorting and limit: by title, date, popularity or manual order, with a freely chosen count.
• Download counting is preserved: the download links produced go through Phoca Download — hit counts, permissions and direct-link settings of the component apply unchanged.

How it works

After the installation the plugin registers the source "Phoca Download" with the YOOtheme builder. In the dynamic content of an element you choose one of the three source types, make your selection (document, categories, sorting, count) and map the fields to the element's areas. The output updates automatically as soon as your downloads change — new files appear in the layout without any further action.

How to use the source in the builder is shown in the article Using the Phoca Download source in the builder.

Applies to version 1.7.3.

Deutsche Fassung

Requirements and installation

Requirements

• Joomla: 6.0 or newer
• PHP: 8.2 or newer
• YOOtheme Pro: installed and active as the site template
• Phoca Download: version 6.x — available free of charge at phoca.cz

Installation

1. Download the installation package plg_system_ytp_phocadownload-x.y.z.zip from your customer account on graup-it.de.
2. In the Joomla backend, open System → Install → Extensions.
3. Drag the ZIP file into the upload area or select it via Browse.

On a first installation the plugin is enabled automatically. You will find it afterwards under System → Plugins as System - Phoca Download Source.

The panel after the installation names the installed version and leads to the three things now due: selecting the source in the builder, storing the download key for updates, and the manual. After an update, the changelog takes the place of "Getting started".

After the installation

1. Clear the YOOtheme cache: YOOtheme → Settings → Advanced → Clear Cache.
2. Open a page in the builder — the dynamic content of the elements now offers the group "Phoca Download" with the three source types.
3. Enter your download key for automatic updates — see Download key and updates.

Updating from version 1.6 or older

An update is installed like a fresh installation via the ZIP, or conveniently through the Joomla updater; your settings are preserved. Version 1.7 automatically cleans up the files of older plugin versions and converts a download ID already stored to the current key format — you do not have to do anything further.

Uninstalling

Under System → Manage Extensions, select the plugin System - Phoca Download Source and uninstall it. Your downloads and categories in Phoca Download remain fully intact; only the source in the builder is gone. Phoca Download sources used in layouts show no content afterwards.

Applies to version 1.7.3.

Deutsche Fassung

Download key and updates

Phoca Download Source receives updates through the official Joomla update mechanism. To allow your website to fetch them, enter your personal download key once.

Entering the download key

1. Create your download key in your customer account on graup-it.de (menu item Download IDs). One key applies per website and covers all extensions obtained through it.
2. In the backend, open System → Update → Update Sites.
3. Open the entry Phoca Download Source Updates and enter the key into the field Download Key.
4. Save.

Installing updates

1. Open System → Update → Extensions.
2. If a new version is available, Phoca Download Source appears in the list. Select it and click Update.
3. Joomla downloads the package using your download key, verifies the checksum and installs the new version. Your settings and your builder layouts are preserved.

If Joomla finds no update although a new version exists, click Check for Updates first to refresh the cache.

The manual route

You can also install any version by hand: download the ZIP and install it via System → Install → Extensions, just like the first installation. An update through the package overwrites the existing installation and keeps your settings.

Applies to version 1.7.3.

Deutsche Fassung

Using the Phoca Download source in the builder

The Phoca Download source is available in every YOOtheme element that supports dynamic content — grid, list, slider, cards, headlines or buttons, for instance.

Selecting the source

1. Open the page you want in the YOOtheme builder.
2. Add an element (a grid, for example) or open an existing one.
3. Switch to the Content tab of the element and enable the source under Dynamic Content.
4. In the source selector you find the group Phoca Download with three entries: Single document, Documents and Categories.

Assigning fields

Once the source is chosen, you map the Phoca Download fields to the areas of the element: on a grid, for example, title → field "Title", image → "Image (full view URL)", link → "Download link". Every field can additionally be filtered (shortening text or formatting a date, say) — those are the standard filters of the YOOtheme builder.

Preview and publishing

The builder shows the real content in the preview right away. New or changed downloads appear automatically — the layout stays in sync with Phoca Download without you having to edit the page again. Unpublished or unapproved documents are never output.

Which settings the three source types offer is described in the article The three source types.

Applies to version 1.7.3.

Deutsche Fassung

The three source types

Phoca Download Source offers three source types. All three return published content only (and, for documents, approved content).

Single document

Outputs exactly one document — ideal for a highlighted download, such as the current version of a product on the home page.

• Document: chosen from all published downloads.

Documents

Outputs a list of documents. The mode determines how the list comes about:

Mode "manual"

• Documents: multiple selection; for orientation the entries show the category in square brackets (for example [Manuals] User guide).
• Sorting: "manual selection order" keeps the order of your selection; alternatively by title, date, popularity or the Phoca order.

Mode "automatic"

• Categories: one or more categories — or all categories.
• Include subcategories: includes up to four levels of subcategories (see Categories and subcategories).
• Sorting and count (default 20, upper limit 500).

Categories

Outputs download categories — as a tile overview linking to the respective category pages, for instance.

• Mode "manual": a fixed selection of individual categories.
• Mode "automatic": all categories, or the subcategories of a chosen parent category.
• Show empty categories: by default, categories without files are hidden.
• Sorting (order, title, popularity) and count.

The sorting options at a glance

• Manual selection order (document list in "manual" mode only)
• Order — the sorting defined in Phoca Download
• Title A–Z / Title Z–A
• Newest first / Oldest first
• Most popular first — by download counts

Applies to version 1.7.3.

Deutsche Fassung

Fields and properties

Once the source is chosen, the following fields are available for assignment in the builder.

Fields of a document

Basic information

• Title, alias, project name
• Description, features, changelog, notes — the four text areas from Phoca Download
• Version

File

• File name, file extension (for example pdf)
• File size — raw in bytes or ready-formatted (for example "2.4 MB"). The size is determined from the file itself and is therefore correct even after the file has been replaced.
• File type icon — as an icon key (for example pdf, zip) or as a ready-made icon URL from the Phoca Download component; more than 60 file types are recognised.

Links

• Download link — goes through Phoca Download; hit counting and permissions stay active
• Detail link — the document's detail page
• External link, mirror 1/2 (each with link, title and target window)

Images and media

• Image (file name, full view URL, thumbnail URL)
• Extra image 1 and 2 — the special images from Phoca Download 6
• Download button image, video file, play/preview file

Metadata

• Author (name, email, website), licence (name, URL)
• Date, publish up/down
• Hits, direct-link flag
• Category (ID and title)
• Tags — as a comma-separated list (for example "Software, Open Source, Free")
• Meta keywords, meta description

Custom fields

All Joomla fields you have created for Phoca Download documents appear automatically as additional builder fields — under the name of the respective field. A field manufacturer is thus available in the builder without any further configuration.

Fields of a category

• Title, alias, description
• Image (file name and URL)
• File count — including subcategories; handy for badges such as "12 files"
• Parent category (ID and title), order, hits
• Link — the category page of Phoca Download

Applies to version 1.7.3.

Deutsche Fassung

Categories and subcategories

Phoca Download organises files in categories nested to any depth. Phoca Download Source mirrors that structure in the builder — for document lists as well as for category overviews.

Subcategories in document lists

If the option include subcategories is active for the source type Documents (mode "automatic"), the plugin searches up to four levels:

• main category (level 1)
• → subcategory (level 2)
• → → sub-subcategory (level 3)
• → → → fourth level

All documents from all levels flow into the result list and are sorted and limited together. If you disable the option, only the category selected directly counts.

Category overviews

With the source type Categories you build overview pages: in automatic mode you choose a parent category and the element shows its direct subcategories — each with title, description, image, file count and a link to the category page. Without a parent category, all published categories are output.

Example: a download centre

A proven layout for a download centre combines both types:

1. At the top a grid with the source type Categories — one tile per area (for example "Manuals", "Software", "Forms") with image and file count.
2. Below it a list with the source type Documents, sorting "newest first", count 5 — the most recent downloads across all areas.

Applies to version 1.7.3.

Deutsche Fassung

Practical examples

Three practical examples show typical field assignments. You find the field names in the assignment list of the respective element area; the examples name the field labels with the technical name in brackets.

Download grid with cards

Element grid, source Documents (mode "automatic", category "Software"):

• Title → title (title)
• Meta → for example "Version 2.1 • 4.7 MB" from version (version) and formatted file size (file_size_formatted)
• Content → description (description), shortened with the Limit filter
• Image → image (full view URL) (image_full) — or the file type icon (file_icon_url) for a plain icon look
• Link → download link (download_link)

Download button

Element button, source Single document:

• Text → title (title) or a fixed text such as "Download now"
• Link → download link (download_link)

Category tiles

Element grid, source Categories (mode "automatic"):

• Title → title (title)
• Meta → file count (file_count), for example as "12 files"
• Image → category image (image_url)
• Link → category link (link)

Author and licence details

For software downloads, author (author), author website (author_url) and licence (license) can be combined in the meta area of a card, say — or in a text element of their own below the download button.

Applies to version 1.7.3.

Deutsche Fassung

Common questions and troubleshooting

The source "Phoca Download" does not appear in the builder

• Clear the YOOtheme cache: YOOtheme → Settings → Advanced → Clear Cache, then reload the builder.
• Check under System → Plugins whether System - Phoca Download Source is enabled.
• Check whether the Phoca Download component is installed and enabled — without it the plugin deliberately stays inactive.
• Also clear the Joomla cache (System → Clear Cache) and the browser cache (Ctrl+F5).

No documents are shown

• Documents have to be published and approved in Phoca Download — both are checked.
• In "automatic" mode: are the selected categories right? If the document sits in a subcategory, include subcategories has to be active.
• In "manual" mode: is at least one document selected?
• The plugin follows the visibility rules of Phoca Download: documents with a restricted access level are only seen by permitted visitors, and a configured publishing period is respected. Check both in the document.

Images are not shown

• Phoca Download images live under images/phocadownload/ — check whether the file exists there (if in doubt, assign it again in the document in Phoca Download).
• For file type icons the Phoca Download component must have installed its media (media/com_phocadownload/images/mime/).

The file size is 0 or wrong

The plugin reads the size directly from the file in the Phoca Download folder; only if the file is not readable there does the value stored in the database apply. Check whether the file is in the configured download folder and whether the file name in the document is correct.

Custom fields are missing in the builder

• The fields have to be created for Phoca Download documents and published.
• After creating new fields, clear the YOOtheme cache.

The update fails ("403", "Invalid Domain", "URL rejected")

• Check the download key under System → Update → Update Sites — without leading or trailing spaces.
• The key is tied to your website's domain; for a new domain, create another key in your customer account.

Does the plugin change my downloads?

No. The plugin only reads data from Phoca Download. Management, permissions, hit counting and delivery of the files remain entirely with the component.

Applies to version 1.7.3.

Deutsche Fassung

Changelog

This changelog lists every released version of Phoca Download Source, the most recent first.

Version 1.7.3 – 16 August 2026

Fixed

• The links in the overview panel always led to the German manual. They now follow the configured language.
• The panel shown after the installation named licence version 2. It now shows the GNU General Public License version 3 or later, as everywhere else.

Version 1.7.2 – 31 July 2026

Changed

• The extension is licensed under the GNU General Public License version 3 or later. All details on licence, author and copyright are consistent.

Fixed

• The licence file shipped named a different product and contained only a short notice instead of the full licence text.

Version 1.7.1 – 31 July 2026

Added

• After an installation or update an overview panel appears with version, status and entry points to getting started, download key and manual.
• A click on "Enable updates" leads straight to the update sites, already filtered to missing download keys.
• The extension manager now shows the list of changes behind the version number.

Changed

• Notices about leftover files of an old version or about Phoca Download being disabled now appear in the overview panel instead of loosely beside it.

Language

• All messages shown during installation and update are available in German and English.

Version 1.7.0 – 30 July 2026

Security

• Downloads now follow the visibility rules of Phoca Download: access level, publishing period and content language are respected.
• Until now, downloads with restricted access or a publishing period appeared publicly in the layout.
• Determining the file size can no longer escape from the download folder.
• All database values go through bound parameters.

Changed

• Large lists load considerably faster: categories and tags are fetched in bulk instead of per document.
• On regular page views the queries for the builder's selection lists are gone; they only run in the customizer.
• Complete modernisation onto the Joomla 6 architecture — no more deprecation warnings.
• The download key is passed in the form the update server expects; existing update sites are converted during the installation.
• The category selection in the builder is sorted hierarchically and indented, and the image fields carry unambiguous labels.
• The display name is now "System - Phoca Download Source".

Fixed

• An update no longer leaves files of old versions behind.

Removed

• The plugin no longer disables itself when Phoca Download is missing. Instead the installation stops without the component; at runtime it simply has no effect.
• An interface endpoint unused since 1.2.0 was removed.

Version 1.6.0 – 6 March 2025

Added

• The download key is managed centrally under System → Update → Update Sites.
• A key previously stored in the plugin settings is taken over during the installation.

Version 1.5.0

Changed

• Update connection and download key as a plugin setting — the precursor to the central management in 1.6.0.

Version 1.3.0 – 22 January 2025

Added

• Automatic detection of the file type with a matching icon for more than 60 file types.

Version 1.2.1 – 22 January 2025

Fixed

• The YOOtheme builder showed raw text keys instead of the labels.

Version 1.2.0 – 22 January 2025

Language

• Full multilingual support in German and English.

Deutsche Fassung