smarty/docs/it/getting-started.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<part id="getting.started">
 <title>Introduzione</title>

 <chapter id="what.is.smarty">
  <title>Cos'è Smarty?</title>
  <para>
   Smarty è un motore di template per PHP. Più specificatamente, fornisce un
   modo semplice di separare la logica e il contenuto dell'applicazione dalla
   sua presentazione. Questo concetto si può comprendere meglio in una situazione
   in cui il programmatore ed il progettista dei template hanno ruoli diversi,
   o nella maggior parte dei casi non sono la stessa persona. 
  </para>
  <para>
   Per esempio,
   diciamo che dovete creare una pagina web che mostra un articolo di giornale.
   Il titolo, il sommario, l'autore e il corpo dell'articolo sono gli elementi
   del contenuto: non contengono informazioni su come saranno presentati. Vengono
   passati a Smarty dall'applicazione, dopodiché il grafico modifica i template
   e usa una combinazione di tag HTML e tag di template per formattare la
   presentazione di questi elementi (tabelle HTML, colori di sfondo, dimensione
   dei caratteri, fogli di stile ecc.). Un giorno il programmatore ha bisogno 
   di cambiare il sistema in cui viene ottenuto il contenuto dell'articolo (si
   tratta di una modifica alla logica dell'applicazione). Questa modifica non
   influisce sul lavoro del grafico, infatti il contenuto arriverà al template
   esattamente uguale a prima. Allo stesso modo, se il grafico vuole ridisegnare
   completamente il template, questo non richiederà modifica alla logica 
   applicativa. Quindi, il programmatore può fare modifice alla logica senza
   bisogno di ristrutturare i template, e il grafico può modificare i template
   senza rovinare la logica dell'applicazione.
  </para>
  <para>
   Uno degli obiettivi progettuali di Smarty è la separazione della logica di 
   business dalla logica di presentazione. Questo significa che i template possono
   contenere logica, a condizione che tale logica sia esclusivamente relativa alla
   presentazione. Cose come includere un altro template, alternare i colori delle
   righe di tabella, mostrare un dato in maiuscolo, ciclare su un array di dati
   per visualizzarli, ecc., sono tutti esempi di logica di presentazione. Questo non
   significa che Smarty forza una separazione fra la logica di business e quella di
   presentazione. Smarty non può sapere che cosa è una cosa e cosa è l'altra, per
   cui se mettete logica di business nel template sono affari vostri. Inoltre,
   se <emphasis>non volete</emphasis> alcuna logica nei template, potete 
   sicuramente ottenere ciò riducendo il contenuto a solo testo e variabili.
  </para>
  <para>
   Uno degli aspetti caratteristici di Smarty è la compilazione dei template. Questo
   significa che Smarty legge i file dei template e crea script PHP a partire da
   questi. Una volta creati, questi script vengono eseguiti da quel momento in poi:
   di conseguenza si evita una costosa analisi dei template ad ogni richiesta, e
   ogni template può avvantaggiarsi pienamente di strumenti per velocizzare 
   l'esecuzione come Zend Accelerator (<ulink url="&url.zend;">&url.zend;</ulink>) 
   o PHP Accelerator (<ulink url="&url.ion-accel;">&url.ion-accel;</ulink>).
  </para>
  <para>
   Ecco alcune delle funzionalità di Smarty:
  </para>
  <itemizedlist>
   <listitem>
    <para>
     E' estremamente veloce.
    </para>
   </listitem>
   <listitem>
    <para>
     E' efficiente, perché è l'analizzatore di PHP a fare il "lavoro sporco".
    </para>
   </listitem>
   <listitem>
    <para>
     Non c'è sovraccarico per l'analisi del template, che viene compilato una sola volta.
    </para>
   </listitem>
   <listitem>
    <para>
     E' abbastanza furbo da saper ricompilare solo i template che sono stati modificati.
    </para>
   </listitem>
   <listitem>
    <para>
     Potete creare <link linkend="language.custom.functions">funzioni personalizzate</link>
     e <link linkend="language.modifiers">modificatori di variabili</link> personalizzati,
     il che rende il linguaggio dei template estremamente estensibile.
    </para>
   </listitem>
   <listitem>
    <para>
     La sintassi dei tag di delimitazione dei template è configurabile: potete usare
     {}, {{}}, &lt;!--{}--&gt;, ecc.
    </para>
   </listitem>
   <listitem>
    <para>
     I costrutti if/elseif/else/endif vengono passati al PHP, quindi la sintassi delle
     espressioni condizionali può essere semplice o complicata a vostro piacimento.
    </para>
   </listitem>
   <listitem>
    <para>
     E' consentito nidificare in maniera illimitata sezioni, test, ecc.
    </para>
   </listitem>
   <listitem>
    <para>
     E' possibile incorporare direttamente codice PHP nei file di template, sebbene
     non dovrebbe essercene bisogno (e nemmeno è raccomandato), essendo il motore
     così personalizzabile.
    </para>
   </listitem>
   <listitem>
    <para>
     Supporto nativo al caching
    </para>
   </listitem>
   <listitem>
    <para>
     Scelta arbitraria dei sorgenti dei template
    </para>
   </listitem>
   <listitem>
    <para>
     Funzioni personalizzate di gestione della cache
    </para>
   </listitem>
   <listitem>
    <para>
     Architettura a plugin
    </para>
   </listitem>
  </itemizedlist>
 </chapter>
 <chapter id="installation">
  <title>Installazione</title>

  <sect1 id="installation.requirements">
   <title>Requisiti</title>
   <para>
    Smarty necessita di un web server su cui gira PHP 4.0.6 o successivo.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>Installazione di base</title>
   <para>
    Installate i file delle librerie di Smarty che si trovano nella directory
    /libs/ della distribuzione. Questi sono i file PHP che NON DOVETE modificare.
    Sono condivisi da tutte le applicazioni e vengono modificati solo quando
    passate ad una nuova versione di Smarty.
   </para>
   <example>
    <title>File delle librerie di Smarty</title>
    <screen>
<![CDATA[
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/internals/*.php (tutti)
/plugins/*.php (tutti)
]]>
    </screen>
   </example>
   <para>
    Smarty usa una costante PHP chiamata <link
    linkend="constant.smarty.dir">SMARTY_DIR</link> che contiene il path di sistema
    della directory delle librerie di Smarty. Fondamentalmente, se la vostra applicazione
    è in grado di trovare il file <filename>Smarty.class.php</filename>, non avete bisogno
    di impostare SMARTY_DIR, in quanto Smarty la troverà da solo. Tuttavia, se
    <filename>Smarty.class.php</filename> non si trova nel vostro include_path, o se non
    fornite alla vostra applicazione un percorso assoluto per questo file, allora dovete
    definire manualmente SMARTY_DIR. La costante SMARTY_DIR <emphasis>deve</emphasis> 
    contenere uno slash (/) finale.
   </para>
   <para>
    Ecco come creerete un'istanza di Smarty nei vostri script PHP:
   </para>

   <example>
    <title>Creazione di un'istanza di Smarty</title>
    <programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>

   <para>
    Provate a lanciare lo script qui sopra. Se ricevete un errore che dice che
    il file <filename>Smarty.class.php</filename> non si trova, dovete fare una
    delle cose seguenti:
   </para>

   <example>
    <title>Fornire un percorso assoluto al file delle librerie</title>
    <programlisting role="php">
<![CDATA[
<?php
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Aggiungere la directory della libreria all'include_path di PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
// Modificate il file php.ini, aggiungete la directory delle
// librerie di Smarty all'include_path e riavviate il server web.
// A questo punto il codice seguente dovrebbe funzionare:
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Impostare manualmente la costante SMARTY_DIR</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>
    Ora che i file delle librerie sono al loro posto, è ora di impostare le
    directory di Smarty per la vostra applicazione. Smarty necessita di quattro
    directory chiamate (per default) <filename class="directory">templates</filename>,
    <filename class="directory">templates_c</filename>, <filename 
    class="directory">configs</filename> e <filename class="directory">cache</filename>. 
    Ciascuna di queste è definibile dalle proprietà
    della classe Smarty <varname>$template_dir</varname>,
    <varname>$compile_dir</varname>, <varname>$config_dir</varname>, e
    <varname>$cache_dir</varname> rispettivamente. E' altamente raccomandato
    impostare un insieme separato di queste directory per ogni applicazione che
    userà Smarty.
   </para>
   <para>
    Assicuratevi di conoscere il percorso della document root del vostro web 
    server. Nel nostro esempio, la document root è <filename 
    class="directory">/web/www.mydomain.com/docs/</filename>.
    Le directory di Smarty vengono accedute solo dalle librerie di Smarty e mai
    direttamente dal browser. Tuttavia, per evitare problemi di sicurezza, si
    raccomanda di mettere queste directory <emphasis>al di fuori</emphasis> della
    document root.
   </para>
   <para>
    Per la nostra installazione di esempio, imposteremo l'ambiente di Smarty per
    una applicazione di guest book. Abbiamo scelto un'applicazione al solo scopo
    di avere una convenzione per il nome delle directory. Potete usare lo stesso
    ambiente per qualsiasi applicazione, soltanto sostituendo "guestbook" con il
    nome della vostra applicazione. Metteremo le nostre directory di Smarty sotto
    <filename class="directory">/web/www.mydomain.com/smarty/guestbook/</filename>.
   </para>
   <para>
    Avrete bisogno di almeno un file sotto la document root, e quello sarà lo script
    a cui può accedere ilbrowser. Lo chiameremo <filename>index.php</filename>, 
    e lo metteremo in una sottodirectory della document root chiamata <filename 
    class="directory">/guestbook/</filename>.
   </para>

   <note>
    <title>Nota tecnica</title>
    <para>
     Conviene impostare il web server in modo che "index.php" possa essere identificato
     come indice di default della directory, così se provate a richiedere
     "http://www.example.com/guestbook/", lo script index.php verrà eseguito senza
     "index.php" nell'URL. In Apache questo può essere impostato aggiungendo
     "index.php" alla fine dell'impostazione DirectoryIndex (le voci vanno separate
     con uno spazio l'una dall'altra).
    </para>
   </note>

   <para>
    Diamo un'occhiata alla struttura dei file fino ad ora:
   </para>

   <example>
    <title>Esempio di struttura dei file</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 necessita del diritto di scrittura su <emphasis>$compile_dir</emphasis> e su
    <emphasis>$cache_dir</emphasis>, quindi assicuratevi che l'utente del web
    server possa scriverci sopra. Di solito si tratta dell'utente "nobody" e
    gruppo "nobody". Per utenti di OS X, il default è utente "www" e gruppo "www".
    Se usate Apache, potete guardare nel file httpd.conf (di solito in 
    "/usr/local/apache/conf/") per vedere quale utente e gruppo vengono usati.
   </para>

   <example>
    <title>Impostazione dei permessi sui file</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 tecnica</title>
    <para>
     chmod 770 vi garantisce una notevole sicurezza, in quanto consente solo 
     all'utente e al gruppo "nobody" l'accesso in lettura/scrittura alle directory.
     Se volete consentire la lettura a chiunque (soprattutto per vostra comodità,
     se volete guardare questi file), potete impostare invece 775.
    </para>
   </note>

   <para>
    Ora dobbiamo creare il file index.tpl che Smarty caricherà. Si troverà nella
    directory $template_dir.
   </para>

   <example>
    <title>Edit di /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
    <screen>
<![CDATA[

{* Smarty *}

Hello, {$name}!
]]>
    </screen>
   </example>

   <note>
    <title>Nota tecnica</title>
    <para>
     {* Smarty *} è un commento del template. Non è obbligatorio, ma è buona pratica
     iniziare tutti i file di template con questo commento. Rende semplice 
     riconoscere il file, indipendentemente dalla sua estensione. Ad esempio,
     un editor di testo potrebbe riconoscere il file ed attivare una particolare
     evidenziazione della sintassi.
    </para>
   </note>

   <para>
    Ora editiamo index.php. Creeremo un'istanza di Smarty, valorizzeremo una
    variabile del template e faremo il display del file index.tpl. Nel nostro
    ambiente di esempio, "/usr/local/lib/php/Smarty" si trova nell'include_path.
    Assicuratevi che sia così anche per voi, oppure usate percorsi assoluti.
   </para>

   <example>
    <title>Edit di /web/www.example.com/docs/guestbook/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php

// caricamento delle librerie di Smarty
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 tecnica</title>
    <para>
     Nell'esempio stiamo usando percorsi assoluti per tutte le directory
     di Smarty. Se <filename
     class="directory">/web/www.example.com/smarty/guestbook/</filename> fa 
     parte dell'include_path di PHP, questo non è necessario. Comunque, è più
     efficiente e (per esperienza) meno soggetto ad errori usare percorsi
     assoluti. Questo vi garantisce che Smarty prenda i file dalle directory
     giuste.
    </para>
   </note>

   <para>
    Ora richiamate il file <filename>index.php</filename> dal browser. 
    Dovreste vedere "Hello, Ned!"
   </para>
   <para>
    Avete completato l'installazione base di Smarty!
   </para>
  </sect1>
  <sect1 id="installing.smarty.extended">
   <title>Installazione avanzata</title>

   <para>
    Questo è il seguito della <link
    linkend="installing.smarty.basic">installazione di base</link>, siete pregati
    di leggerla prima!
   </para>
   <para>
    Un modo leggermente più flessibile di installare Smarty è di estendere la
    classe e inizializzare il vostro ambiente di Smarty. Così, invece di impostare
    ripetutamente i percorsi delle directory, riassegnare le stesse variabili ecc.,
    possiamo farlo in un unico punto. 
    Creiamo una nuova directory "/php/includes/guestbook/" e un file chiamato
    <filename>setup.php</filename>. Nel nostro ambiente di esempio, "/php/includes" fa parte
    dell'include_path. Assicuratevi che sia così anche per voi, oppure usate percorsi
    assoluti.
   </para>

   <example>
    <title>Edit di /php/includes/guestbook/setup.php</title>
    <programlisting role="php">
<![CDATA[
<?php

// caricamento delle librerie di Smarty
require('Smarty.class.php');

// Il file setup.php è un buon punto dal quale caricare
// le librerie necessarie all'applicazione, quindi
// potete farlo qui. Ad esempio:
// require('guestbook/guestbook.lib.php');

class Smarty_GuestBook extends Smarty {

   function Smarty_GuestBook()
   {

        // Costruttore della Classe. Questi dati vengono automaticamente impostati
        // per ogni nuova istanza.

        $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>
   Ora modifichiamo il file index.php per usare setup.php:
  </para>

  <example>
   <title>Edit di /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>
   Come potete vedere, è molto semplice creare un'istanza di Smarty, basta usare
   Smarty_GuestBook che inizializza automaticamente tutto ciò che serve alla
   nostra applicazione.
  </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
-->