Feature Proposal: Clarify best practices on naming of query parameters.

Motivation

We've been seeing occasional collisions between extensions use of query parameters. CommentPlugin and RevCommentPlugin were stepping on each other, and recently the refresh= parameter is used by both core and multiple extensions for somewhat different purposes.

Description and Documentation

Plugins should follow several practices to avoid collisions of query parameters.

• Name parameters with some indicator of the extension.
• New Foswiki core parameters should prefix query params with fw_ where practical.
• Recommend (not require) that parameters take format of ext_subject=verb

The bulk of this proposal will go into the documentation as best practices when writing extensions.

Examples

Old implementation	core parameter	Extension parameter	Notes
refresh=on	fw_pagecache=refresh	myplug_cache=refresh
refresh=all	fw_pagecache=purge	myplug_cache=purge	Collides with several plugins that use refresh parameter
refresh=ldap		ldap_cache=refresh	Avoids issues if other extensions do sloppy validation
comment=blah	n/a	commentplugin_comment=blah	Originally collided with RevCommentPlugin
comment=blah	n/a	revcommentplugin_comment=blah RCP_comment=blah

Impact

Changes to the core, for the page cache refresh are probably of little consequence. The refresh links are all generated from the templates.

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: GeorgeClark - 12 Feb 2016

Discussion

After wrangling through the code changes to apply some restrictions on the refresh=all, I'm beginning to wonder if the above proposal isn't at least partly wrong. The plugin-specific param strategy seems reasonable as a best practice, but maybe refresh= should remain as a core parameter, that can be "extended" or attached to by extensions.

Currently it's documented in CommandAndCGIScripts as a "common" parameter applying to all scripts. Another way to fix the confusion regarding this parameter is to update the documentation to better describe it's "pluggable" behaviour.

refresh

Refresh is a "special" reserved parameter that is both implemented by core and optionally by other Contribs and Extensions. It is used to clear various internal persistent (on-disk) and in-memory caches. Options implemented by refresh include:

Refresh option	Cache	Notes
all	PageCache	Admin only, Deprecated: purges the page cache
on	PageCache	Deprecated: Equivalent of "cache' option. (Actions should be descriptive.)
cache	PageCache	Clears the cache for the current topic variants for the current user.
cachepurge	PageCache	Admin only: Purges all cached pages for all users. Used after software or other changes that would not be detected by Foswiki
fire	PageCache	Fires dependencies as if the current topic had changed. (deprecate? Change to cachefire?)

...

-- GeorgeClark - 16 Feb 2016

What's really needed is some way for a plugin to explicitly register the namespace they want to reserve. That way collisions can be detected.

my $namespace = Foswiki::Func::registerNamespace("cp");
$namespace->getURLParameter("comment"); # will get "cp_comment"

then gives me free access to "cp_*" query parameters (and anything else likely to collide that we haven't thought of yet) for cp_comment. You might have noticed I already followed this principle for EditRowPlugin which uses the erp namespace.

The blank namespace is of course reserved for the core.

Of course you can't stop plugins stumbling over each other, but this would at least provide a detection mechanism.

-- Main.CrawfordCurrie - 16 Feb 2016 - 17:43

I started this more as a documentation / best practice effort, with a side effect of cleaning up some obvious collisions. At risk of making a big effort bigger, this might be a good consideration for the new object oriented plugins vrurg is working on.

-- GeorgeClark - 16 Feb 2016

Changing this to a parked proposal.

-- GeorgeClark - 23 Mar 2017

Commenting is disabled while not logged in