Argument passing and the magic of ar::getvar
In previous examples you've seen multiple uses of the method ar::getvar. This method is at the heart of Ariadne's template calling and request handling system and its workings can seem a bit magical at first.
When calling a template from another template, you can pass an arguments array with named parameters, e.g.:
<pinp> $foo = 'bar';
ar::call('template.html', array('foo' => $foo)); </pinp>
In this second template, you can get a specific named parameter using ar::getvar, e.g.:
<pinp>
$foo = ar::getvar('foo');
echo $foo;
</pinp>
This wil result in 'bar' being echoed, as expected.
However, ar::getvar has some extra tricks. The first one is that you can put parameters into a global scope and ar::getvar will use that if the named parameter is not passed on using ar::call, e.g.:
<pinp>
ar::putvar('foo', 'bar');
ar::call('template.html');
</pinp>
Without any changes to template.html this will still echo 'bar'. But the global scope is only used, if the named parameter is not in the arguments list of ar::call:
<pinp>
ar::putvar('foo','bar');
ar::call('template.html', array('foo' => 'baz'));
</pinp>
Will echo 'baz' instead of 'bar'. With me so far? Let's add another scope.
Ariadne is a Web Application Platform and CMS, so it stands to reason that query parameters to the URL or through POST requests should be easy to get to, and they are. Once again ar::getvar will get them for you. Take for example the following URL:
http://www.example.com/?foo=foobar
Assuming this site is build in Ariadne, this request will be handled by a call to the template 'view.html' on the site root. Ariadne's loader.php script parses the URL and all request parameters and passes them on as call arguments to this template. So if the 'view.html' contains the following code:
<pinp>
$foo = ar::getvar('foo');
echo $foo;
</pinp>
This http request will return 'foobar'.
However, of these three scopes only the global scope, managed by ar::putvar, and the request scope, from either the URL or POST arguments, are automatically available in all templates. Any parameters passed to a template in ar::call are not available in subsequently called templates, unless specifically passed on.
For example, view.html:
<pinp>
ar::call('template.html', array('foo' => 'bar');
</pinp>
template.html:
<pinp>
ar::call('template2.html');
</pinp>
template2.html:
<pinp>
echo ar::getvar('foo');
</pinp>
In this case template2.html will not find the parameter 'foo', since it wasn't passed on by template1.html.
However, if you would add ?foo=bar to the request URL, template2.html would echo 'bar', since it does have access to the request parameters.
Similarly, if view.html called ar::putvar('foo','baz'), template2.html would echo 'baz', regardless of the parameters to the request URL. The global scope has priority over request parameters.
So, how can you tell where a variable originated? The short answer is you can't. However you can check if a variable is available in the request scope or in the template call scope and what its value is in those scopes.
If you absolutely only want the variable sent with the request, use the following code:
<pinp>
$foo = ar('loader')->getvar('foo');
</pinp>
This only looks in the list of parameters for the current loader. This is usually the HTTP loader, used for normal web requests. However Ariadne can be used through FTP, the command line, as a SOAP server and as a WEBDAV server. Each of these has its own loader and its own way of passing on parameters. Using the syntax above makes sure your code works with all of them.
If you really only want to use the http loader to get parameters, you can also do:
<pinp>
$foo = ar('http')->getvar('foo');
</pinp>
Or even:
<pinp>
$foo = ar('http')->getvar('foo', 'POST');
</pinp>
Finally you can also make sure you only get parameters passed on directly to template in ar::call:
<pinp>
$args = ar::getvar('arCallArgs');
$foo = $args['foo'];
</pinp>
Note: ar::getvar('arCallArgs') only works reliably from Ariadne 8.3.2, untill then use getvar('arCallArgs') - without the ar:: prefix
arCallArgs is a special parameter, which always refers to the parameters passed on to the current template through ar::call. In addition it will also contain all request parameters in the first template called, e.g. view.html. This is because the loader.php script parses the request parameters and explicitly calls the view template with them.
In addition the following parameters are usually available for each template call:
arCallFunction | The name of the template called |
arLibrary | The name of the library called, if set. |
arLibraryPath | The path to the current library, if set. |