Issue 55 * August 18th, 2008

The Power of Merge
Create easy-read code using the Merge function

by Jan Schenkel

As we all know by now, Revolution offers a plethora of commands and functions that let us develop applications much faster than any other development tool. One of my favourite bits is the 'merge' function.

Let's face it: no matter how self-documenting Revolution scripts are, the following piece of script can get a bit hard to read.

on mouseUp
   put quote & "Foobar" & quote && the short name of this stack \
   & return & \
   the layer of this card && "/" && the short ID of me into \
end mouseUp

With all those concatenations using single and double ampersands, it isn't exactly pretty (it's also rather nonsensical, but that's not the point of this exercise). Using the 'merge' function, we can turn this into something which I find much more understandable.

on mouseUp
   put merge("[[quote]]Foobar[[quote]] [[the short name of \
   this stack]]") & return & \
   merge("[[the layer of this card]] / [[the short ID \
   of me]]") into tVariable
end mouseUp

Here's what happens when Revolution executes the 'merge' function: it looks for any pair of double square brackets [[expression]] and replaces that chunk with the value of the expression between the brackets. In the above example it replaces [[quote]] with a " (the quote symbol), it replaces [[the short name with this stack]] with the short name of the current stack (you guessed it!)

In the above example, I could have placed everything on a single line, and used the expression [[return]] to insert a new line character, but that would have made the merge string unnecessarily long. The important thing to remember is that you can use any constant, as well as any local or global variable that you have declared in your script, as well as any other one-line expression.

on mouseUp
   put merge("Five times 'pi' is [[5 * pi]]") into \
end mouseUp

But it doesn't end there: you can use entire script snippets surrounded by a pair of <? ... ?> which should look familiar to anyone who ever dabbled with PHP, JSP or ASP. What Revolution does there, is interpret the script snippet, and whatever is 'return'ed it uses to replace that chunk of the text.

on mouseUp
   ask &quot;Enter a number between 1 and 10&quot;
   put merge(&quot;<? if it < 10 then return 5 else 15 \
?>&quot;) into tVariable
end mouseUp

This becomes especially interesting if you save the pre-merge text into a custom property or a field. Let's say we have a field 'Merge text' on the same card as our button, and we put the following text into it:

Your computer is feeling <? if the platform is \
&quot;MacOS&quot; then
   return &quot;green&quot;
   return &quot;red&quot;
end if ?> today - isn&#146;t that <? if the platform is \
&quot;MacOS&quot; then
   return “wonderful&quot;
   return &quot;sad&quot;
end if ?>...

Now let's set the script of our button to:

on mouseUp
   answer merge(field &quot;Merge text&quot;)
end mouseUp

Depending on your platform, you will get a different message. And this isn't the only thing you can do with it - you can use any valid script structure, including 'repeat' loops and even 'try/catch' blocks if you are so inclined. As long as you put a 'return' statement in there somewhere, the script snippet will be replaced with the result that you returned.

There is one limitation, however: the script snippet cannot span across <? ... ?> blocks. This means that the following won't work:

Your computer is feeling <? if the platform is \
&quot;MacOS&quot; then ?>green<? else ?>red<? end if ?>...

But for that sort of feature, we're looking forward to the brand-new PHP-style CGI-engine that was announced at the Revolution Live Conference.

Given what you've seen above, you may think that this primarily useful for constructing web pages, but it has lots of other applications. I use it frequently to put together SQL queries in a meaningful way:

put merge(&quot;SELECT [[theFieldsFraze]] FROM [[theTableName]] \
WHERE [[theWhereClause]]&quot; into theSQLQuery
put revQueryDatabase(theConnection, theSQLQuery) into \

put merge(&quot;INSERT INTO [[theTableName]] \
([[theFieldsList]]) VALUES ([[theValuesList]])&quot; into theSQLQuery
revExecuteSQL theConnection, theSQLQuery

You can also use it to 'merge' raw RTF text files with actual data: make a template in Word, including tables, headers and footers; put in placeholder with variable names or short expressions between double square brackets save that as an RTF document and read them as a text file fill up the variables with your data and call the 'merge' function write the result to another RTF file and use the 'launch' command to open it in Word.

This way you can quickly create documents that your users can open, modify and print.

In my experience, it will also make your scripts a lot more readable and maintainable when you're putting together dynamic 'do' statements. In short, make a friend out of the 'merge' function as it will help you write better, reusable Revolution scripts.

Jan Schenkel is the developer behind Quartam Reports and Quartam PDF Library for Revolution. Find out more at

Runtime Revolution and Quartam Software are happy to make a special offer for RevUp Newsletter Readers: act quickly and get Quartam PDF Library for just $79 instead of the regular list price of $149.

Main Menu What's New