smarty/docs/en/programmers/advanced-features/advanced-features-objects.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="advanced.features.objects">
 <title>Objects</title>
 <para>
  Smarty allows access to PHP objects through the templates. There are
 two ways to access them. One way is to
 <link linkend="api.register.object">register objects</link> to the template,
	 then use access them via syntax similar to custom functions. The other way
 is to <link linkend="api.assign">assign objects</link>
 to the templates and access them much like any other
	 assigned variable. The first method has a much nicer template syntax. It
	 is also more secure, as a registered object can be restricted to certain
 methods or properties. However,
 <emphasis role="bold">a registered object cannot be looped over
 or assigned in arrays of objects</emphasis>, etc. The method you choose will be
	 determined by your needs, but use the first method whenever possible to
	 keep template syntax to a minimum.
 </para>
	<para>
  If <link linkend="variable.security">security is enabled</link>,
  no private methods or functions can be accessed
 	(begininning with "_"). If a method and property of the same name exist,
 	the method will be used.
	</para>
	<para>
 	You can restrict the methods and properties that can be accessed by
 	listing them in an array as the third registration parameter.
	</para>
	<para>
	 By default, parameters passed to objects through the templates are passed
  the same way
  <link linkend="language.custom.functions">custom functions</link> get them.
  An associative array is passed
	 as the first parameter, and the smarty object as the second. If you want
	 the parameters passed one at a time for each argument like traditional
	 object parameter passing, set the fourth registration parameter to false.
	</para>
	<para>
	 The optional fifth parameter has only effect with
	 <parameter>format</parameter> being <literal>true</literal>
	 and contains a list of methods that should be treated as
	 blocks. That means these methods have a closing tag in the
	 template
	 (<literal>{foobar->meth2}...{/foobar->meth2}</literal>) and
	 the parameters to the methods have the same synopsis as the
	 parameters for block-function-plugins: They get 4 parameters
	 <parameter>$params</parameter>,
	 <parameter>$content</parameter>,
	 <parameter>&amp;$smarty</parameter> and
	 <parameter>&amp;$repeat</parameter> and they also behave like
	 block-function-plugins.
	</para>
 <example>
  <title>using a registered or assigned object</title>
  <programlisting role="php">
<![CDATA[
<?php
// the object

class My_Object {
	function meth1($params, &$smarty_obj) {
		return "this is my meth1";
	}
}

$myobj = new My_Object;
// registering the object (will be by reference)
$smarty->register_object("foobar",$myobj);
// if we want to restrict access to certain methods or properties, list them
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
// if you want to use the traditional object parameter format, pass a boolean of false
$smarty->register_object("foobar",$myobj,null,false);

// We can also assign objects. Assign by ref when possible.
$smarty->assign_by_ref("myobj", $myobj);

$smarty->display("index.tpl");
?>
]]>
  </programlisting>
  <para>
   And here's how to access your objects in index.tpl:
  </para>
  <programlisting>
<![CDATA[
{* access our registered object *}
{foobar->meth1 p1="foo" p2=$bar}

{* you can also assign the output *}
{foobar->meth1 p1="foo" p2=$bar assign="output"}
the output was {$output}

{* access our assigned object *}
{$myobj->meth1("foo",$bar)}
]]>
  </programlisting>
 </example>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->