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
Impact
Changes to the core, for the page cache refresh are probably of little consequence. The refresh links are all generated from the templates.
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.
...
--
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