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
  <ulink url="&url.php-manual;object">objects</ulink> through the templates.
  There are two ways to access them.
  </para>

 <itemizedlist spacing="compact">
 <listitem><para>
 One way is to <link linkend="api.register.object">register objects</link> to
 the template, then use access them via syntax similar to
 <link linkend="language.custom.functions">custom functions</link>.
 </para></listitem>
 <listitem><para>
 The other way is to <link linkend="api.assign"><varname>assign()</varname>
 </link> objects to the templates and access them much like any other
	 assigned variable.
 </para></listitem>
 </itemizedlist>

 <para>
    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"><parameter>$security</parameter></link>
  is enabled,  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 &true;
	 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
  <link linkend="plugins.block.functions">
  <varname>block-function-plugins</varname></link>:
 They get the four 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 <filename>index.tpl</filename>:
  </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>
 <para>
  See also <link
  linkend="api.register.object"><varname>register_object()</varname></link>
  and
  <link linkend="api.assign"><varname>assign()</varname></link>.
 </para>
</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
-->