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<63>n l<>gica y el
   contenido en la presentaci<63>n.  
   La mejor descripci<63>n esta en una situaci<63>n donde la aplicaci<63>n 
   del programador y la plantilla del dise<73>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<63>n de 
   como quieren ser presentados. Estos son pasados por la aplicaci<63>n 
   Smarty, donde el dise<73>ador edita la plantilla, y usa una combinaci<63>n de 
   etiquetas HTML y etiquetas de plantilla para formatear la presentaci<63>n 
   de estos elementos (HTML, tablas, color de fondo, tama<6D>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<63>n l<>gica.).  Este 
   cambio no afectara al dise<73>ador de la plantilla, el contenido llegara a 
   la plantilla exactamente igual. De la misma manera, si el dise<73>ador de 
   la plantilla quiere redise<73>arla en su totalidad, estos cambios no 
   afectaran la aplicaci<63>n l<>gica.  
   Por lo tanto, el programador puede hacer cambios en la aplicaci<63>n l<>gica
   sin que sea necesario restructurar la plantilla.  Y el dise<73>ador de la 
   plantilla puede hacer cambios sin que haya rompimiento con la aplicaci<63>n 
   l<>gica.
  </para>
  <para>
   Ahora un peque<75>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<63>n que esta l<>gica sea
   estrictamente para presentaci<63>n.  
   Un consejo: mantener la aplicaci<63>n l<>gica fuera de la plantilla, y la
   presentaci<63>n fuera de la aplicaci<63>n l<>gica.
   Esto tiene como finalidad tener un objeto mas manipulable y escalable para 
   un futuro proximo.
  </para>
  <para>
   Un <20>nico aspecto acerca de Smarty es la compilaci<63>n de la plantilla.
   De esta manera Smarty lee la plantilla y crea los scripts de PHP. Una vez
   creados, son executados sobre <20>l.  
   Por consiguiente no existe ning<6E>n costo por analizar gramaticalmente 
   cada archivo de template por cada requisici<63>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<65>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<63>n de la plantilla,
     as<61> lo puede usar {}, {{}}, &lt;!--{}--&gt;, etc.
    </para>
   </listitem>
   <listitem>
    <para>
     Los construtoress if/elseif/else/endif son pasados por el interpretador 
     de PHP, as<61> la sintaxis de la expresi<73>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<63>n de cache
    </para>
   </listitem>
   <listitem>
    <para>
     Arquitectura de Plugin
    </para>
   </listitem>
  </itemizedlist>
 </chapter>
 <chapter id="installation">
  <title>Instalaci<EFBFBD>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<EFBFBD>n B<>sica</title>
   <para>
    Instale los archivos de la libreria de Smarty que estan en el directorio 
    de distribuci<63>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<73>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<63>n puede encontrar el archivo <emphasis>Smarty.class.php
    </emphasis>, usted no necesita definir SMARTY_DIR, Smarty lo 
    encontrar<61>. 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<63>n, entonces usted 
    debe definir SMARTY_DIR manualmente.  SMARTY_DIR <emphasis>debe
    </emphasis> incluir una barra de seguimento.
   </para>
   <para>
    Aqu<71> 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<63>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<63>n que utilice de Smarty.
   </para>
   <para>
     Asegurece que usted sabe la ubicaci<63>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<63>n 
    con la seguridad, es recomendado colocar estos directorios
    <emphasis> fuera </emphasis> del document root.
   </para>
   <para>
    Para nuestro ejemplo de instalaci<63>n, configuraremos el ambiente de Smarty 
    para una aplicaci<63>n de libro de visitas. Escojemos una aplicaci<63>n solo 
    con el proposito de crear un directorio de nombre convencional.
    Usted puede usar el mismo ambiente para cualquier aplicaci<63>n, solamente 
    sustituya "guestbook" con el nombre de su aplicaci<63>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 <20>ndice del direct<63>rio padre, de esta manera 
     si usted accesa "http://www.mydomain.com/guestbook/", el script 
     index.php ser<65> ejecutado sin "index.php" ni la URL.
     En Apache usted puede definir el sitio adicionando "index.php" en el 
     final de su configuraci<63>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<63>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<73> 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<63>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<63>n</title>

   <para>
    Esta es una continuaci<63>n de la <link linkend="installing.smarty.basic">
    instalaci<63>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<73> en nuestro include_path.
    Verifique que usted tambi<62>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<6F>ticamente inicializa todo 
   para nuestra aplicaci<63>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
-->