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. 
  </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<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>
   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<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
/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<63>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<61>. 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<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 <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<63>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<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
     <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<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
    <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 <20>ndice del direct<63>rio padre, de esta manera 
     si usted accesa http://www.example.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 <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<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.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<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 <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<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 <filename>setup.php
    </filename>. 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.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<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
-->