smarty/docs/es/getting-started.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. 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>
   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 {}, {{}}, &lt;!--{}--&gt;, 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
/core/*.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. Basicamente, si su 
    aplicación puede encontrar el archivo <emphasis>Smarty.class.php
    </emphasis>, usted no necesita definir SMARTY_DIR, Smarty lo 
    encontrará. Por consiguiente si, <emphasis>Smarty.class.php
    </emphasis> 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 <emphasis>Smarty.class.php</emphasis>
    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 
// biblioteca 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.
    Smarty require cuatro directorios (por defaul) llamados
    <emphasis>templates</emphasis>, <emphasis>templates_c</emphasis>, 
    <emphasis>configs</emphasis> y <emphasis>cache</emphasis>. Cada 
    uno de estos son para definir las propiedades de las clases de Smarty.
    <emphasis>$template_dir</emphasis>, <emphasis>$compile_dir</emphasis>, 
    <emphasis>$config_dir</emphasis>, y <emphasis>$cache_dir</emphasis>
    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
    "/web/www.mydomain.com/docs/". 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
    "/web/www.mydomain.com/smarty/guestbook/".
   </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 
    "index.php", y lo colocamos en un subdirectorio dentro del document root 
    llamado "/guestbook/".
   </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.mydomain.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 index
     (separando cada uno con espacios.)
    </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/core/*.php
/usr/local/lib/php/Smarty/plugins/*.php

/web/www.mydomain.com/smarty/guestbook/templates/
/web/www.mydomain.com/smarty/guestbook/templates_c/
/web/www.mydomain.com/smarty/guestbook/configs/
/web/www.mydomain.com/smarty/guestbook/cache/

/web/www.mydomain.com/docs/guestbook/index.php
]]>
    </screen>
   </example>

   <para>
    Smarty necesitara permisos de escritura para
    <emphasis>$compile_dir</emphasis> y <emphasis>$cache_dir</emphasis>,
    esto garantiza que el usuario del servidor pueda escribir en ellos.
    Este es generalmente el usuarios "nobody" y el grupo "nobody".
    Para X usuarios de sistema, 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.mydomain.com/smarty/guestbook/templates_c/
chmod 770 /web/www.mydomain.com/smarty/guestbook/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/cache/
chmod 770 /web/www.mydomain.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 $template_dir.
   </para>

   <example>
    <title>Editando /web/www.mydomain.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 comentario 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.mydomain.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.mydomain.com/smarty/guestbook/templates/';
$smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
$smarty->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
$smarty->cache_dir = '/web/www.mydomain.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 '/web/www.mydomain.com/smarty/guestbook/' 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 index.php 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 "setup.php". 
    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.mydomain.com/smarty/guestbook/templates/';
        $this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
        $this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
        $this->cache_dir = '/web/www.mydomain.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.mydomain.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
-->