MTWikiVar
MTWikiVar is a simple macro package for using and defining Wiki style variables in line and in MT templates. These variables can be simple string substitutitions or functions (as is the case in Wiki).
This plug in is also intended for use with Textile. This has two effects:
$
instead of %
.
MTWikiVar is a text formatter and not just MT tags (although it can be used as an MT
global filter). A patch is available to cause Textile to automatically invoke MTWikiVars
if present.
MTWikiVar also has support for loading external variable definition files inline or in MT templates.
MTWikiVar is intended to provide Wiki like variables for use in Movable Type. The variables are of two types, string variables and function variables. String variables perform simple string substitution - the invocation of the variable are replaced with the string contained in the variable. Function variables cause a PERL subroutine to be called when the variable is used. An argument string can be passed to the subroutine. The subroutine is expected to return a string which is then used to replace the invocation of the variable.
The name of a variable must consist of characters that are alphabetic, digits, dash or underscore. No other characters are permitted.
The variable ``name'' is invoked by the character sequence $name$
. White space is not allowed.
This set of characters is replaced by the value of the variable.
If the variable is a function that takes arguments
it can be invoked with $name(argument)$
. The character pairs <
>, {}
or []
can be used in place of ()
. The argument will be subjected to expansion of any
variables. The argument is always a single string, any further parsing (such as using commas
to separate arguments) is the responsibility of the function. If the argument is ommitted the
function is passed the empty string.
To define the variable ``name'' use the text $name=@value@$
.
@
represents a value delimiter.
This delimiter can be any printable non-whitespace character that is not a
valid variable name character and is not one of
>, )
, ]
, }
.
The end of the definition of the value is signaled by the
delimiter immediately followed by a literal $
. For most delimiters, the terminating
(second) delimiter is the same character as the first. For the delimiters <
, (
, [
and {
the ending delimiter is
>, )
, ]
, }
respectively.
The most common delimiter is "
which makes an assignment look like $text="replacement"$
.
Subsequent occurences of ``$text$
'' is replaced by ``replacement
''.
The actual text of the assignment (everything between the $
characters
and those characters as well) is removed completely the output text.
The value itself is evaluated so that any variables in the value are evaluated. This is intended to allow defining a variable in terms of one or more other variables. However, it does mean that you can define new variables in the value part of a variable definition. This nested define must use a different delimiter than the outer define, limiting the possible recursion depth. Let me be clear that doing that kind of thing is the symptom of a diseased mind and should be avoided, as I can't think of any benefit to doing so.
There is not provision for escaping characters because of the ability to select a
delimiter. In addition to that, a delimiter can be used in the string as long as
it is not immediately followed by the terminating $
. If that's not sufficient then
another variable consisting of just the delimiter can be defined and used to put the
delimiter in to the variable value.
Inline variable definition can only be string variables. Inline definition of function variables is not supported.
You can assign a value to a string variables for use in posts with the MTWikiVarAssign
tag.
The attributes are:
The string value is evaluated against existing variables before assignment to the variable.
You can define a function variable with the MTWikiVarDefun
tag. The attributes are
&
character.
It is also best to use the fully qualified nameto avoid PERL scope issues.
A variable function is passed two arguments upon invocation.
$func(arg1, arg2)$
then the
second argument will be the string ``arg1, arg2''.
The subroutine is expected to return a printable scalar which is used to replace the variable invocation text. If the subroutine doesn't exist then upon use the string ``FUNCTION VARIABLE ERROR'' followed by a more specific error message.
This is a container tag that creates a scope for variable assignment. The set of variables and their values will be the same after this tag as they were before. This is useful for surrounding posts or comments in a template so that variables defined in one post do not carry over to the next post.
This reads a file from disk and processes all inline variable assignments in the file.
The resulting text is discarded. The file name is specified by the attribute ``file
''.
Note: If you want to include a file that uses MT tags to define variables you should use
MTInclude
to pull in those definitions.
WikiVar is built primarily for use inside posts and comments. However, it can be useful to inject PERL code in to MT templates. This tag supports that.
MTWikiVarEval is a container tag. The contents are
This procedure allows WikiVars to generate MT template tags which are then processed by the MT Template mechanisms. One example would be having a WikiVar function that generates MT Template output based on parameters.
If you include this tag in a Movable Type template:
<MTWikiVarVersion$>
it will be replaced with a string representing the version number of the installed version of MTWikiVar, e.g. ``0.2.0''.
To use MTWikiVar as a global filter add the attribute ``wikivar'' to the MT content tag. The value should be empty or a comma separated list of options. The currently available options are
You can manipulate WikiVars from PERL. See the Text::WikiVar.pm file for that API.
Here is some example text illustrating the basic usage.
$Bob="<a href="mailto:bob@nowhere.com">Bob</a>"$ $BobHomePage=(<a href="http://nowhere.com/~bob">Home Page</a>)$ $Bobco='Bob's Organic Software and Vegetables'$
I first met $Bob$ a about 10 years ago. You can check out his biography at his $BobHomePage$. Shortly after I met him he started $Bobco$ to combine his talent for software development with his wife's green thumb. $Bobco$ has been a rousing success, their "free onion with every download" marketing scheme taking the market by storm. I see a good future for $Bob$ and $Bobco$.
After processing, this yields
I first met <a href="mailto:bob@nowhere.com">Bob</a> a about 10 years ago. You can check out his biography at his <a href="http://nowhere.com/~bob">Home Page</a>. Shortly after I met him he started Bob's Organic Software and Vegetables to combine his talent for software development with his wife's green thumb. Bob's Organic Software and Vegetables has been a rousing success, their "free onion with every download" marketing scheme taking the market by storm. I see a good future for <a href="mailto:bob@nowhere.com">Bob</a> and Bob's Organic Software and Vegetables.
This is even easier if you have a fixed set of variables. For instance, you can build a smiley package by creating a set of MTWikeVarAssign tags that define things like $grin$ to correct IMG tag and including that module in your templates.
Other applications include
MTInclude
or MTWikiVarLoad
depending on whether the file uses MT tags or MTWikiVar
inline definitions. If MTWikiVar is then enabled for comments, text strings such as $grin$
(with a suitable definition) would be converted to an image tag. Updating or extending
the set of smileys would be much simpler and not involve modifying MT templates. For
people who prefer smileys that look like :grin:
it's a single character change to
modify WikiVar to use :
instead of $
(this would be done in the Text::Wikivar.pm
file).
$ThisPost(link text)$
to create a link to the current post with the specified text.
There are two processing options that might be useful.
MTWikiVarScope
container tag can prevent cross post or cross comment definitions.
A goal of this project is to integrate in to Brad Choate's MT-Textile plug-in. Although there are other variable package plug-ins available, I am not aware of any that are ``Textile'' in flavor or are designed to work inline. For instance, MTMacro only works best in the template unless the Sanitize specification is modified.
http://bradchoate.com/past/mttextile.php
MT-Textile is a port of Dean Allen's original Textile project to Perl and Movable Type. MT-Textile by itself only translates Textile markup to HTML.
Textile is Dean Allen's ``humane web text generator'', an easy-to-write and easy-to-read shorthand for writing text for the web. An online Textile web application is available at Mr. Allen's site:
http://textism.com/tools/textile/
MTWikiVar works with Movable Type version 2.6 or later.
extlib/Text/WikiVar.pm
.
The ``plugins'' directory should be in the same directory as ``mt.cgi''; if it
doesn't already exist, use your FTP program to create it. Your
installation should look like this:
(mt home)/plugins/MTWikiVar.pl (mt home)/extlib/Text/WikiVar.pmTo activate MTWikiVar on your weblog, you need to edit your MT templates. The easiest way is to add the
wikivar
attribute to
each MT template tag whose contents you wish to apply MTWikiVar
transformations. Obvious tags would include MTEntryTitle
,
MTEntryBody
, and MTEntryMore
. MTWikiVar should work within any
MT content tag.
For example, to apply MTWikiVar to your entries:
<$MTEntry wikivar=""$>
The content of the attribute is used to set options for MTWikiVar processing. See the description under Global Filter above.
To modify Textile to call MTWikiVar automatically if available, you need to modify the
``textile.pm'' file in in the (mt home)/extlib/bradchoate
directory. Depending the
exact version you have, around line 66 are the line
$textile->filter_param($ctx); $str = $textile->process($str);
You need to insert some code between these two lines so it all together looks like
$textile->filter_param($ctx); if (my $wikivar = $MT::Template::Context::Global_filters{'wikivar'}) { $str = $wikivar->($str, "scope", $ctx) if defined $ctx; } $str = $textile->process($str);
It's best to invoke MTWikiVars before Textile processing so that you can use Textile shorthand in the
substitution strings. There can also be issues with Smarty Pants transforming quotes used in
variable assignments to mismatched (left and right) quotes which are not recognized by MTWikiVars.
The use of scope
in the second argument to WikiVar puts the WikiVar processing in a scope so
that variable definitions do not propagate out of the processed text.
MTWikiVar does not currently support any options.
MTWikiVar doesn't detect PRE, CODE or SCRIPT tags. Variable substitutions will occur inside these tags. This may change in the future but the low impact of that occuring and the pontential usefulness plus the cost of implementation weighed to not checking.
Note that you can use $ to substitute for '$'. Using this on one of the surrounding variable '$' marks will prevent substitution.
To file bug reports or feature requests (other than topics listed in the Caveats section above) please send email to:
wikivar@thought-mesh.net
Alan M. Carroll http://thought-mesh.net
Timothy Appnel's article at
http://www.oreillynet.com/pub/a/javascript/2003/03/18/movabletype.html
was very useful in setting up this plug in.
The original goal of this project was to extend Textile. Originally I had hacked the Textile source to define the variables, which makes maintenance difficult. I can now just tweak it enough to have it invoke MTWikiVar.
While doing the design I started working with Wiki and decided to expand the functionality enough to handle Wiki variables as well. This is part of an effort to support Textile formatting in a Wiki.
Copyright (c) 2003 Alan M. Carroll (http://thought-mesh.net/) All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
This software is provided by the copyright holders and contributors ``as is'' and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.