Name

MTWikiVar


Synopsis

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:

MTWikiVar also has support for loading external variable definition files inline or in MT templates.


Description

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.

Using inline

Use a variable inline

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.

Define a variable inline

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.

MT Tag interface

MTWikiVarAssign

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.

MTWikiVarDefun

You can define a function variable with the MTWikiVarDefun tag. The attributes are

A variable function is passed two arguments upon invocation.

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.

MTWikiVarScope

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.

MTWikiVarLoad

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.

MTWikiVarEval

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

  1. All MT tags are evaluated as would have been the case without the container tag.

  2. The text resulting from the previous step is processed by WikiVar.

  3. The text is processed again as MT template code, i.e. all MT tags are evaluated.

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.

MTWikiVarVersion

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''.

Global Filter

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

scope
If this is present then the application of MTWikiVars to the MT content is done is a local scope. This means that inline definitions will work inside the content but will be discarded after the content is processed. This prevents ``cross-talk'' between different posts or comments on the same page.

Programmatic API

You can manipulate WikiVars from PERL. See the Text::WikiVar.pm file for that API.

Examples And Applications

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


Future Work

Options

There are two processing options that might be useful.

MT-Textile Integration

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/


Installation

Movable Type

MTWikiVar works with Movable Type version 2.6 or later.

  1. Copy the ``MTWikiVar.pl'' file into your Movable Type ``plugins'' directory. Copy the ``WikiVar.pm'' file into your MovableType external library directory under ``Text'', i.e. 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.pm

  2. To 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.

Textile

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.


Options

MTWikiVar does not currently support any options.


Caveats

MTWikiVar operates everywhere

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 &#36; to substitute for '$'. Using this on one of the surrounding variable '$' marks will prevent substitution.


Bugs

To file bug reports or feature requests (other than topics listed in the Caveats section above) please send email to:

    wikivar@thought-mesh.net


See Also


Version History

Version 0.3 27 Oct 2003
Some extensions and bug fixes.
Version 0.2 15 Oct 2003
Initial Beta release.


Author

    Alan M. Carroll
    http://thought-mesh.net


Additional Credits

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 and License

    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.