Location: PHPKode > projects > Open Power Template > docs/Opt/extending.functions.html
<!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" lang="pl">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<meta name="robots" content="all" />

	<title>New functions - Open Power Template</title>
	
	<link rel="stylesheet" type="text/css" href="design/generic.css" media="all"  />
	<link rel="stylesheet" type="text/css" href="design/print.css" media="print" />
	<!--[if lte IE 6]><link rel="stylesheet" href="design/ie.css" type="text/css" /><![endif]-->	
	<!--[if IE 7]><link rel="stylesheet" href="design/ie7.css" type="text/css" /><![endif]-->
</head>
<body>

<div id="wrap">
	<div id="header">
		<h1>Open Power Template 2.0</h1>
		<h2>New functions</h2>
		<p class="generated">@ 02.09.2010</p>
		<p class="location"><a href="index.html"><strong>User manual</strong></a> &raquo; <a href="extending.html">Extending OPT</a> &raquo; <a href="extending.functions.html">New functions</a></p>
	</div>
	
	<div id="content"><dl class="location"><dt><a href="extending.html">5. Extending OPT</a><br/>5.2. New functions</dt><dd class="prev">5.1. Introduction to plugins<br/><a href="extending.plugins.html">&laquo; Previous</a></dd><dd class="next">5.3. New blocks<br/><a href="extending.blocks.html">Next &raquo;</a></dd></dl>	<h1>5.2. New functions</h1><p>Functions are the easiest to create and register in OPT, as they have exactly the same form in the templates:</p>

<pre class="php"><span style="color: #000000; font-weight: bold;">function</span> myFunction<span style="color: #009900;">&#40;</span><span style="color: #000088;">$argument1</span><span style="color: #339933;">,</span> <span style="color: #000088;">$argument2</span><span style="color: #009900;">&#41;</span>
<span style="color: #009900;">&#123;</span>
  <span style="color: #666666; font-style: italic;">// do something here</span>
<span style="color: #009900;">&#125;</span> <span style="color: #666666; font-style: italic;">// end myFunction();</span>
&nbsp;
<span style="color: #666666; font-style: italic;">// ...</span>
<span style="color: #000088;">$tpl</span><span style="color: #339933;">-&gt;</span><span style="color: #004000;">register</span><span style="color: #009900;">&#40;</span>Opt_Class<span style="color: #339933;">::</span><span style="color: #004000;">PHP_FUNCTION</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'myFunction'</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'myFunction'</span><span style="color: #009900;">&#41;</span><span style="color: #339933;">;</span></pre>

<h2>Practical tricks</h2>

<p>The functions can either return the value or <strong>echo</strong> it. At the first sight, it gives the same effect in both of cases:</p>

<pre class="xml"><span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span>{myFunction()}<span style="color: #009900;"><span style="color: #000000; font-weight: bold;">&lt;/p<span style="color: #000000; font-weight: bold;">&gt;</span></span></span></pre>

<p>However, if we use the function in a more complex expression:</p>

<pre class="xml">{@variable is myFunction()}</pre>

<p>We will see the difference. In the first case, the function result is saved in the variable, in the second - printed, and the variable contains nothing.</p>

<blockquote class="help">
  <p>Your functions <strong>should</strong> always return the value instead of echoing it, unless you know, what you are doing.</p>
</blockquote>

<h2>Writing aggregate functions</h2>

<p>Open Power Template supports aggregate functions that can operate either on a single value or a container. You can easily write your own aggregate functions, too, using a simple interface provided by <code>Opt_Function</code>:</p>

<pre class="php"><span style="color: #000000; font-weight: bold;">function</span> myAggregateFunction<span style="color: #009900;">&#40;</span><span style="color: #000088;">$item</span><span style="color: #339933;">,</span> <span style="color: #000088;">$argument</span><span style="color: #009900;">&#41;</span>
<span style="color: #009900;">&#123;</span>
    <span style="color: #b1b100;">if</span><span style="color: #009900;">&#40;</span>Opt_Function<span style="color: #339933;">::</span><span style="color: #004000;">isContainer</span><span style="color: #009900;">&#40;</span><span style="color: #000088;">$item</span><span style="color: #009900;">&#41;</span><span style="color: #009900;">&#41;</span>
    <span style="color: #009900;">&#123;</span>
        <span style="color: #b1b100;">return</span> Opt_Function<span style="color: #339933;">::</span><span style="color: #004000;">processContainer</span><span style="color: #009900;">&#40;</span><span style="color: #0000ff;">'myFunction'</span><span style="color: #339933;">,</span> <a href="http://www.php.net/array"><span style="color: #990000;">array</span></a><span style="color: #009900;">&#40;</span><span style="color: #000088;">$item</span><span style="color: #339933;">,</span> <span style="color: #000088;">$argument</span><span style="color: #009900;">&#41;</span><span style="color: #009900;">&#41;</span><span style="color: #339933;">;</span>
    <span style="color: #009900;">&#125;</span>
&nbsp;
    <span style="color: #666666; font-style: italic;">// Do something here with a single value</span>
    <span style="color: #b1b100;">return</span> <span style="color: #000088;">$item</span><span style="color: #339933;">.</span><span style="color: #0000ff;">' '</span><span style="color: #339933;">.</span><span style="color: #000088;">$argument</span><span style="color: #339933;">;</span>
<span style="color: #009900;">&#125;</span> <span style="color: #666666; font-style: italic;">// end myAggregateFunction();</span></pre>

<p>If we notice that the first argument is a valid container (an OPT convention says that the value that we are going to operate on, should be provided as the first argument), we return the value from <code>processContainer()</code> static method. As the first argument, we must provide the name of the function that will modify a single value (usually it will be the same function, but this does not have to be the rule), and as the second one - the list of arguments. Please note that the first item of this array must be the container!</p>

<h2>Registering functions</h2>

<p>During the function registration, we may perform several tricks. As you have probably noticed, we have specified the function name twice. The first name shows, how the function will be named in the template. The second one is the real PHP function name and <strong>it may be any valid PHP code</strong>. In fact, you are allowed to register static methods as OPT functions, namespace elements and many other things:</p>

<pre class="php"><span style="color: #000088;">$tpl</span><span style="color: #339933;">-&gt;</span><span style="color: #004000;">register</span><span style="color: #009900;">&#40;</span>Opt_Class<span style="color: #339933;">::</span><span style="color: #004000;">PHP_FUNCTION</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'myFunction'</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'myClass::myStaticMethod'</span><span style="color: #009900;">&#41;</span><span style="color: #339933;">;</span></pre>

<p>Another interesting feature is the ability to modify the argument order during the template compilation, so that you do not have to create a PHP wrapper function. The order rules are specified before the real PHP function name and are enclosed within <code>#</code>:</p>

<pre class="php"><span style="color: #000088;">$tpl</span><span style="color: #339933;">-&gt;</span><span style="color: #004000;">register</span><span style="color: #009900;">&#40;</span>Opt_Class<span style="color: #339933;">::</span><span style="color: #004000;">PHP_FUNCTION</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'regexReplace'</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'#3,1,2#preg_replace'</span><span style="color: #009900;">&#41;</span><span style="color: #339933;">;</span></pre>

<p>It could be read like this:</p>

<ul>
<li>The first argument in templates must be in the third place in the compiled template.</li>
<li>The second argument - in the first one.</li>
<li>The third one - in the second.</li>
</ul>

<p>We may also specify some optional values:</p>

<pre class="php"><span style="color: #000088;">$tpl</span><span style="color: #339933;">-&gt;</span><span style="color: #004000;">register</span><span style="color: #009900;">&#40;</span>Opt_Class<span style="color: #339933;">::</span><span style="color: #004000;">PHP_FUNCTION</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'foo'</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'#3,1,2:null#foo'</span><span style="color: #009900;">&#41;</span><span style="color: #339933;">;</span></pre>

<p>In this case, the third argument in templates is optional, but in PHP it is required. We must specify the default value (here, <strong>null</strong>) for the compiler then by adding <code>:null</code> to the position number.</p>
<dl class="location location-bottom"><dt>5.2. New functions<br/><a href="extending.html">5. Extending OPT</a></dt><dd class="prev"><a href="extending.plugins.html">&laquo; Previous</a><br/>5.1. Introduction to plugins</dd><dd class="next"><a href="extending.blocks.html">Next &raquo;</a><br/>5.3. New blocks</dd></dl>		</div>
	
	<div id="footer">
		<p>Copyright &copy; <a href="http://www.invenzzia.org/">Invenzzia Group 2008-2009</a></p>
		<p>Available under the terms of license: <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License 1.2</a></p>
		<p>Generated by <strong>TypeFriendly 0.1.4</strong> by <a href="http://www.invenzzia.org/">Invenzzia</a></p>
	</div>
</div>

</body>
</html>
Return current item: Open Power Template