Feature Proposal: TWiki::Func and TWiki variable enhancements for ReadOnlyAndMirrorWebs

Motivation

ReadOnlyAndMirrorWebs causes needs for enhancements to TWiki::Func and TWiki variables.

Description and Documentation

Examples

New functions in TWiki::Func

TWiki::Func::getSiteName() -> $siteName

Returns $TWiki::cfg{SiteName} or a null string ("").

TWiki::Func::getContentMode($web) -> $contentMode

Returns the content mode of the specified web.

TWiki::Func::webWritable($web)

Checks if the web is writable on this site. Returns true if it is. Returns false otherwise.

Enhanced functions in TWiki.pm

TWiki::getScriptUrl($absolute, $web, $topic, $script, @params) -> $scriptUrl

It acts differently with a slave web.

With edit, save, attach, upload, and rename scripts, it returns the absolute script URL on the master site even if $absolute is false.

If '$master' => 1 is handed in @params, it returns the absolute script URL on the master site regardless of script and $absolute.

The scripts returning master site URLs without '$master' => 1 are specified in the following manner.

$TWiki::cfg{ScriptOnMaster}{edit} = 1;
$TWiki::cfg{ScriptOnMaster}{save} = 1;
...

TWiki::SCRIPTURL(), TWiki::SCRIPTURLPATH()

They are enhanced so that the following returns the expected value.

• %SCRIPTURL{"view" web="WEB"}%
• %SCRIPTURL{"view" web="WEB" topic="TOPIC"}%
• %SCRIPTURL{"view" topic="WEB.TOPIC"}% - same as above
• %SCRIPTURL{"view" topic="TOPIC"}% same as %SCRIPTURL{"view" web="%WEB%" topic="TOPIC"}%, the default value of the web parameter when topic parameter is present is the current web.
• %SCRIPTURLPATH{"view" web="WEB"}%
• %SCRIPTURLPATH{"view" web="WEB" topic="TOPIC"}%
• %SCRIPTURLPATH{"view" topic="WEB.TOPIC"}%
• %SCRIPTURLPATH{"view" topic="TOPIC"}%

Just like getScriptUrl(), SCRIPTURL() and SCRIPTURLPATH() behave differently with a slave web.

If master="on" parameter is in %SCRIPTURL{...}% or %SCRIPTURLPATH{...}%, then they return master site's URLs regardless of script.

These enhancements make %MASTERWEBSCRIPTURL{...}% redundant.

Impact

Implementation

-- Contributors: HideyoImazu - 2012-10-26

Discussion

Overall I like the proposal, much cleaner for plugin developers than the current spec. Feedback and questions:

• What is contentMode?
• For TWiki::getScriptUrl() extra parameter #master, I recommend to use a different prefix character than "#", I find it somewhat confusing because of the #anchorName syntax. How about $ prefix, e.g. '$master' => 1?
• On %SCRIPTURL{"view/%WEB%/%TOPIC%"}%, I think it is confusing to have web and topic as part of the script of SCRIPTURL.
  • This syntax also likely fails if a site uses a $TWiki::cfg{ScriptSuffix} - the %SCRIPTURL{view}% returns view.pl if {ScriptSuffix} is set to .pl.
  • Logically I think it is better to define new parameter(s), such as %SCRIPTURL{ "view" web="%WEB%" topic="%TOPIC%" }% or the like.
  • We could align the parameters with the parameters of TWiki::getScriptUrl():
    • web="%WEB%"
    • topic="%TOPIC%"
    • any_other_param="value"
    • is_added="as URL parameter"
    • _anchor="SomeAnchor" - reserved to specify anchor, which is # => SomeAnchor in TWiki::getScriptUrl()
    • If web or topic parameter is missing and other parameters are specified, a valid TWiki URL needs to be constructed: In this case the web and topic are filled in as %BASEWEB%" and %BASETOPIC%", respectively

-- PeterThoeny - 2012-10-27

• contentMode is a notion introduced at ReadOnlyAndMirrorWebs.
• '$master' => 1 is fine by me. It's reflected at #Example
• %SCRIPTURL{...}%
  • %SCRIPTURL{"view/%WEB%/%TOPIC%"}% syntax is for brevity.
  • sub SCRIPTURL would extract the script name, web, and topic and process accordingly. %SCRIPTURL{"view/WEB/TOPIC"}% would equivalent to getScriptUrl(1, 'view', 'WEB', 'TOPIC'). As such %SCRIPTURL{"view/%WEB%/%TOPIC%"}% would work fine even if {ScriptSuffix} is set.
  • %SCRIPTURL{"view" web="%WEB%" topic="%TOPIC%"}% is logical but more verbose than %SCRIPTURL{"view"}%/%WEB%/%TOPIC%
  • Do other parameters necessary? As of now, I have no need. So how about deferring to when somebody wants it?

-- HideyoImazu - 2012-10-29

• On contentMode, I suggest to document it directly in the TWiki::Func::getContentMode docs
• I really think %SCRIPTURL{"view/WEB/TOPIC"}% is a hack. If you feel strongly about this syntax, how about implementing it both ways, but document only %SCRIPTURL{ "view" web="%WEB%" topic="%TOPIC%" }% syntax?

-- PeterThoeny - 2012-10-29

• TWiki::Func::getContentMode doc will have sufficient details.
• For the content mirroring to work, on the view template, %SCRIPTURL{"edit"}%/%WEB%/%TOPIC% needs to be modified to either:
  • %SCRIPTURL{"edit/%WEB%/%TOPIC%"}% (the short syntax. the same length as the original)
  • %SCRIPTURL{"edit" web="%WEB%" topic="%TOPIC%"}% (the long syntax. 14 characters longer than the original)
• Though the short syntax is a bit of hack, still it's more practical, intuitive, easier to deal with, I think.
• I don't like undocumented features. If you cannot stand the short syntax, I have no option but accept the long syntax.

-- HideyoImazu - 2012-10-30

What is the plan for %PUBURL%, %PUBURLPATH%, %ATTACHURL% and %ATTACHURLPATH%? Do they need to be enhanced as well?

-- PeterThoeny - 2012-10-31

There is no need for enhancement to %PUBURL%, %PUBURLPATH%, %ATTACHURL%, and %ATTACHURLPATH% because they are always .../pub/... even under UsingMultipleDisks. It's described at UsingMultipleDisks

-- HideyoImazu - 2012-11-01

Topic name changed from TWikiFuncEnhancementForReadOnlyAndMirrorWebs (singular Enhancement) to TWikiFuncEnhancementsForReadOnlyAndMirrorWebs (plural Enhancements)

-- HideyoImazu - 2012-11-01

I really like that SCRIPTURL and MASTERWEBSCRIPTURL can be consolidated into one. KISS for users.

On %SCRIPTURL{"edit/%WEB%/%TOPIC%"}% syntax, I really find it confusing. So if a site has a script suffix defined, when you specify "edit/%WEB%/%TOPIC%" it actually means "edit.pl/%WEB%/%TOPIC%". Yes, the variable gets longer with web="" and topic="" parameters, but I find it much more consistent. We could shorten it by making web="" optional and accept "TopicName" or "Web.TopicName" in the topic="" parameter (The normalizeWebTopicName() takes care of figuring out proper web and topic combination). This matches the syntax of VarADDTOHEAD, VarFORMFIELD, VarMETA, VarPARENTTOPIC and VarTOPICTITLE.

-- PeterThoeny - 2012-11-05

%SCRIPTURL{"edit" topic="%WEB%.%TOPIC%"}% is not bad. I take it. I modified the TWiki::SCRIPTURL(), TWiki::SCRIPTURLPATH() section accordingly.

-- HideyoImazu - 2012-11-06

Accepted by consensus reached at JerusalemReleaseMeeting2012x11x09.

-- PeterThoeny - 2012-11-09

TWiki::Func::checkWritable() has been renamed to TWiki::Func::webWritabe() and it's been made to return a Boolean value rather than throwing exception. This is to make it similar to TWiki::Func::webExists().

-- HideyoImazu - 2012-11-13