mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-28 02:41:37 +01:00
582 lines
19 KiB
XML
582 lines
19 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<part id="getting.started">
|
|
<title>Iniciando</title>
|
|
|
|
<chapter id="what.is.smarty">
|
|
<title>Que es Smarty?</title>
|
|
<para>
|
|
Smarty es un motor de plantillas para PHP. Mas especificamente, esta
|
|
herramienta facilita la manera de separar la aplicación lógica y el
|
|
contenido en la presentación.
|
|
La mejor descripción esta en una situación donde la aplicación
|
|
del programador y la plantilla del diseñador juegan diferentes roles,
|
|
o en la mayoria de los casos no la misma persona.
|
|
</para>
|
|
<para>
|
|
Por ejemplo:
|
|
Digamos que usted crea una pagina web, es decir, despliega el articulo
|
|
de un diario. El encabezado del articulo, el rotulo, el autor y el
|
|
cuerpo son elementos del contenido, estos no contiene información de
|
|
como quieren ser presentados. Estos son pasados por la aplicación
|
|
Smarty, donde el diseñador edita la plantilla, y usa una combinación de
|
|
etiquetas HTML y etiquetas de plantilla para formatear la presentación
|
|
de estos elementos (HTML, tablas, color de fondo, tamaño de letras,
|
|
hojas de estilo, etc...).
|
|
Un día el programador necesita cambiar la manera de recuperar el
|
|
contenido del articulo(un cambio en la aplicación lógica.). Este
|
|
cambio no afectara al diseñador de la plantilla, el contenido llegara a
|
|
la plantilla exactamente igual. De la misma manera, si el diseñador de
|
|
la plantilla quiere rediseñarla en su totalidad, estos cambios no
|
|
afectaran la aplicación lógica.
|
|
Por lo tanto, el programador puede hacer cambios en la aplicación lógica
|
|
sin que sea necesario restructurar la plantilla. Y el diseñador de la
|
|
plantilla puede hacer cambios sin que haya rompimiento con la aplicación
|
|
lógica.
|
|
</para>
|
|
<para>
|
|
One design goal of Smarty is the separation of business logic and
|
|
presentation logic. This means templates can certainly contain logic under
|
|
the condition that it is for presentation only. Things such as including
|
|
other templates, altering table row colors, upper-casing a variable,
|
|
looping over an array of data and displaying it, etc. are all examples of
|
|
presentation logic. This does not mean that Smarty forces a separation of
|
|
business and presentation logic. Smarty has no knowledge of which is which,
|
|
so placing business logic in the template is your own doing. Also, if you
|
|
desire <emphasis>no</emphasis> logic in your templates you certainly can
|
|
do so by boiling the content down to text and variables only.
|
|
</para>
|
|
<para>
|
|
Ahora un pequeño resumen sobre que no hace Smarty. Smarty no intenta
|
|
separar completamente la lógica de la plantilla. No hay problema entre la
|
|
lógica y su plantilla bajo la condición que esta lógica sea
|
|
estrictamente para presentación.
|
|
Un consejo: mantener la aplicación lógica fuera de la plantilla, y la
|
|
presentación fuera de la aplicación lógica.
|
|
Esto tiene como finalidad tener un objeto mas manipulable y escalable para
|
|
un futuro proximo.
|
|
</para>
|
|
<para>
|
|
Un único aspecto acerca de Smarty es la compilación de la plantilla.
|
|
De esta manera Smarty lee la plantilla y crea los scripts de PHP. Una vez
|
|
creados, son executados sobre él.
|
|
Por consiguiente no existe ningún costo por analizar gramaticalmente
|
|
cada archivo de template por cada requisición, y cada template puede llevar
|
|
toda la ventaja del compilador de cache de PHP tal como Zend Accelerator
|
|
(<ulink url="&url.zend;">&url.zend;</ulink>) o PHP Accelerator
|
|
(<ulink url="&url.php-accelerator;">&url.php-accelerator;</ulink>).
|
|
</para>
|
|
<para>
|
|
Algunas de las características de Smarty:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Es extremamente rápido.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Es eficiente ya que puede interpretar el trabajo mas sucio.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
No analiza gramaticalmente desde arriba el template, solo compila una vez.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
El esta atento para solo recompilar los archivos de plantilla que fueron
|
|
cambiados.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Usted puede crear <link linkend="language.custom.functions">
|
|
funciones habituales </link>
|
|
y <link linkend="language.modifiers">modificadores de variables </link>
|
|
customizados, de modo que el lenguaje de la platilla es altamente extensible.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Sintaxis de etiquetas delimitadoras para configuración de la plantilla,
|
|
así lo puede usar {}, {{}}, <!--{}-->, etc.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Los construtoress if/elseif/else/endif son pasados por el interpretador
|
|
de PHP, así la sintaxis de la expresión {if ...} puede ser compleja o
|
|
simple de la forma que usted quiera.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Permite un anidamiento ilimitado de sections, ifs, etc.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Es posible incrustar directamente codigo PHP en los archivos de plantilla,
|
|
aunque esto puede no ser necesario(no recomendado) dado que la herramienta
|
|
se puede ajustar.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Soporte de caching incrustado
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Fuentes de Plantilla absoluto
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Funciones habituales de manipulación de cache
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Arquitectura de Plugin
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</chapter>
|
|
<chapter id="installation">
|
|
<title>Instalación</title>
|
|
|
|
<sect1 id="installation.requirements">
|
|
<title>Requerimentos</title>
|
|
<para>
|
|
Smarty Requiere un servidor web corriendo PHP 4.0.6 o posterior.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="installing.smarty.basic">
|
|
<title>Instalación Básica</title>
|
|
<para>
|
|
Instale los archivos de la libreria de Smarty que estan en el directorio
|
|
de distribución /libs/.
|
|
Estos son los archivos PHP que usted NO EDITARA. Estos archivos son toda
|
|
las aplicaciones comunes y ellos son actualizados cuando usted actualiza
|
|
a una nueva versión de Smarty.
|
|
</para>
|
|
<example>
|
|
<title>Archivos de la libreria Smarty</title>
|
|
<screen>
|
|
<![CDATA[
|
|
Smarty.class.php
|
|
Smarty_Compiler.class.php
|
|
Config_File.class.php
|
|
debug.tpl
|
|
/internals/*.php (all of them)
|
|
/plugins/*.php (all of them)
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<para>
|
|
Smarty utiliza una constante de PHP llamada <link
|
|
linkend="constant.smarty.dir">SMARTY_DIR</link> que es la ruta para
|
|
el directorio de la biblioteca de Smarty 'libs/'. Basicamente, si su
|
|
aplicación puede encontrar el archivo <filename>Smarty.class.php
|
|
</filename>, usted no necesita definir <link linkend="constant.smarty.dir">SMARTY_DIR</link>,
|
|
Smarty lo encontrará. Por consiguiente si, <filename>Smarty.class.php
|
|
</filename> no esta incluido en el path, y no es abastecido por
|
|
una ruta absoluta para encontrar su aplicación, entonces usted
|
|
debe definir SMARTY_DIR manualmente. SMARTY_DIR <emphasis>debe
|
|
</emphasis> incluir una barra de seguimento.
|
|
</para>
|
|
<para>
|
|
Aquí esta un ejemplo de como se crea una instancia de Smarty en sus
|
|
scripts PHP:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Creando una instancia Smarty de Smarty</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Intente correr el script de arriba. Si usted obtiene un error diciendo que
|
|
el archivo <filename>Smarty.class.php</filename>
|
|
no fue encontrado, puedes usar una de las siguientes opciones:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Reemplazar por la ruta absulta de la libreria del archivo</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
require('/usr/local/lib/php/Smarty/Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Adicionar el directorio de la libreria para incluirlo en el
|
|
include_path de PHP</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Edite su archivo php.ini, y adicione el directorio de la libreria de Smarty
|
|
// include_path y reinicie su servidor web.
|
|
// Entonces lo siguiente debe funcionar:
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Defina la constante SMARTY_DIR manualmente</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
|
|
require(SMARTY_DIR . 'Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Ahora que la libreria de archivos esta en su sitio, es tiempo
|
|
de configurar los directorios de Smarty para su aplicación.
|
|
</para>
|
|
<para>
|
|
Smarty require cuatro directorios (por defaul) llamados
|
|
<filename class="directory">'templates/'</filename>,
|
|
<filename class="directory">'templates_c/'</filename>,
|
|
<filename class="directory">'configs/'</filename> y
|
|
<filename class="directory">'cache/'</filename>.
|
|
</para>
|
|
<para>
|
|
Cada uno de estos son para definir las propiedades de las clases de Smarty.
|
|
<link linkend="variable.template.dir">
|
|
<varname>$template_dir</varname></link>,
|
|
<link linkend="variable.compile.dir">
|
|
<varname>$compile_dir</varname></link>,
|
|
<link linkend="variable.config.dir">
|
|
<varname>$config_dir</varname></link>, y
|
|
<link linkend="variable.cache.dir">
|
|
<varname>$cache_dir</varname></link> respectivamente.
|
|
Es altamente recomendado que usted configure un grupo
|
|
separado de estos directorios para cada aplicación que utilice de Smarty.
|
|
</para>
|
|
<para>
|
|
Asegurece que usted sabe la ubicación del document root de su servidor
|
|
web. En nuestro ejemplo, el document root esta en
|
|
<filename class="directory">/web/www.example.com/docs/</filename>.
|
|
Los directorios de Smarty solo son
|
|
accesados por la libreria de Smarty y nunca son accesados directamente
|
|
por el navegador. Por consiguiente para evitar cualquier preocupación
|
|
con la seguridad, es recomendado colocar estos directorios
|
|
<emphasis> fuera </emphasis> del document root.
|
|
</para>
|
|
<para>
|
|
Para nuestro ejemplo de instalación, configuraremos el ambiente de Smarty
|
|
para una aplicación de libro de visitas. Escojemos una aplicación solo
|
|
con el proposito de crear un directorio de nombre convencional.
|
|
Usted puede usar el mismo ambiente para cualquier aplicación, solamente
|
|
sustituya "guestbook" con el nombre de su aplicación.
|
|
Nosotros colocaremos nuestros directorios de Smarty dentro de
|
|
<filename class="directory">/web/www.example.com/smarty/guestbook/</filename>.
|
|
</para>
|
|
<para>
|
|
Usted necesita tener por lo menos un archivo dentro de su document root,
|
|
y que sea accesado por el navegador. Nosotros llamamos el script de
|
|
<emphasis>'index.php'</emphasis>, y lo colocamos en un subdirectorio dentro del
|
|
document root llamado <filename class="directory">/guestbook/</filename>.
|
|
</para>
|
|
|
|
<note>
|
|
<title>Nota Técnica: </title>
|
|
<para>
|
|
Es conveniente configurar el servidor de forma que "index.php" pueda
|
|
ser identificado como el índice del directório padre, de esta manera
|
|
si usted accesa http://www.example.com/guestbook/, el script
|
|
index.php será ejecutado sin "index.php" ni la URL.
|
|
En Apache usted puede definir el sitio adicionando "index.php" en el
|
|
final de su configuración del directorio <emphasis>DirectoryIndex</emphasis>
|
|
(separando cada uno con espacios.) como en el ejemplo de httpd.conf.
|
|
</para>
|
|
<para>
|
|
<emphasis>DirectoryIndex
|
|
index.htm index.html index.php index.php3 default.html index.cgi
|
|
</emphasis>
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Veamos nuestra estructura de archivos hasta hora:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Ejemplo de estrutura de archivo</title>
|
|
<screen>
|
|
<![CDATA[
|
|
/usr/local/lib/php/Smarty/Smarty.class.php
|
|
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php
|
|
/usr/local/lib/php/Smarty/Config_File.class.php
|
|
/usr/local/lib/php/Smarty/debug.tpl
|
|
/usr/local/lib/php/Smarty/internals/*.php
|
|
/usr/local/lib/php/Smarty/plugins/*.php
|
|
|
|
/web/www.example.com/smarty/guestbook/templates/
|
|
/web/www.example.com/smarty/guestbook/templates_c/
|
|
/web/www.example.com/smarty/guestbook/configs/
|
|
/web/www.example.com/smarty/guestbook/cache/
|
|
|
|
/web/www.example.com/docs/guestbook/index.php
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>
|
|
Smarty necesitara <emphasis role="bold">permisos de escritura</emphasis>
|
|
(usuarios de windows ingnorar) para
|
|
<link linkend="variable.compile.dir"><emphasis>$compile_dir</emphasis></link> y
|
|
<link linkend="variable.cache.dir"><emphasis>$cache_dir</emphasis></link>,
|
|
esto garantiza que el usuario del servidor pueda escribir en ellos.
|
|
Este es generalmente el usuarios "nobody" y el grupo "nobody".
|
|
Para usuarios con X sistema operativo, el default es "www" y el grupo "www".
|
|
Si usted esta usando Apache, puede ver en su archivo httpd.conf
|
|
(normalmente en "/usr/local/apache/conf/") cual es el usuario y
|
|
grupo que estan siendo usados.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Configurando permisos de archivos</title>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
chown nobody:nobody /web/www.example.com/smarty/guestbook/templates_c/
|
|
chmod 770 /web/www.example.com/smarty/guestbook/templates_c/
|
|
|
|
chown nobody:nobody /web/www.example.com/smarty/guestbook/cache/
|
|
chmod 770 /web/www.example.com/smarty/guestbook/cache/
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<note>
|
|
<title>Nota Técnica: </title>
|
|
<para>
|
|
chmod 770 puede ser una seguridad bastante fuerte, solo le permite al
|
|
usuario "nobody" y al grupo "nobody" acesso de lectura/escritura a los
|
|
directorios. Si usted quiere abrir permiso de lectura a cualquiera
|
|
(en la mayoria de las veces para su propia conveniencia de querer ver
|
|
estos archivos), usted puede usar el 775 en lugar del 770.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Nosotros necesitamos crear el archivo index.tpl, para que Smarty lo
|
|
pueda cargar. Este estara localizado en su
|
|
<link linkend="variable.template.dir">$template_dir</link>.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Editando /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
|
|
<screen>
|
|
<![CDATA[
|
|
|
|
{* Smarty *}
|
|
|
|
Hello, {$name}!
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<note>
|
|
<title>Nota Técnica:</title>
|
|
<para>
|
|
{* Smarty *} Esto es un <link linkend="language.syntax.comments">comentario
|
|
</link> en el template. Este no es obligatorio, pero si una buena practica
|
|
iniciar todos sus archivos de plantilla con estos comentarios.
|
|
Esto hace facilmente reconocibles a los archivos a pesar la extención
|
|
del archivo. Por ejemplo, editores de texto pueden reconocer el archivo
|
|
y habilitar un realce de sintaxis especial.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Ahora vamos a editar el index.php. crearemos una instancia de Smarty,
|
|
daremos valor a las variables del template y mostraremos el archivo
|
|
index.tpl.
|
|
En el ambiente de nuestro ejemplo, "/usr/local/lib/php/Smarty" esta
|
|
dentro de include_path. Asegurese que exista el mismo, o utilice la
|
|
ruta absoluta.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Editando /web/www.example.com/docs/guestbook/index.php</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// load Smarty library
|
|
require('Smarty.class.php');
|
|
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->template_dir = '/web/www.example.com/smarty/guestbook/templates/';
|
|
$smarty->compile_dir = '/web/www.example.com/smarty/guestbook/templates_c/';
|
|
$smarty->config_dir = '/web/www.example.com/smarty/guestbook/configs/';
|
|
$smarty->cache_dir = '/web/www.example.com/smarty/guestbook/cache/';
|
|
|
|
$smarty->assign('name','Ned');
|
|
|
|
$smarty->display('index.tpl');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<note>
|
|
<title>Nota Técnica: </title>
|
|
<para>
|
|
En nuestro ejemplo, estamos configurando rutas absolutas para todos
|
|
los directorios de Smarty.
|
|
Si <filename class="directory">/web/www.example.com/smarty/guestbook/
|
|
</filename> está dentro de su include_path de PHP, entonces estas
|
|
declaraciones no son necesarias. Sin embargo, esto es mas eficiente y
|
|
(por experiencia) tiene menos tendencia a errores en relación a
|
|
determinar las rutas absolutas. Esto garantiza que Smarty esta recibiendo
|
|
los archivos del directorio que usted desea.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Ahora carge el archivo <filename>index.php</filename> desde su navegador web.
|
|
Usted debera ver "Hello, Ned!"
|
|
</para>
|
|
<para>
|
|
Usted a completado la configuracion basica para el Smarty!
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="installing.smarty.extended">
|
|
<title>Expandiendo la configuración</title>
|
|
|
|
<para>
|
|
Esta es una continuación de la <link linkend="installing.smarty.basic">
|
|
instalación básica</link>, por favor lea esta primero!
|
|
</para>
|
|
<para>
|
|
Una forma un poco mas flexible de configurar el Smarty, expandir las
|
|
clases e iniciar su ambiente de Smarty. Es, en vez de configurar rutas
|
|
de directorios repetidamente, asigne esas mismas a variables, etc.,
|
|
nosotros podemos facilitar eso. Vamos a crear un nuevo directorio en
|
|
"/php/includes/guestbook/" y llamemos al nuevo archivo <filename>setup.php
|
|
</filename>. En nuestro ejemplo, "/php/includes" está en nuestro include_path.
|
|
Verifique que usted también lo definio, o utilice rutas absolutas de
|
|
los archivos.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Editando /php/includes/guestbook/setup.php</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// load Smarty library
|
|
require('Smarty.class.php');
|
|
|
|
// The setup.php file is a good place to load
|
|
// required application library files, and you
|
|
// can do that right here. An example:
|
|
// require('guestbook/guestbook.lib.php');
|
|
|
|
class Smarty_GuestBook extends Smarty {
|
|
|
|
function Smarty_GuestBook()
|
|
{
|
|
|
|
// Class Constructor.
|
|
// These automatically get set with each new instance.
|
|
|
|
$this->Smarty();
|
|
|
|
$this->template_dir = '/web/www.example.com/smarty/guestbook/templates/';
|
|
$this->compile_dir = '/web/www.example.com/smarty/guestbook/templates_c/';
|
|
$this->config_dir = '/web/www.example.com/smarty/guestbook/configs/';
|
|
$this->cache_dir = '/web/www.example.com/smarty/guestbook/cache/';
|
|
|
|
$this->caching = true;
|
|
$this->assign('app_name', 'Guest Book');
|
|
}
|
|
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Ahora vamos a modificar el archivo index.php para usar el setup.php:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Editando /web/www.example.com/docs/guestbook/index.php</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
require('guestbook/setup.php');
|
|
|
|
$smarty = new Smarty_GuestBook;
|
|
|
|
$smarty->assign('name','Ned');
|
|
|
|
$smarty->display('index.tpl');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Ahora usted vera que es completamente simple crear una instancia de
|
|
Smarty, solo use Smarty_GuestBook, que automáticamente inicializa todo
|
|
para nuestra aplicación.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
</part>
|
|
|
|
<!-- 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
|
|
-->
|