• View
• Edit
• History
• Attach
• Print
• Backlinks

ExtensionHub

Configuration panel for PmWiki extensions (recipes/modules).

This page is a work in progress. Having a few very busy weeks, I'll work on this as time permits. I'll send a message to pmwiki-users when ready. --Petko February 20, 2024, at 07:35 PM

Description

Introducing a new family of PmWiki recipes that are easy to install, configure, and maintain.

Extensions

Easy installation:

• Extensions are placed in the pmwiki/extensions directory.
• They can be uncompressed, or even left as zip-compressed archives.
• They can be checked out or pulled from public version control repository, for easy updates.

Easy configuration:

• There is no need to edit config.php and other local files.
• The Hub (the page SiteAdmin.ExtensionHub on your own wiki) lists all available extensions and allows to enable and configure them.
• The wiki administrator can enable, disable, and edit extension configurations.
• Extensions can have different configurations for different page name patterns. This is more flexible than the local/Group.php and local/Group.Page.php customizations.

And, helper functions for extension authors (see ExtensionDesign).

Hub

The SiteAdmin.ExtensionHub is a configuration panel for extensions. It shows a table with all available extensions, and allows to enable/disable and configure these.

The Hub manages configuration settings for each extension, enables or disables the extension based on the page patterns defined by the wiki admin, and with the priority/actions defined by the developer.

Installation and updates (Hub)

This requires:

• PmWiki version 2.3.31 or more recent.
• PHP 7.0 or more recent on the server.

On a wiki farm, you only install the Hub and all extensions once. You can enable the Hub from farmconfig.php, but individual extensions are enabled and configured per field.

Manually

1. Unzip extensions-2024-08-13a.zip then rename the directory to just "extensions".
2. Place the directory "extensions" on your server in your $FarmD directory (as a sibling to the "scripts" directory, in the same directory where pmwiki.php is located).
3. In config.php or farmconfig.php, add the following line near the top of the file:
   include_once("$FarmD/extensions/hub.php");
   This line should be added after including scripts/xlpage-utf-8.php, but before including scripts/authuser.php (if you include it).

Update an existing Hub installation:

0. Review the Release notes for changes.
1. Get the archive extensions-2024-08-13a.zip.
2. On the wiki, replace the file pmwiki/extensions/hub.php with the one from the archive.

From the GitHub repo

1. In your pmwiki directory, clone the repo:
   git clone https://github.com/5ko/extensions.git
2. In config.php or farmconfig.php, add the following line near the top of the file:
   include_once("$FarmD/extensions/hub.php");
   This line should be added after including scripts/xlpage-utf-8.php, but before including scripts/authuser.php (if you include it).

Update an existing installation:

0. Review the Release notes for changes.
1. From inside your pmwiki/extensions directory, call:
   git pull

Configuration (Hub)

If you have a farm, you need to correctly configure $FarmPubDirUrl (you probably already have).

If for some reason the Hub cannot correctly detect your public extensions path, you can set to config.php such a line:

$ExtPubDirUrl = 'https://www.example.com/extensions';

This is the public browser-reachable path to the /extensions directory.

Internationalization

The following strings can be translated in an XLPage:

To do.

Usage (Extension configuration)

PmWiki extensions are recipes with a specific structure, designed to work with the Hub. You can find compatible extensions at Cookbook:Extensions.

There are 3 ways to install an extension:

1. Check out or pull the code from version control, e.g. a GitHub repository. Do this inside the pmwiki/extensions directory on the server. This method also allows for easy upgrades.
2. Download a compressed (zip) archive with the extension, provided by the developer, and place it in the pmwiki/extensions directory on the server. In some cases you don't need to uncompress the extension, see below.
3. Extract (unzip) the compressed extension in the pmwiki/extensions directory on the server.

Should you uncompress individual extensions?

Using compressed extensions (as zip archives) has benefits and downsides:

Benefits for compressed extensions:

• Easier deployment and updates: Installing and upgrading extensions as zip archives simplifies the deployment process. Administrators can download a single file and (re)place it in the pmwiki/extensions directory.
• Reduced disk space: Compressed extensions occupy less disk space compared to their uncompressed counterparts.
• Read-only distribution: The files in the compressed extension are read-only and are unlikely to be modified unintentionally, which reduces the risk of accidentally breaking an extension.
• Version control: Administrators can easily track and manage different versions of extensions without cluttering the filesystem.
• PHP files inside compressed extensions are only loaded by the Hub and cannot be called directly from a browser, which may prevent unintended access.

Downsides for compressed extensions:

• Performance overhead: Decompressing the extensions at runtime may introduce a performance overhead, albeit usually negligible, and static files served from extensions are cached by the browsers for a reasonable amount of time. However, if the extensions are large or there are many of them, or if the website has many visitors in a short time, this overhead might become noticeable.
• Readability and debugging: It can be more challenging to read and debug code directly from compressed archives. Extracting the files might be necessary for troubleshooting purposes.
• Depending on server configuration, compressed extensions may be downloadable with a browser, if someone guesses the extension URL. The Hub comes with a .htaccess configuration for Apache forbidding this, but it may not work in some cases, or on other servers. You should evaluate how risky is this.

Benefits and downsides of uncompressed extensions:

• Faster processing, no decompression overhead.
• PHP and other files in the extension directory may be reachable via the browser (like for PmWiki skins). For scripts and wikiplain.d pages it might enable unintended access. It is recommended PHP files to start with <?php if (!defined('PmWiki')) exit(); to only run if loaded by PmWiki.

Compressed or not, like with skins and classic recipes, you should only install extensions from trusted sources and authors.

If the extension directory has both a compressed and an uncompressed extension with the same name, the uncompressed one will be loaded.

Extensions placed in pmwiki/extensions are available to the wiki administrators, but they need to be enabled before they become operational. This is done in the page SiteAdmin.ExtensionHub on your wiki, without the need to edit PHP files on the server.

Navigate to SiteAdmin.ExtensionHub on your wiki. By default this page, and the related "hub" action are restricted to "admin" users. You should see a table listing all extensions:

Extension	Version	Priority	Actions	Configurations
BootstrapIcons	2024-05-16	150	*	🟢 *🟡 New configuration
CodeHighlight	2024-07-25	150	*	🟢 *🟡 New configuration
Filterable	2024-08-06	150	*	🟡 New configuration

(Non-functional form)

To enable and configure a new extension, locate its row, from the drop-down select "New configuration" (it should already be selected) then press "Edit". A new page will open with something like this:

(Non-functional form)

Select the checkbox "Enable configuration". In the "Page patterns" field type "*" for all pages, or a different glob pattern, for example for selected groups. The configuration will be enabled on pages that match the pattern, and you could have different configurations for different page patterns.

Press "Save" to save the configuration.

Some extensions provide their own annotated configuration fields. In this case, they will appear between the page patterns and the Save button. (You may need to enable the extension before a custom form is visible.) Please consult the extension documentation.

Notes

• Extensions supported are listed in Extensions.
• See ExtensionDesign How to create extensions compatible with ExtensionHub

To do / some day / maybe

• It should be possible to optimize/speed up the retrieval of the current page configurations outside of the Hub page and actions.
• Internationalization - easy way for extensions to ship with translations.
• Skins - allow for skins to be installed, enabled, and configured like extensions, with automatically discoverable wikilib.d or wikiplain.d pages, possibly resources.
• It may be possible to split the "configuration + loading" of extensions and ship it with the PmWiki core, while having the "compressed serve" part separate.
• Add UI for extension configurations to be manually ordered.
• Should we enable permissions selection for custom actions? Say an action enabled by an extension would be available only to editors or admins, should this be configurable in the hub?

Change log / Release notes

• 2024-08-13a: Fix bug with multi-line page patterns.
• 2024-08-13: extGetConfig() unset some values only needed by the hub, name patterns field convert to textarea (both suggested by Simon).
• 2024-05-31: Configurable status icons, change colors to green (active), red (inactive), yellow (new). Add conditional "extension_enabled". Hub configuration form: larger name patterns field.
• 2024-05-30: Refactor saving configurations to fix bug when unchecking option checkboxes.
• 2024-05-18: Custom form keys only allow [a-zA-Z0-9_] chars. Keys prefixed with "enc_" or "passwd" will save their values base64 encoded. The values will be decoded when the extension requests them with extGetConfig().
• 2024-04-20a: Fix paths for Windows (bug reported by HansB). Refactor .htaccess.
• 2024-04-15a: Fix RecipeCheck incompatibility, reported by Simon.
• 2024-04-10: Add functions extAddHeaderResource() and extAddFooterResource().
• 2024-03-02b: Fix for compressed extensions with version suffix.
• 2024-03-02: Refactor extGetConfig() to merge a default array.
• 2024-02-24: Add class HubPlainPageStore, function extAddWikiPlainDir(). FmtExtList() to require admin perms.
• 2024-02-21: Add page SiteAdmin.ExtensionHub. Page patterns suggestions for existing groups. In .htaccess replace "Options -Indexes" with "IndexIgnore *" (more likely to be available on shared hostings).
• 2024-02-20: Update PageVariables for Hub actions.
• 2024-02-19: First public release, ready to be tested.

See also

Contributors

Written and maintained by Petko.

Comments

See discussion at ExtensionHub-Talk