The J2C Releases plugin connects Akeeba Release System (ARS) to a J2Commerce store that sells downloadable extensions. When you publish a release in ARS, it fills in the release notes, the product version and the product change log. It also adds change log links and the product page link to your update streams.
This plugin is a separate extension, not included with J2Commerce 6. It is for sites that publish their own downloads through ARS.
Requirements
- J2Commerce 6 and Joomla 6.
- Akeeba Release System (
com_ars) installed and enabled on the same site. - The Akeeba Release System Download ID app, which links each J2Commerce product to an ARS category through its ARS Package ID field.
- A Super User account for publishing releases. The plugin changes nothing when another user saves a release.
Installation
- Go to System -> Install -> Extensions.
- Upload the
plg_system_j2creleasespackage and click Upload & Install. - Go to System -> Manage -> Plugins, search for
j2creleases, and enable the plugin.
Note
The plugin does not enable itself. Enable it before you publish a release.
How It Works
Release Publishing
These actions apply to ARS categories of the Bleeding Edge type. Releases in other categories are left alone.
- Release notes: if the release notes are empty, the plugin fills them from the
CHANGELOGfile in the release folder. - Product version: the release version is written to the product article custom field chosen in Downloads: Version Field.
- Product change log: a new row (date, version and items) is added to the field chosen in Change Log Field.
- Download file: for a downloadable product, the product file name and version are updated to the new release item.
- Environments: each release item gets the environments from the matching row of Release Environments.
- Maturity: the release is saved as stable.
Update Streams
Every entry of an ARS update stream gets a change log link. The link is the Changelog Base URL, then the stream ID, then .xml. The information link of each entry points to the product page, built from Store Base URL.
Change Log Files
The plugin reads CHANGELOG, CHANGELOG.txt or CHANGELOG.md from the version folder of the release. Each line starts with a symbol that sets its type.
| Line Starts With | Type |
|---|---|
+ | Addition |
- | Removal |
~ | Change |
# | Fix |
| Anything else | Note |
A fix line can start with [HIGH], [MEDIUM] or [LOW] to show its severity in the release notes.
Settings
Go to System -> Manage -> Plugins and open j2creleases.
Basic Settings
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Changelog Base URL | Public address the update streams use for change logs. Stream 193 becomes changelogs/193.xml. Your update server must redirect this address to the plugin. | https://updates.j2commerce.com/changelogs/ | A valid URL |
| Store Base URL | Scheme and host used for the product page links in the update streams. The host is never taken from the incoming request. | https://www.j2commerce.com | A valid URL |
| Release Environments | Rows that set which environments a release is available for. Each row has a Version Match and an Environments list. | One empty row | Add or remove rows |
| Version Match | The start of the release version to match. For example, 4. matches every 4.x release. | Empty | Text |
| Environments | The ARS environments applied when the version matches. | None | Environments defined in ARS |
Field Mapping
These settings choose which custom fields of the product article the plugin fills.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Downloads: Version Field | The field in the Downloads tab of the article that holds the release version. | None | None or a custom field |
| Change Log Field | The subform field in the Change Log tab of the article that holds the change log rows. The next six settings appear only when this is set. | None | None or a subform field |
| Change Log Row: Date Field | The sub-field of a change log row that holds the release date. | None | None or a custom field |
| Change Log Row: Title Field | The sub-field of a change log row that holds the release version. | None | None or a custom field |
| Change Log Row: Items Subform Field | The sub-field of a change log row that holds the list of change log items. | None | None or a subform field |
| Change Log Item: Type Field | The sub-field of an item that holds its badge type: danger, success, light, warning or info. | None | None or a custom field |
| Change Log Item: Info Field | The sub-field of an item that holds its text. | None | None or a custom field |
Setting Up a Product
- Create the custom fields for the product article: a version field, and a change log subform with date, version and items.
- Open the plugin, choose those fields on the Field Mapping tab and click Save.
- Edit the product, open the Apps tab and enter the ARS category ID in ARS Package ID.
- Put a
CHANGELOGfile in each version folder of the ARS category. - Publish a release as a Super User and check the product article.
Troubleshooting
The Product Fields Do Not Change
- The ARS category must be of the Bleeding Edge type.
- You must save the release as a Super User.
- The product must be enabled, and its ARS Package ID must list the category ID.
- The fields must be chosen on the Field Mapping tab.
Skipped saves are written to administrator/logs/j2commerce.errors.php.
The Change Log Link Returns an Error
The update stream and its ARS category must both be published. A missing or unpublished stream returns a 404 error.
Uninstalling
Go to System -> Manage -> Extensions, search for j2creleases, select the plugin and click Uninstall. Existing releases and product fields keep their values.