Skip to content

Commit

Permalink
Item13909: improve doc, use CREATE instead of EXPAND, conditionally d…
Browse files Browse the repository at this point in the history 
…isable EOTC in new installs
  • Loading branch information
@cdot
cdot committed Feb 20, 2017
1 parent 062ff5e commit 7196d29
Show file tree
Hide file tree
Showing 7 changed files with 129 additions and 53 deletions.
77 changes: 67 additions & 10 deletions UnitTestContrib/test/unit/TopicTemplatesTests.pm
View file
Expand Up @@ -226,24 +226,22 @@ sub test_templateTopicWithAttachments {
return;
}

sub test_templateTopicWithMacros {
my $this = shift;
sub test_templateTopicWithEOTCMacros {
my $this = shift;
$Foswiki::cfg{DisableEOTC} = 0;
my $query = Unit::Request->new(
{
text => [<<'TEXT'],
* NOP: No%NOP%Link
* DATE: %DATE%
* TMPL:DATE: %TMPL:DATE%
* CREATE:DATE: %CREATE:DATE%
* GMTIME: %GMTIME%
* SERVERTIME: %SERVERTIME%
* USERNAME: %USERNAME%
* TMPL:USERNAME: %TMPL:USERNAME%
* URLPARAM: %URLPARAM{"purple"}%
* WIKINAME: %WIKINAME%
* WIKIUSERNAME: %WIKIUSERNAME%
* COMMENT: #{ ... comment }#
* TMPL:IF: %TMPL:IF{"1=1" then="OK" else="BAD"}%
* TMPL:P:%TMPL:P{"sep"}%
%STARTSECTION{type="templateonly"}%
Mither me not
%ENDSECTION{type="templateonly"}%
Expand Down Expand Up @@ -274,18 +272,15 @@ TEXT
Foswiki::Func::readTopic( $this->{test_web}, 'TemplatedTopic' );
my $text = $meta->text;
$this->assert( $text =~ s/^\s*\* DATE: \d+ \w+ \d+$//m, $text );
$this->assert( $text =~ s/^\s*\* TMPL:DATE: \d+ \w+ \d+$//m, $text );
$this->assert( $text =~ s/^\s*\* CREATE:DATE: \d+ \w+ \d+$//m, $text );
$this->assert( $text =~ s/^\s*\* GMTIME: \d+ \w+ \d+ - \d+:\d+$//m, $text );
$this->assert( $text =~ s/^\s*\* SERVERTIME: \d+ \w+ \d+ - \d+:\d+$//m,
$text );
$this->assert( $text =~ s/^\s*\* USERNAME: scum$//m, $text );
$this->assert( $text =~ s/^\s*\* TMPL:USERNAME: scum$//m, $text );
$this->assert( $text =~ s/^\s*\* WIKINAME: ScumBag$//m, $text );
$this->assert( $text =~ s/^\s*\* WIKIUSERNAME: \w+\.ScumBag$//m, $text );
$this->assert( $text =~ s/^\s*\* URLPARAM: ok$//m, $text );
$this->assert( $text =~ s/^\s*\* NOP: NoLink$//m, $text );
$this->assert( $text =~ s/^\s*\* TMPL:IF: OK$//m, $text );
$this->assert( $text =~ s/^\s*\* TMPL:P: \| $//m, $text );
$this->assert( $text =~ s/^\s*\* COMMENT: $//m, $text );
$this->assert( $text =~ s/^TemplatedTopic$//m, $text );
$this->assert( $text =~ s/^%TOPIC%$//m, $text );
Expand All @@ -297,4 +292,66 @@ TEXT
return;
}

sub test_templateTopicWithCREATEMacros {
my $this = shift;
$Foswiki::cfg{DisableEOTC} = 1;
my $query = Unit::Request->new(
{
text => [<<'TEXT'],
* NOP: No%NOP%Link
* DATE: %DATE%
* CREATE:DATE: %CREATE:DATE%
* CREATE:USERNAME: %CREATE:USERNAME%
* CREATE:URLPARAM: %CREATE:URLPARAM{"purple"}%
* URLPARAM: %URLPARAM{"purple"}%
* COMMENT: %{ ... comment }%
* CREATE:IF: %CREATE:IF{"1=1" then="OK" else="BAD"}%
%STARTSECTION{type="templateonly"}%
Mither me not
%ENDSECTION{type="templateonly"}%
%STARTSECTION{type="expandvariables"}%
%TOPIC%
%ENDSECTION{type="expandvariables"}%
%TOPIC%
TEXT
action => ['save'],
topic => [ $this->{test_web} . '.TemplateTopic' ]
}
);
$this->createNewFoswikiSession( $this->{test_user_login}, $query );
$this->captureWithKey( save => $UI_FN, $this->{session} );
$query = Unit::Request->new(
{
templatetopic => ['TemplateTopic'],
action => ['save'],
purple => ['ok'],
topic => [ $this->{test_web} . '.TemplatedTopic' ]
}
);
$this->createNewFoswikiSession( $this->{test_user_login}, $query );
my ( $responseText, $result, $stdout, $stderr ) =
$this->captureWithKey( save => $UI_FN, $this->{session} );
print STDERR $stderr;
my ($meta) =
Foswiki::Func::readTopic( $this->{test_web}, 'TemplatedTopic' );
my $text = $meta->text;
$this->assert( $text =~ s/^\s*\* DATE: %DATE%$//m, $text );
$this->assert( $text =~ s/^\s*\* CREATE:DATE: \d+ \w+ \d+$//m, $text );
$this->assert( $text =~ s/^\s*\* CREATE:USERNAME: scum$//m, $text );
$this->assert( $text =~ s/^\s*\* CREATE:URLPARAM: ok$//m, $text );
$this->assert( $text =~ s/^\s*\* URLPARAM: %URLPARAM\{"purple"\}%$//m,
$text );
$this->assert( $text =~ s/^\s*\* NOP: NoLink$//m, $text );
$this->assert( $text =~ s/^\s*\* CREATE:IF: OK$//m, $text );
$this->assert( $text =~ s/^\s*\* COMMENT: %\{ ... comment \}%$//m, $text );
$this->assert( $text =~ s/^TemplatedTopic$//m, $text );
$this->assert( $text =~ s/^%TOPIC%$//m, $text );
$this->assert( $text !~ /Mither me not/s, $text );
$text =~ s/\s+//gs;
$this->assert_equals( "", $text );
$meta->finish();

return;
}

1;
54 changes: 35 additions & 19 deletions core/data/System/SkinTemplates.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" comment="" date="1452527048" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" comment="" date="1487618135" format="1.1" version="1"}%
%META:TOPICPARENT{name="Skins"}%
%STARTINCLUDE%
---+ Skin Templates
Expand Down Expand Up @@ -48,12 +48,12 @@ Template directives look a lot like standard [[macros]].
* =#<nop>{...}#= is a comment. Whitespace either side of the comment
(newlines, spaces, tabs etc) is treated as part of the comment, and
removed when the comment is removed. An alternate syntax =%<nop>{...}%=
is also supported.
is also supported - see #Comments below for why.
You can use a block before _or_ after declaring it. If you define the same
block twice, only the second definition is used.

<div class="foswikiHelp">
%X% Most template directives work only for templates: they do not get processed in normal topic text. The one exception is =TMPL:P=, which is expanded in normal text (and also when a TopicTemplate is expanded).
%X% Most template directives work only for templates: they do not get processed in normal topic text. The one exception is =%TMPL:P=.
</div>

---+++ Parameters to blocks
Expand Down Expand Up @@ -96,15 +96,11 @@ then
</verbatim>
will expand to =x1000z=.


---++++ Naming
Any alphanumeric characters can be used in parameter names. =TMPL:P= parameters
override any other possible definition of the name, so you should not use
parameter names that might clash with [[Macros]].




---+++ Conditional expansion
---++++ Using context identifiers
Three parameter names, =context=, =then= and =else= are *reserved*.
Expand Down Expand Up @@ -170,6 +166,26 @@ An alternative comment type =#{...}#= will automatically absorb whitespace
either side of the comment (newlines, spaces, tabs etc). This type of comment
only works in templates.

The alternative comment type becomes really useful when we have skin templates defined in topics, because we can now use it to delimit content that should be _displayed when the topic is viewed normally_, but _removed when the templates are instantiated_.

or example, we might have templates in a topic like this:
<verbatim class="tml">
%TMPL:DEF{"example"}%
#{ This comment will always be removed }%
%{ This comment will be removed when the template is instantiated }%
Example
%TMPL:END%
</verbatim>

When we view the topic, we'll see:

%<nop>TMPL:DEF{"example"}%
#{ This comment will always be removed }%
%{ This comment will be removed when the template is instantiated }%
Example
%<nop>TMPL:END%
but all comments will be removed when the template is actually used.

#FindingTemplates
---++ Finding Skin Templates

Expand Down Expand Up @@ -203,15 +219,15 @@ The rules defined by the out-of-the-box setting of ={TemplatePath}= are:
7 =$web.$nameTemplate=
8 =%SYSTEMWEB%.$nameTemplate=
For example, let's say we are viewing a topic in web =%SANDBOXWEB%= and are searching for the template called =function=. The skin path is set to =custom,pattern=. The following locations will be considered in turn, until a template is found:
1 :skull: =templates/%SANDBOXWEB%/function.custom.tmpl= _(rule 1)_
1 :skull: =templates/%SANDBOXWEB%/function.pattern.tmpl= _(rule 1)_
1 =templates/%SANDBOXWEB%/function.custom.tmpl= _(rule 1)_ :skull:
1 =templates/%SANDBOXWEB%/function.pattern.tmpl= _(rule 1)_ :skull:
2 =templates/function.custom.tmpl= _(rule 2)_
2 =templates/function.pattern.tmpl= _(rule 2)_
3 =%SANDBOXWEB%.CustomSkinFunctionTemplate= _(rule 3)_
3 =%SANDBOXWEB%.PatternSkinFunctionTemplate= _(rule 3)_
4 =%SYSTEMWEB%.CustomSkinFunctionTemplate= _(rule 4)_
4 =%SYSTEMWEB%.PatternSkinFunctionTemplate= _(rule 4)_
5 :skull: =templates/%SANDBOXWEB%/function.tmpl= _(rule 5)_
5 =templates/%SANDBOXWEB%/function.tmpl= _(rule 5)_ :skull:
6 =templates/function.tmpl= _(rule 6)_
7 =%SANDBOXWEB%.FunctionTemplate= _(rule 7)_
8 =%SYSTEMWEB%.FunctionTemplate= _(rule 8)_
Expand Down Expand Up @@ -338,12 +354,12 @@ see what PatternSkin defines.

%STOPINCLUDE%

%META:FILEATTACHMENT{name="oopsmore_diff_debug.gif" attr="h" comment="" date="1452527048" size="3205" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default.css.gz" attr="h" comment="" date="1452527048" size="2072" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base.css.gz" attr="h" comment="" date="1452527048" size="1331" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="oopsmore_diff_sidebyside.gif" attr="h" comment="" date="1452527048" size="1994" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base_src.css" attr="h" comment="" date="1452527048" size="6780" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base.css" attr="h" comment="" date="1452527048" size="5196" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="oopsmore_diff_sequential.gif" attr="h" comment="" date="1452527048" size="3464" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default_src.css" attr="h" comment="" date="1452527048" size="11093" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default.css" attr="h" comment="" date="1452527048" size="8209" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="oopsmore_diff_debug.gif" attr="h" comment="" date="1487618135" size="3205" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default.css.gz" attr="h" comment="" date="1487618135" size="2072" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base.css.gz" attr="h" comment="" date="1487618135" size="1331" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="oopsmore_diff_sidebyside.gif" attr="h" comment="" date="1487618135" size="1994" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base_src.css" attr="h" comment="" date="1487618135" size="6780" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="base.css" attr="h" comment="" date="1487618135" size="5196" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="oopsmore_diff_sequential.gif" attr="h" comment="" date="1487618135" size="3464" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default_src.css" attr="h" comment="" date="1487618135" size="11093" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="default.css" attr="h" comment="" date="1487618135" size="8209" user="ProjectContributor" version="1"}%
23 changes: 6 additions & 17 deletions core/data/System/TemplateTopics.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" date="1452527048" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1487617858" format="1.1" version="1"}%
%META:TOPICPARENT{name="DeveloperDocumentationCategory"}%
#TemplateTopics
---+ Template topics
Expand All @@ -23,27 +23,16 @@ When you create a new topic using the =edit= script, the system inserts default
#TemplateTopicsVars
---++ Macro expansion

Any Foswiki macro can be automatically expanded during templated topic
creation by prepending =TMPL:= to the macro name. For example,
=%<nop>TMPL:DATE%= will be expanded to the date that the
templated topic was created. SkinTemplates can also be expanded
using =%<nop>TMPL:P{"templatename}%=.

For compatibility with versions of Foswiki < 2.1, when the following macros are used in a template topic, they automatically get expanded when a new topic is created based on it:
When the following macros are used in a template topic, they automatically get expanded when new topic is created based on it:

| *Macro:* | *Description:* |
| =%<nop>DATE%= | Signature format date. See VarDATE |
| =%<nop>GMTIME%= | Date/time. See VarGMTIME |
| =%<nop>GMTIME{...}%= | Formatted date/time. See VarGMTIME |
| =%<nop>NOP%= | A no-operation macro that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as =%<nop>URLPA%<nop>NOP%RAM{...}%= escaping URLPARAM |
| =%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%= | Text that gets removed when a new topic based on the template topic is created. See notes below. |
| =%<nop>STARTSECTION{type="expandvariables"}%%BR%...%BR%%<nop>ENDSECTION{type="expandvariables"}%= | All Foswiki macros enclosed in this section type are expanded when a new topic based on the template topic is created. Otherwise only the macros listed in this table are expanded. |
| =%<nop>SERVERTIME%= | Date/time. See VarSERVERTIME |
| =%<nop>SERVERTIME{...}%= | Formatted date/time. See VarSERVERTIME |
| =%<nop>USERNAME%= | Login username of user who is instantiating the new topic, e.g. <nop>%USERNAME% (On some systems this will be the same as the !WikiName). |
| =%<nop>URLPARAM{"name"}%= | Value of a named URL or HTTP POST parameter |
| =%<nop>WIKINAME%= | WikiName of user who is creating the new topic, e.g. <nop>%WIKINAME% |
| =%<nop>WIKIUSERNAME%= | User name of user who is creating the new topic, e.g. <nop>%WIKIUSERNAME% |

All other macros - including macros defined by plugins - can be expanded when creating a new topic by prefixing =CREATE:= to the macro name. For example, =%<nop>CREATE:DATE{...}<nop>%=.

*NOTE* For compatibility with earlier Foswiki versions, the site administrator can enable the automatic expansion of a subset of macros when a new topic is created from a template _even without CREATE_. The affected macros are =DATE, GMTIME, SERVERTIME, USERNAME, URLPARAM, WIKINAME, and WIKIUSERNAME=.

---+++ Macro notes:
<pre class="tml">%<nop>STARTSECTION{type="templateonly"}%%BR%...%BR%%<nop>ENDSECTION{type="templateonly"}%</pre> markers are used to embed text that you _do not_ want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
Expand Down
4 changes: 3 additions & 1 deletion core/data/System/TopicMarkupLanguage.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" date="1434484983" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1487613457" format="1.1" version="1"}%
%META:TOPICPARENT{name="UserDocumentationCategory"}%
---+!! What is !TML?

Expand Down Expand Up @@ -38,6 +38,8 @@ A quick introduction:
and more of it!
</verbatim></verbatim>

* Comments start with =#<nop>{= and end with =}<nop>#=. Comments are not displayed when the topic is viewed, but can be seen when it is edited.

---++ Formatting text

Full list of text formatting capabilities:
Expand Down
5 changes: 3 additions & 2 deletions core/data/System/UsingHTML.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" date="1434484983" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1487618039" format="1.1" version="1"}%
%META:TOPICPARENT{name="UserDocumentationCategory"}%
---++ Using HTML

Expand All @@ -12,7 +12,8 @@ you can write =&lt;strike&gt;deleted text&lt;/strike&gt;= to get <strike>deleted
There are a few usability and technical considerations to keep in mind:
* On collaboration pages, it's better *not* to use HTML, but to use [[wiki syntax]] instead -
this keeps the text uncluttered and easy to edit using the plaintext editor.
* If you _must_ use HTML, use [[http://www.w3.org/TR/xhtml1/][XHTML 1.0 Transitional]] syntax.
* If you _must_ use HTML, try to stick to [[http://www.w3.org/TR/xhtml1/][XHTML 1.0 Transitional]] syntax.
* Even if your site allows it, avoid using Javascript.
* Use =&lt;literal&gt;..&lt;/literal&gt;= tags around blocks of HTML to avoid accidental interpretation of
[[Wiki syntax]] within the HTML.
<div class="foswikiHelp">%X% Script tags may be filtered out, at the discretion of your Wiki administrator.</div>
Expand Down
10 changes: 6 additions & 4 deletions core/lib/Foswiki.pm
View file
Expand Up @@ -3331,7 +3331,7 @@ sub _processMacros {
$text = takeOutBlocks( $text, 'verbatim', $verbatim );

# Remove comments
$text =~ s/#{.*?}#//gs;
$text =~ s/#\{.*?\}#//gs;

my $dirtyAreas = {};
$text = takeOutBlocks( $text, 'dirtyarea', $dirtyAreas )
Expand Down Expand Up @@ -3550,9 +3550,11 @@ sub _expandMacroOnTopicCreation {
# correctly, but you need to think about this if you extend the set of
# tags expanded here.
return
unless $_[0] =~
m/^(URLPARAM|DATE|(SERVER|GM)TIME|(USER|WIKI)NAME|WIKIUSERNAME|USERINFO|TMPL:P)$/
|| $_[0] =~ s/^TMPL://;
unless ( !$Foswiki::cfg{DisableEOTC}
&& $_[0] =~
m/^(URLPARAM|DATE|(SERVER|GM)TIME|(USER|WIKI)NAME|WIKIUSERNAME|USERINFO)$/
)
|| $_[0] =~ s/^CREATE://;

return $this->_expandMacroOnTopicRendering(@_);
}
Expand Down
9 changes: 9 additions & 0 deletions core/lib/Foswiki.spec
View file
Expand Up @@ -2264,6 +2264,15 @@ $Foswiki::cfg{HomeTopicName} = 'WebHome';
# use Foswiki to manually rename the topic in all existing webs*
$Foswiki::cfg{NotifyTopicName} = 'WebNotify';

# **BOOLEAN EXPERT LABEL="Disable automatic macros on template expand"**
# Disable the automatic expansion of certain macros in topic templates, when
# they are used to create a new topic.
# This feature is disabled by default for new installations, but may be
# required for existing installations.
# The affected macros are DATE, GMTIME, SERVERTIME, USERNAME, URLPARAM,
# WIKINAME, and WIKIUSERNAME.
$Foswiki::cfg{DisableEOTC} = $TRUE;

This comment has been minimized.

Sign in to view

Copy link
@MichaelDaum

MichaelDaum May 2, 2017

Member

Please do not add double-negotiations in configuration parameters. Better call it EnableSomething. Btw what does EOTC stand for?

#############################################################################
#---+ Extensions

Expand Down

0 comments on commit 7196d29

Please sign in to comment.