PmWiki | Cookbook / EditMX

Summary: Allow Markup Expressions to be used in the editing of a page

Version: 2008-05-04

Prerequisites:

Status: Alpha

Maintainer: Peter Bowers

Categories: Markup MarkupExpressions

Download: EditMX.php Δ

Questions answered by this recipe

How can I put some sort of "macros" in my templates that will result in the newly created page being individualized?
In general, how can I insert the results of MXes back into the actual text of my page?
Specifically, how can I create a static pagelist (like for a WikiTrail) without typing all the pagenames?
Specifically, how can I insert the contents of pages into my currently-being-edited page without copying/pasting each one individually?
In general, as a pmwiki author I'm tired of typing. How can I make the computer do more of my work? Or, how can I work smarter instead of harder?

Description

Allow the return value of Markup Expressions to be inserted as text in a page.

Installation

Download EditMX.php and place it in your cookbook directory. If you plan on using this recipe for "macros" in your templates then use a conditional like this to actually include it (the array should contain a list of all your template pages):

if (!in_array($pagename, array('MyGroupA.Template', 'MyGroupB.Template')))
    include_once('cookbook/EditMX.php');

$EditTemplatesFmt = '$Group.Template';
if (!preg_match('/.*Template$/',$pagename))
	include_once('cookbook/EditMX.php');

(It is necessary not to have EditMX included on your actual template pages because then every time you edit your template to make a change you lose all your "macros".)

Notes

If you want your MX to be replaced from a template when creating a new page from the template then surround the MX with {ROE(...)} instead of {(...)}. (ROE=Replace On Edit)

If you want your MX to be replaced on save then instead of the usual {(...)} surrounding your MX you will need to use {ROS(...)}. (ROS=Replace On Save)

It is advised to "debug" your MX using {(...)} and only when you are confident of your results to replace it with {ROS(...)}. Otherwise you have to delete the text inserted and re-type your MX from scratch on each iteration of the testing process. This intermediate debugging step is not necessary with the {ROE(...)} MXes because EditMX.php is not included for the template pages (as per installation instructions above).

Examples

Example: Put a date in a template

Place this in the source of your template page:

If this page were created tomorrow instead of today it would be created on this date: {ROE(ftime fmt="%Y-%m-%d" tomorrow)}

Now whenever this template is used to create a new page you will have tomorrow's date in that spot.

Example: Place text in your template dependent on the existence of another page:

Place this in the source of your template:

{ROE(wikish if test -f GroupA.Page1; then; echo "Refer to [[GroupA.Page1]] for more details"; else; echo "Refer to [[Main.Page1]] for more details"; fi)}

Then if GroupA.Page1 exists you can refer to it but otherwise you can refer to another page.

Example: Page List (requires powertools.php)

While editing a page I decide I want a list of pages from the group Test to be inserted at a certain point in my text. I insert my MX so my page looks like this:

Below you have a list of all pages in the Test group
{ROS(pagelist group=Test wrap=inline fmt=#simple)}
And that's all, folks!

And when you go back in to edit the page you will see this:

Below you have a list of all pages in the Test group
* [[Test.Foo]]
* [[Test.Foo2]]
* [[Test.Foo99]]
* [[Test.Foo99x]]
* [[Test.IncludeMyURL]]
* [[Test.NestedIf]]
* [[Test.NewPTV]]
* [[Test.TrailIndexPage]]
And that's all, folks!

Example: Inserting some repetitive text that varies slightly (requires WikiSh)

I would like to insert a paragraph several times but in each paragraph I want a certain location to contain different values (ala mailmerge)

While editing the page enter this text (all on one line - I've divided it here just for formatting purposes):

{ROS(wikish for name in John Sally Jack Sam Brittany Julie; do; echo "Hello, ${name}.  I hope you're having a great day.  By the way, 
I think ${name} is just a beautiful name.  TTFN!"; done)}

After saving, your source will look like this

Hello, John.  I hope you're having a great day.  By the way, I think John is just a beautiful name.  TTFN!
Hello, Sally.  I hope you're having a great day.  By the way, I think Sally is just a beautiful name.  TTFN!
Hello, Jack.  I hope you're having a great day.  By the way, I think Jack is just a beautiful name.  TTFN!
Hello, Sam.  I hope you're having a great day.  By the way, I think Sam is just a beautiful name.  TTFN!
Hello, Brittany.  I hope you're having a great day.  By the way, I think Brittany is just a beautiful name.  TTFN!
Hello, Julie.  I hope you're having a great day.  By the way, I think Julie is just a beautiful name.  TTFN!

(OK, so it's a dumb example - you get the idea and at some point it may come in handy for repetitive text...)

Example: Inserting Pages (requires WikiSh.php)

You want to have the source of several different pages inserted (not included - you want to edit them or delete the other pages or etc) in the current page. Obviously you could go and open up each page individually and copy/paste it into place, but this is a whole lot faster and less error prone.

While editing the target page you will enter this text:

(:linebreaks:)
{ROS(cat --file_prefix:"---PAGENAME---" Test.PageA Test.PageB Test.PageC)}

When viewing the page it will look very similar to an include, but when you go back in and edit the page you will see that the actual text was included (the optional --file_prefix:"PAGENAME" generated the separating lines):

(:linebreaks:)
---Test.PageA---
I am the text from PageA
---Test.PageB---
I am the text from PageB
---Test.PageC---
I am the text from PageC

Example: TextExtract

Example unfinished

Example: A quick calculator while editing (requires WikiSh although something similar could be done with MarkupExprPlus or MarkupExpressionsExtensions)

This page while editing

The result of adding 1 and 2 and 3 and 4 and dividing all that by 2 is {ROS(set -v junk = "(1 + 2 + 3 + 4) / 2")}

Becomes this after saving

The result of adding 1 and 2 and 3 and 4 and dividing all that by 2 is 5

Release Notes

2008-05-04B - Added {ROE(...)} markup
2008-05-04 - Initial release

Contributors

Henrik came up with the idea of using this for $ROEPatterns as well as $ROSPatterns -- it makes this recipe something that could be really useful now... :-)

EditMX