<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Merge::Tags - A summary of the available tags in Merge</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#database_tags">DATABASE TAGS</a></li>
<li><a href="#flow_tags">FLOW TAGS</a></li>
<li><a href="#functional_tags">FUNCTIONAL TAGS</a></li>
<li><a href="#source_tags">SOURCE TAGS</a></li>
<li><a href="#variable_tags">VARIABLE TAGS</a></li>
<li><a href="#security_tags">SECURITY TAGS</a></li>
<li><a href="#date_tags">DATE TAGS</a></li>
<li><a href="#form_and_html_enhancement_tags">FORM AND HTML ENHANCEMENT TAGS</a></li>
<li><a href="#file_tags">FILE TAGS</a></li>
<li><a href="#meta_tags">META TAGS</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>HTML::Merge::Tags - A summary of the available tags in Merge</p>
<p>
</p>
<hr />
<h1><a name="database_tags">DATABASE TAGS</a></h1>
<ul>
<li>
<p><$RDB='[<strong>Database type</strong>:]<strong>Database name</strong>[:<strong>Host</strong>][,<strong>User</strong>[,<strong>Password</strong>]]'></p>
<p>Connect to alternative database. Defaults are taken from the configuration
file. If two parameters are given in the first token, the database type takes
precedence.</p>
<p>Predefined databases from merge.conf can be used like this:</p>
<p><$RDB='SYSTEM'> for system database
If system database (SESSION_DB) is not defined in merge.conf a system wide
definition will apply.</p>
<p><$RDB='DEFAULT'> for the application database as defined
in merge.conf</p>
</li>
<li>
<p><$RS='<strong>SQL statement</strong>'></p>
<p>Perform a non query SQL statement.</p>
</li>
<li>
<p><$RQ='SELECT <strong>SQL statement</strong>'></p>
<p>Perform a query. First row of result is immediately available.
Query can be iterated with <$RLOOP> tags.</p>
</li>
<li>
<p><$RERUN></p>
<p>Re-performs the query.</p>
</li>
<li>
<p><$RLOOP[.LIMIT=<strong>number</strong>]></p>
<p></$RLOOP></p>
<p><$REND></p>
<p>Performs a loop over fetched query elements. Last row remains valid after
iteration.
Iteration number can be limited.</p>
</li>
<li>
<p><$RSQL.<strong>variable</strong>></p>
<p>Dereferences a column from the current fetch. Or in other words
the variable holds the data fetched from data base.</p>
</li>
<li>
<p><$RINDEX></p>
<p>Substitutes for the number of the row currently fetched.</p>
</li>
<li>
<p><$RFETCH></p>
<p>Fetches another row. Increments the index.</p>
</li>
<li>
<p><$RSTATE></p>
<p>Returns the SQL state of the last statement.</p>
</li>
<li>
<p><$REMPTY></p>
<p>Returns a boolean value of whether the last query yielded an empty set.</p>
</li>
<li>
<p><$RDISCONNECT></p>
<p>Destroy an engine. This is used if the DB_DATABASE configuration
variable has been changed using the <$RCFGSET> tag to
recreate the engine with the new parameters.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="flow_tags">FLOW TAGS</a></h1>
<ul>
<li>
<p><$RITERATION.LIMIT=<strong>number</strong>></p>
<p></$RITERATION></p>
<p>Performs a counted loop.</p>
</li>
<li>
<p><$RIF.'<strong>perl code</strong>'></p>
<p><$RELSE> (optional)</p>
<p><$REND_IF></p>
<p></$RIF></p>
<p><$RELSIF.'<strong>perl code</strong>'></p>
<p>Perform the code if the Perl code evaluates to true.</p>
</li>
<li>
<p><$RWHILE.'<strong>perl code</strong>'></p>
<p></$RWHILE></p>
<p><$REND_WHILE></p>
<p>Perform a while loop.</p>
</li>
<li>
<p><$RBREAK></p>
<p>Break out of a loop.</p>
</li>
<li>
<p><$RCONT></p>
<p>Jump to the next iteration of the loop.</p>
</li>
<li>
<p><$RCOUNT.<strong>variable</strong>=<strong>from</strong>:<strong>to</strong>[,<strong>step</strong>]></p>
<p></$RCOUNT></p>
<p>Perform a classic variable iteration loop. All parameters are mandatory.</p>
</li>
<li>
<p><$REXIT></p>
<p>Exit a template in the middle.</p>
</li>
<li>
<p><$RENUMREQ.<strong>iterator variable</strong>=<strong>value variable</strong>></p>
<p>Iterate over all request parameters; each time having the first variable contain the parameter name and the second contain the value.</p>
</li>
<li>
<p><$RENUMQUERY.<strong>iterator variable</strong>=<strong>value variable</strong>></p>
<p>Iterate over all the columns of a query result. each time having the first variable contain the column name and the second contain the data.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="functional_tags">FUNCTIONAL TAGS</a></h1>
<ul>
<li>
<p><$RPIC.<strong>picture type</strong>(<strong>instruction set</strong>).'<strong>string</strong>'></p>
<p><$RPIC.F(<strong>char</strong>).'<strong>string</strong>'></p>
<p>Replace all white spaces by the given char.
e.g., <$RPIC.F(+).'Banana, a yellow energy bomb'>
will yield: Banana,+a+yellow+energy+bomb and so on.</p>
<p><$RPIC.R(<strong>find</strong>=<strong>replace</strong>, ...).'<strong>string</strong>'></p>
<p>Replace tuples of string-to-find/string-to-replace in the
given string.
e.g., <$RPIC.R('na'='ta').'Banana'> will
yield Batata and so on.</p>
<p><$RPIC.C(<strong>find</strong>=<strong>replace</strong>, ...).'<strong>string</strong>'></p>
<p>Change words word-to-find/word-to-replace in the
given string.
e.g., <$RPIC.C('Banana'='Orange').'Banana'> will
yield Orange and so on.</p>
<p><$RPIC.N(<strong>width</strong>.<strong>fraction positions</strong>).'<strong>number</strong>'></p>
<p>Left space pad the number, with a fixed number of decimal places.</p>
<p><$RPIC.N(0<width>).'<strong>number</strong>'></p>
<p>Left zero pad the number, with a fixed number of decimal places.</p>
<p>(Hint, the instruction is equal to <em>printf</em>ing with %<strong>string</strong>f)</p>
<p><$RPIC.NZ(<format>).'<strong>number</strong>'></p>
<p>Substitute a blank for zero. (Mnemonic: zero suppress)</p>
<p><$RPIC.NF(<format>).'<strong>number</strong>'></p>
<p>After formatting the number, add commas.</p>
<p>Z and F may be combined.</p>
<p><$RPIC.A(<width>).'<strong>alphanumeric string</strong>'></p>
<p>Left space pad the number to achieve a width. (Right justify)</p>
<p><$RPIC.A(-<width>).'<strong>alphanumeric string</strong>'></p>
<p>Right space pad the number to achieve a width. (Left justify)</p>
<p><$RPIC.AC(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Capitalize string.</p>
<p><$RPIC.AS(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Convert string to lower case. (Mnemonic: Small)</p>
<p><$RPIC.AP(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Convert string to 'proper' case, ie, first and only first letter
of each word capitalized.</p>
<p><$RPIC.AW(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Trim redundant spaces, ie, convert bulk spaces to one space.</p>
<p><$RPIC.AR(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Trim right spaces.</p>
<p><$RPIC.AL(<format>).'<strong>alphanumeric string</strong>'></p>
<p>Trim left spaces.</p>
<p>L, R and W may be combined, and all combinations may be combined with either
C, S or P.</p>
<p><$RPIC.D(<strong>format</strong>).'<strong>date</strong>'></p>
<p>Format a POSIX time string, requires Date::Format.</p>
<p><$RPIC.X(<strong>number</strong>).'<strong>string</strong>'></p>
<p>Repeats a string the required number of times.</p>
</li>
<li>
<p><$RDECIDE.'<strong>perl code</strong>'?'<strong>string</strong>':'<strong>string</strong>'></p>
<p>Evaluates the code. If true, yields the first string, otherwise the second.</p>
</li>
<li>
<p><$RMAIL.'<strong>From address</strong>','<strong>To address</strong>'[,'<strong>Subject</strong>']></p>
<p></$RMAIL></p>
<p>Send email, using SMTP to a host configured in merge.conf.</p>
</li>
<li>
<p><$RPERL></p>
<p></$RPERL></p>
<p>Embedded Perl code. <code>print()</code> may be used to write HTML or javascript.</p>
<p>you may set HTML::Merge variables (<$RVAR>) using
the setvar function e.g :</p>
<p><code>setvar('test_var',$test1);</code></p>
<p><$RVAR.test_var> will hold the value of Perl variable $test1.</p>
<p>All <strong>merge.conf</strong> settings are available to your Perl code in the
HTML::Merge::Ini name space e.g. :</p>
<p><code>my $path = $HTML::Merge::Ini::MERGE_ABSOLUTE_PATH;</code></p>
</li>
<li>
<p><$RPERL.B></p>
<p></$RPERL></p>
<p>Embedded Perl with <strong>before</strong> processing.</p>
<p>Your Perl code can have HTML::Merge output tags and HTML::Merge::Compile will expand your code before it will be passed to Perl. e.g.:</p>
<p><code>my $buf="<$RVAR.pic>";</code></p>
</li>
<li>
<p><$RPERL.A></p>
<p></$RPERL></p>
<p>Embedded Perl with <strong>after</strong> processing.
HTML::Merge::Compile will process the value returned by your Perl code. e.g.:</p>
<p><code>return "<\$RSET.pic=' \"$buf\" '>";</code></p>
<p>You can use the merge function to enter input to HTML::Merge e.g.:</p>
<p><code>my $data = '<$RSET.full_date =\'' . scalar(localtime()) . '\'>';</code></p>
<p><code>merge($data);</code></p>
</li>
<li>
<p><$RPERL.C></p>
<p></$RPERL></p>
<p>Embedded Perl with after and before processing <strong>combined</strong>.</p>
<p>see <$RPERL.B> for information about before processing and <$RPERL.A> for about after processing.</p>
</li>
<li>
<p><$REVAL.'<strong>perl code</strong>'></p>
<p>Evaluates the code.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="source_tags">SOURCE TAGS</a></h1>
<ul>
<li>
<p><$REM.'<strong>string</strong>'></p>
<p>Add a server side comment.</p>
</li>
<li>
<p><$RTRACE.'<strong>string</strong>'></p>
<p>Send a string to the log file.</p>
</li>
<li>
<p><$RINCLUDE.'<strong>template name</strong>'></p>
<p>Include a template in compile time.</p>
</li>
<li>
<p><$RWEBINCLUDE.'<strong>url</strong>'></p>
<p>Include an external web page in run time.</p>
</li>
<li>
<p><$RSOURCE.'<strong>template</strong>'></p>
<p></$RSOURCE></p>
<p>Generate an Anchor for a source view for a template. e.g,
<$RSOURCE.'<$RTEMPLATE>'>Click here to view
the source for this template</$RSOURCE></p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="variable_tags">VARIABLE TAGS</a></h1>
<ul>
<li>
<p><$RVAR.<strong>variable</strong>></p>
<p>Dereferences a local variable, or a CGI variable. (Precedence to the former).</p>
</li>
<li>
<p><$RSET.<strong>variable</strong>='<strong>perl code</strong>'></p>
<p>Set a variable to the result of a perl code segment.
CGI variables may be overwritten.</p>
</li>
<li>
<p><$RINC.<strong>variable</strong>></p>
</li>
<li>
<p><$RINC.<strong>variable</strong>+<strong>number</strong>></p>
<p><$RINC.<strong>variable</strong>-<strong>number</strong>></p>
<p>Modify a variable.</p>
</li>
<li>
<p><$RPSET.<strong>variable</strong>='<strong>perl code</strong>'></p>
<p><$RPGET.<strong>variable</strong>></p>
<p>Store and retrieve session variables. Must be configured in the configuration
file manually.</p>
</li>
<li>
<p><$RPIMPORT.<strong>variable</strong>></p>
<p>Copy a persistent variable to a local variable, for faster retrieving.
Memory variables work much faster than session variables.</p>
</li>
<li>
<p><$RPEXPORT.<strong>variable</strong>></p>
<p>Copy a regular variable to a persistent variable of the same name.</p>
</li>
<li>
<p><$RPCLEAR></p>
<p>Erases all session variables.</p>
</li>
<li>
<p><$RCFG.<strong>variable</strong>></p>
<p>Retrieve a variable from Merge configuration.</p>
</li>
<li>
<p><$RCFGSET.<strong>variable</strong>='<strong>perl code</strong>'></p>
<p>Forge a temporary value instead of a configuration variable. Does <strong>NOT</strong> change the configuration file!</p>
</li>
<li>
<p><$RCOOKIE.<strong>name</strong>></p>
<p>Retrieve a cookie.</p>
</li>
<li>
<p><$RCOOKIESET.<strong>name</strong>='<strong>perl expression</strong>'></p>
<p><$RCOOKIESET.<strong>name</strong>='<strong>perl expression</strong>',<strong>minutes</strong>></p>
<p><$RCOOKIESET.<strong>name</strong>='<strong>perl expression</strong>',<strong>non numeric</strong>></p>
<p>Set a cookie using a HTTP-EQUIV <META> HTML tag.
The notations are used for setting a permanent cookie,
a cookie with an expire date, and a temporary cookie
that will disappear when the browser exits.</p>
</li>
<li>
<p><$RENV.<strong>variable</strong>></p>
<p>Get an environment variable.</p>
</li>
<li>
<p><$RENVSET.<strong>variable</strong>='<strong>perl code</strong>'></p>
<p>Set an environment variable.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="security_tags">SECURITY TAGS</a></h1>
<p>These tags are valid only if the merge database exists.</p>
<p>IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
These tags are to be used with the Merge security backend which is not written yet.
IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT</p>
<ul>
<li>
<p><$RLOGIN.'<strong>user</strong>','<strong>password</strong>'></p>
<p>Logs in. Tag outputs a boolean value to notify if login was successful or failed.</p>
</li>
<li>
<p><$RAUTH.'<strong>realm</strong>'></p>
<p>Check if the user has permission to a specific realm/key.</p>
</li>
<li>
<p><$RCHPASS.'<strong>new password</strong>'></p>
<p>Change password for the logged in user.</p>
</li>
<li>
<p><$RADDUSER.'<strong>user</strong>','<strong>password</strong>'></p>
<p>Add a new user. Use with CAUTION! Any user running the page could create a user with this tag.
If Merge is running on a user shell machine, configuration and templates should be readable to the web server but not world readable!
Pages using <$RADDUSER> *must* be protected.</p>
</li>
<li>
<p><$RDELUSER.'<strong>user</strong>'></p>
<p>Remove a user.</p>
</li>
<li>
<p><$RJOIN.'<strong>user</strong>','<strong>group</strong>'></p>
<p><$RPART.'<strong>user</strong>','<strong>group</strong>'></p>
<p>Add a user to a group and remove a user from a group, accordingly.</p>
</li>
<li>
<p><$RGRANT.U.'<strong>user</strong>','<strong>realm</strong>'></p>
<p><$RGRANT.G.'<strong>group</strong>','<strong>realm</strong>'></p>
<p>Grant a permission over a realm to a group or a user.</p>
</li>
<li>
<p><$REVOKE.U.'<strong>user</strong>','<strong>realm</strong>'></p>
<p><$REVOKE.G.'<strong>group</strong>','<strong>realm</strong>'></p>
<p>Revoke a permission over a realm from a group or a user.</p>
</li>
<li>
<p><$REQUIRE.'<strong>template name</strong>','<strong>list of possible realms</strong>'></p>
<p>Require users of a specific template to have access for at least one of the templates in the list. (Comma separated)</p>
</li>
<li>
<p><$RUSER></p>
<p>Returns the user name of the currently logged in user.</p>
</li>
<li>
<p><$RNAME></p>
<p>Yield the real name of the currently logged in user.</p>
</li>
<li>
<p><$RTAG></p>
<p>Yield the tag string of the currently logged in user.</p>
</li>
<li>
<p><$RATTACH.'<strong>template</strong>','<strong>subsite</strong>'></p>
<p>Attach a template to a subsite.</p>
</li>
<li>
<p><$RDETACH.'<strong>template</strong>','<strong>subsite</strong>'></p>
<p>Detach a template from a subsite.</p>
</li>
</ul>
<pre>
=head1</pre>
<p>
</p>
<hr />
<h1><a name="date_tags">DATE TAGS</a></h1>
<ul>
<li>
<p><$RDATE></p>
<p><$RDATE,'<strong>number of days ahead</strong>'></p>
<p>Return the date as a YYMDHmS string. For example: 199912312359 is December 31, 1999, at one minute before midnight.
The second parameter gives the date for a few days ahead, or beyond, if given negative.</p>
</li>
<li>
<p><$RSECOND.'<strong>date</strong>'></p>
<p><$RMINUTE.'<strong>date</strong>'></p>
<p><$RHOUR.'<strong>date</strong>'></p>
<p><$RDAY.'<strong>date</strong>'></p>
<p><$RMONTH.'<strong>date</strong>'></p>
<p><$RYEAR.'<strong>date</strong>'></p>
<p>Return the corresponding part of the date given.</p>
</li>
<li>
<p><$RDATEDIFF.D.'<strong>earlier date</strong>','<strong>later date</strong>'></p>
<p><$RDATEDIFF.H.'<strong>earlier date</strong>','<strong>later date</strong>'></p>
<p><$RDATEDIFF.M.'<strong>earlier date</strong>','<strong>later date</strong>'></p>
<p><$RDATEDIFF.S.'<strong>earlier date</strong>','<strong>later date</strong>'></p>
<p>Return the difference between dates, in days, hours, minutes and seconds, correspondingly.</p>
</li>
<li>
<p><$RLASTDAY.'<strong>date</strong>'></p>
<p>Give the last day of month related to the specific date.</p>
</li>
<li>
<p><$RADDDATE.'<strong>date</strong>','<strong>day</strong>','<strong>month</strong>','<strong>year</strong>'></p>
<p>Add the given number of days, then the given number of months and years to the date. Returns a new date.</p>
</li>
<li>
<p><$RDATE2UTC.'<strong>date</strong>'></p>
<p><$RUTC2DATE.'<strong>UNIX epoch time</strong>'></p>
<p>Convert between a date string and a universal UNIX time.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="form_and_html_enhancement_tags">FORM AND HTML ENHANCEMENT TAGS</a></h1>
<ul>
<li>
<p><$RSUBMIT[.'<strong>javascript validation code</strong>']></p>
<p></$RSUBMIT></p>
<p>Create the HTML code for a POST form pointed at the same merge template
it is called from. An optional parameter is passed to the onSubmit
attribute; a typical value would be 'return <em>function</em>()' where <em>function</em>
returns a boolean value.</p>
</li>
<li>
<p><$RTRANSFER.<strong>field name</strong>></p>
<p>Create a HIDDEN input tag, for the parameter with the corresponding name, based on the values the server side parameter with the same name has.
Useful to transfer input fields among pages.</p>
</li>
<li>
<p><$RMULTI.'<strong>iterator variable</strong>'='<strong>form field</strong>'></p>
<p>Iterate over multiple input form fields.</p>
</li>
<li>
<p><$RMERGE></p>
<p>The name of the Merge CGI.</p>
</li>
<li>
<p><$RTEMPLATE></p>
<p>The name of the current template.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="file_tags">FILE TAGS</a></h1>
<ul>
<li>
<p><$RGLOB.F.'<strong>iterator variable</strong>'='<strong>base directory or *</strong>'></p>
<p><$RGLOB.D.'<strong>iterator variable</strong>'='<strong>base directory</strong>'></p>
<p>Iterate over a directory. Produces either files only or directories only, accordingly.</p>
</li>
<li>
<p><$RFTS.'<strong>iterator variable</strong>'='<strong>base directory</strong>'></p>
<p>Iterate over a subtree of files.</p>
</li>
<li>
<p><$RDIVERT.'<strong>buffer name</strong>'>
</$RDIVERT></p>
<p>Divert the output into a named buffer. Buffers are store in temporary
files and do not overlap between processes.
Subsequent diverting is appended to the existing buffer.</p>
</li>
<li>
<p><$RDUMP.'<strong>buffer name</strong>'></p>
<p>Dump the named buffer.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="meta_tags">META TAGS</a></h1>
<ul>
<li>
<p><$RVERSION></p>
<p>Returns Merge version.</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 1999 - 2005 Raz Information Systems Ltd.
<a href="http://www.raz.co.il/">http://www.raz.co.il/</a></p>
<p>This package is distributed under the same terms as Perl itself, see the
Artistic License on Perl's home page.</p>
</body>
</html>