joomla/Component-Builder

28 Fork 13

[ENHANCEMENT]: Additional configuration for installation manifest xml #1306

New Issue

Open

opened 2026-04-24 22:30:24 +00:00 by ConfidantCommunications · 1 comment

ConfidantCommunications commented

2026-04-24 22:30:24 +00:00

Enhancement Details

I'm using JReleaser which is very nice for creating an update server for Joomla. I've run into a couple issues making JCB compatible.

JCB forces the user to enter a path to the Update Server as if it were a static file (i.e. ending with .xml extension). I had to work around that by configuring a fake URL file path and then creating a 301 redirect to the update path JReleaser produces. It would be nice to make that field more tolerant of alternate paths.
JReleaser supports enabling an API token for downloads but JCB does not. If you could add the option of creating a tag with options to configure the prefix and suffix that would be great. e.g.: <dlid prefix="dlid=" suffix=""/>

Which part of the extension will be affected by this enhancement?

Compilation of component, Compiler(admin_view)

Additional Context

No response

### Enhancement Details I'm using JReleaser which is very nice for creating an update server for Joomla. I've run into a couple issues making JCB compatible. 1. JCB forces the user to enter a path to the Update Server as if it were a static file (i.e. ending with .xml extension). I had to work around that by configuring a fake URL file path and then creating a 301 redirect to the update path JReleaser produces. It would be nice to make that field more tolerant of alternate paths. 2. JReleaser supports enabling an API token for downloads but JCB does not. If you could add the option of creating a <dlid> tag with options to configure the prefix and suffix that would be great. e.g.: `<dlid prefix="dlid=" suffix=""/>` ### Which part of the extension will be affected by this enhancement? Compilation of component, Compiler(admin_view) ### Additional Context _No response_

ConfidantCommunications added the enhancement label 2026-04-24 22:30:25 +00:00

Llewellyn commented

2026-06-24 10:47:58 +00:00

Owner

Thank you for raising this and for explaining how you are using JReleaser.

There are a few design decisions in JCB that may help explain the current behaviour.

When JCB was first designed, one of my goals was to avoid adding unnecessary fields, switches, and buttons where the intent could already be determined from an existing value. The update server field is one of those cases.

JCB does not only store a path to an update server. It can also create the update server XML file as part of the compilation and packaging pipeline. When you select the update server option as server, JCB creates the XML file and moves it to the selected server path. When you select zip, JCB creates the XML file and adds it to the compiled package. When you select other, JCB expects you to manage that part yourself.

Because JCB creates and moves the XML file, it needs to know what the file name should be. Instead of adding a second field for the file name, and then needing extra validation to make sure the file name and URL/path remain consistent, JCB currently derives both the location and the file name from the same value. That is why the field currently expects the path to end with an .xml file.

That said, I do understand the JReleaser use case. If JReleaser produces an update endpoint that does not look like a static XML file path, then JCB’s current validation can become too strict. We can investigate whether the field can be made more tolerant of alternate update server paths without breaking the existing pipeline where JCB creates, packages, and/or moves the XML file itself.

Regarding the API token support, the direction we have taken in JCB is slightly different.

JCB has two places where this matters:

The dynamic integration area where the update server XML is added.
The component updates area, where the actual downloadable version/package URL is defined.

In most cases, especially with paid or private downloads, the XML update feed should remain publicly readable. You normally want Joomla to be able to check for updates and show the available update information without the user immediately being blocked by an authorization error. The protection should usually happen at the point where the actual package is downloaded.

For that reason, the solution we have used is an installer plugin. Joomla allows an installer plugin to implement the onInstallerBeforePackageDownload event. That event receives the package URL and headers before the package is downloaded. From there, the plugin can modify the URL, add a token, add authorization headers, block the download, or return an error message.

This approach keeps the update XML accessible while protecting the actual downloadable package. It also gives the developer full control over where the token comes from, whether from the component’s global configuration, another configuration source, or some other custom logic.

We already have a plugin implementation that follows this approach. It was built to integrate with Gitea, allowing a component to download a package from a private repository by adding the required token at download time. The same approach can also be adapted for GitHub or other infrastructure. The idea is that the plugin can be shipped with your component, then customized to match your own distribution pipeline.

I checked, and it looks like this plugin is not currently available in the public JCB package repository where I expected it to be. I will add it there so it can be selected and included more easily with a component.

As for the suggested <dlid prefix="dlid=" suffix=""/> tag, we can investigate whether Joomla’s current update system and JReleaser’s expected structure make that a useful addition for JCB. I cannot give a timeframe at the moment, as our current development time is tied up with other priorities, but I am open to looking into it.

For now, the recommended JCB-compatible approach for token-protected downloads is to keep the update XML available and use an installer plugin to handle the token at the actual package download stage. That gives the best balance between Joomla update visibility, private package protection, and flexible distribution through existing infrastructure such as Gitea or GitHub.

Thank you for raising this and for explaining how you are using JReleaser. There are a few design decisions in JCB that may help explain the current behaviour. When JCB was first designed, one of my goals was to avoid adding unnecessary fields, switches, and buttons where the intent could already be determined from an existing value. The update server field is one of those cases. JCB does not only store a path to an update server. It can also create the update server XML file as part of the compilation and packaging pipeline. When you select the update server option as `server`, JCB creates the XML file and moves it to the selected server path. When you select `zip`, JCB creates the XML file and adds it to the compiled package. When you select `other`, JCB expects you to manage that part yourself. Because JCB creates and moves the XML file, it needs to know what the file name should be. Instead of adding a second field for the file name, and then needing extra validation to make sure the file name and URL/path remain consistent, JCB currently derives both the location and the file name from the same value. That is why the field currently expects the path to end with an `.xml` file. That said, I do understand the JReleaser use case. If JReleaser produces an update endpoint that does not look like a static XML file path, then JCB’s current validation can become too strict. We can investigate whether the field can be made more tolerant of alternate update server paths without breaking the existing pipeline where JCB creates, packages, and/or moves the XML file itself. Regarding the API token support, the direction we have taken in JCB is slightly different. JCB has two places where this matters: 1. The dynamic integration area where the update server XML is added. 2. The component updates area, where the actual downloadable version/package URL is defined. In most cases, especially with paid or private downloads, the XML update feed should remain publicly readable. You normally want Joomla to be able to check for updates and show the available update information without the user immediately being blocked by an authorization error. The protection should usually happen at the point where the actual package is downloaded. For that reason, the solution we have used is an installer plugin. Joomla allows an installer plugin to implement the `onInstallerBeforePackageDownload` event. That event receives the package URL and headers before the package is downloaded. From there, the plugin can modify the URL, add a token, add authorization headers, block the download, or return an error message. This approach keeps the update XML accessible while protecting the actual downloadable package. It also gives the developer full control over where the token comes from, whether from the component’s global configuration, another configuration source, or some other custom logic. We already have a plugin implementation that follows this approach. It was built to integrate with Gitea, allowing a component to download a package from a private repository by adding the required token at download time. The same approach can also be adapted for GitHub or other infrastructure. The idea is that the plugin can be shipped with your component, then customized to match your own distribution pipeline. I checked, and it looks like this plugin is not currently available in the public JCB package repository where I expected it to be. I will add it there so it can be selected and included more easily with a component. As for the suggested `<dlid prefix="dlid=" suffix=""/>` tag, we can investigate whether Joomla’s current update system and JReleaser’s expected structure make that a useful addition for JCB. I cannot give a timeframe at the moment, as our current development time is tied up with other priorities, but I am open to looking into it. For now, the recommended JCB-compatible approach for token-protected downloads is to keep the update XML available and use an installer plugin to handle the token at the actual package download stage. That gives the best balance between Joomla update visibility, private package protection, and flexible distribution through existing infrastructure such as Gitea or GitHub.

👍 1

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: joomla/Component-Builder#1306