/docs/id/getting-started.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision$ -->
<part id="getting.started">
 <title>Memulai</title>

 <chapter id="what.is.smarty">
  <title>Apa itu Smarty?</title>
  <para>
   Smarty adalah mesin template untuk PHP. Lebih khusus, ia memfasilitasi 
   cara yang bisa diatur untuk memisahkan logika aplikasi dan konten dari 
   penampilannya. Ini jauh lebih baik dijelaskan dalam situasi di mana 
   pemrogram aplikasi dan desainer template memainkan aturan yang berbeda, 
   atau secara umum bukan orang yang sama.
  </para>

  <para>
   Sebagai contoh, katakanlah anda sedang membuat halaman web yang 
   menampilkan artikel koran.
   </para>
   <itemizedlist>
   <listitem><para>
   Artikel <literal>$headline</literal>, <literal>$tagline</literal>,
   <literal>$author</literal> dan <literal>$body</literal> adalah elemen
   konten, tidak berisi informasi mengenai bagaimana akan ditampilkan.
   Ia akan <link linkend="api.assign">dioper</link> ke dalam Smarty
   oleh aplikasi.
   </para></listitem>

   <listitem><para>Kemudian desainer template mengedit template dan 
   menggunakan kombinasi tag HTML dan 
   <link linkend="language.basic.syntax">tag template</link> untuk 
   membentuk presentasi terhadap
   <link linkend="language.syntax.variables">variabel</link> ini dengan
   elemen seperti tabel, div, warna latar belakang, ukuran font, style 
   sheets, svg dll.
   </para></listitem>

   <listitem><para>Suatu hari pemrogram perlu mengubah cara konten 
   artikel diambil (perubahan dalam logika aplikasi). Perubahan 
   ini tidak mempengaruhi desainer template, konten masih akan 
   muncul dalam template persis sama.
   </para></listitem>

   <listitem><para>
   Demikian juga jika desainer template ingin mendesain ulang template 
   seutuhnya, ini tidak memerlukan perubahan logika aplikasi.
   </para></listitem>

   <listitem><para>Oleh karena itu, pemrogram dapat membuat perubahan 
   terhadap logika aplikasi tanpa perlu merestrukturisasi template, dan 
   desainer template bisa membuat perubahan terhadap template tanpa 
   membongkar logika aplikasi.
  </para></listitem>
  </itemizedlist>

  <para>
   Satu tujuan desain Smarty adalah pemisahan logika  bisnis dan logika
   presentasi.
   </para>

   <itemizedlist>
   <listitem><para>
   Ini berarti template tentu saja dapat berisi logika di bawah
   kondisi yang hanya untuk presentasi saja. Hal seperti
   <link linkend="language.function.include">menyertakan</link>
   template lain,
   <link linkend="language.function.cycle">memilih</link> warna baris tabel,
   <link linkend="language.modifier.upper">membesarkan huruf</link> variabel,
   <link linkend="language.function.foreach">mengulang</link> terus
   sebuah data array dan <link linkend="api.display">menampilkannya</link>
   adalah contoh dari logika presentasi.
   </para></listitem>
   <listitem><para>
   Ini tidak
   berarti bahwa Smarty memaksa pemisahan logika bisnis dan presentasi. Smarty 
   tidak mengetahui yang mana adalah yang mana, maka menempatkan logika bisnis
   dalam template adalah anda sendiri yang melakukannya.
    </para></listitem>
   <listitem><para>Juga, jika anda 
   menginginkan <emphasis>tidak ada</emphasis> logika dalam template, anda 
   tentunya dapat melakukannya dengan menetapkan konten cukup ke teks dan 
   variabel saja.
  </para></listitem>
  </itemizedlist>

  <para>
   Salah satu aspek unik mengenai Smarty adalah kompilasi template. Ini
   berartu Smarty membaca file template dan membuat naskah PHP darinya. 
   Sekali dibuat, selanjutnya ia dieksekusi darinya. Oleh karenanya tidak
   ada beban menguraikan file template untuk setiap permintaan, dan setiap 
   template dapat memanfaatkan solusi cache kompilator PHP seperti 
   <ulink url="&url.e-accel;">eAccelerator</ulink>,
   <ulink url="&url.ion-accel;">ionCube</ulink>
   <ulink url="&url.mmcache-accel;">mmCache</ulink>
   atau <ulink url="&url.zend;">Zend Accelerator</ulink>
   adalah beberapa diantaranya.
  </para>
  <para>
   <emphasis role="bold">Beberapa fitur Smarty:</emphasis>
  </para>
  <itemizedlist>
   <listitem>
    <para>
     Sangat cepat.
    </para>
   </listitem>
   <listitem>
    <para>
     Efisien karena pengurai PHP yang mengerjakan pekerjaan beratnya.
    </para>
   </listitem>
   <listitem>
    <para>
     Tidak ada kelebihan penguraian template, hanya sekali mengompilasi.
    </para>
   </listitem>
   <listitem>
    <para>
     Pintar mengenai <link linkend="variable.compile.check">rekompilasi</link>
     hanya file template yang telah diubah.
    </para>
   </listitem>
   <listitem>
    <para>
     Anda dapat membuat dengan mudah <link
     linkend="language.custom.functions">fungsi</link> kustom
     dan <link linkend="language.modifiers">pengubah variabel</link>, agar 
     bahasa template bisa diperluas secara ekstrim.
    </para>
   </listitem>
   <listitem>
    <para>
     Template bisa mengkonfigurasi sintaks tag
     <link linkend="variable.left.delimiter">{pemisah}</link>, agar
     anda dapat menggunakan
     <literal>{$foo}</literal>, <literal>{{$foo}}</literal>,
     <literal>&lt;!--{$foo}--&gt;</literal>, dll.
    </para>
   </listitem>
   <listitem>
    <para>
     Konstruksi <link linkend="language.function.if">
     <literal>{if}..{elseif}..{else}..{/if}</literal></link>
     dioper ke pengurai PHP, maka sintaks ekspresi <literal>{if...}</literal> 
     bisa berupa evaluasi sesederhana atau serumit yang anda 
     inginkan.
    </para>
   </listitem>
   <listitem>
    <para>
     Membolehkan pengulangan tidak terbatas dari 
     <link linkend="language.function.section">
     <varname>sections</varname></link>, <varname>if's</varname> dll.
    </para>
   </listitem>
   <listitem>
    <para>
     Dimungkinkan untuk
     <link linkend="language.function.php">menyertakan kode PHP</link>
     langsung dalam file template anda, meskipun ini mungkin tidak 
     diperlukan (ataupun direkomendasikan) karena mesin
     <link linkend="plugins">dapat dikustomisasi</link>.
    </para>
   </listitem>
   <listitem>
    <para>
     Dukungan built-in <link linkend="caching">caching</link> 
    </para>
   </listitem>
   <listitem>
    <para>
     Bebas sumber <link linkend="template.resources">template</link>
    </para>
   </listitem>
   <listitem>
    <para>
     Fungsi kustom
     <link
     linkend="section.template.cache.handler.func">penanganan cache</link>
    </para>
   </listitem>
   <listitem>
    <para>
     Arsitektur <link linkend="plugins">Plugin</link>
    </para>
   </listitem>
  </itemizedlist>
 </chapter>





 <chapter id="installation">
  <title>Instalasi</title>

  <sect1 id="installation.requirements">
   <title>Persyaratan</title>
   <para>
    Smarty membutuhkan server web yang menjalankan PHP 4.0.6 atau lebih 
    tinggi.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>Instalasi Dasar</title>

   <para>
    Instalasi file librari Smarty yang ada dalam sub direktori
    <filename class="directory">/libs/</filename>  dari
    distributsi. Ini adalah file <filename>.php</filename> yang 
    TIDAK BOLEH diedit. Ia berbagi diantara seluruh aplikasi dan hanya
    diubah ketika anda meingkatkannya ke versi Smarty baru.
   </para>
   <para>Dalam contoh di bawah ini Smarty tarball telah diuraikan ke:
   <itemizedlist>
   <listitem><para>
   <filename class="directory">/usr/local/lib/Smarty-v.e.r/</filename> untuk
   mesin *nix</para></listitem>
   <listitem><para> dan
   <filename class="directory">c:\webroot\libs\Smarty-v.e.r\</filename> untuk
   lingkungan windows.</para></listitem>
   </itemizedlist>
   </para>

   <example>
    <title>File librari Smarty yang Diperlukan</title>
    <screen>
<![CDATA[
Smarty-v.e.r/
   libs/
      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 menggunakan <ulink url="&url.php-manual;define">konstan</ulink>
    PHP bernama <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant>
    </link> yang merupakan <emphasis role="bold">path file sistem lengkap</emphasis>
    ke direktori <filename>libs/</filename> Smarty.
    Pada dasarnya, jika aplikasi anda dapat menemukan file
    <filename>Smarty.class.php</filename>, anda tidak perlu menyetel 
    <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
    karena Smarty akan mengetahui dirinya sendiri.
    Oleh karena itu, jika
    <filename>Smarty.class.php</filename> tidak dalam 
    <ulink url="&url.php-manual;ini.core.php#ini.include-path">include_path</ulink>
    anda, atau anda tidak menyertakan path absolut kepadanya dalam aplikasi
    anda, maka anda harus mendefinisikan <constant>SMARTY_DIR</constant> 
    secara manual.
    <constant>SMARTY_DIR</constant> <emphasis role="bold">harus menyertakan
    akhiran garis miring/</emphasis>.
   </para>


   <informalexample>
   <para>
    Ini adalah bagaimana anda membuat turunan Smarty dalam naskah PHP anda:
   </para>
    <programlisting role="php">
<![CDATA[
<?php
// NOTE: Smarty has a capital 'S'
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    Coba menjalankan naskah di atas. Jika anda mendapatkan kesalahan yang
    mengatakan
    <filename>Smarty.class.php</filename> file could not be found, anda perlu
    melakukan salah satu dari yang berikut:
   </para>

   <example>
    <title>Setel konstan SMARTY_DIR secara manual</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix style (note capital 'S')
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');

// windows style
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// hack version example that works on both *nix and windows
// Smarty is assumend to be in 'includes/' dir under current script
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Sertakan path absolut ke file librari</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix style (note capital 'S')
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');

// windows style
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Tambah path librari ke file <filename>php.ini</filename></title>
     <programlisting role="php">
<![CDATA[
;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;

; *nix: "/path1:/path2"
include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/"

; Windows: "\path1;\path2"
include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"
]]>
</programlisting>
</example>

<example>
    <title>Menambahkan path include dalam naskah PHP dengan
    <literal><ulink url="&url.php-manual;ini-set">ini_set()</ulink></literal></title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/');

// windows
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/');
?>
]]>
    </programlisting>
   </example>

   <para>
    Sekarang file librari itu di tempatnya, waktunya menyiapkan 
    direktori Smarty untuk aplikasi anda:</para>

    <itemizedlist>
    <listitem><para>
    Smarty memerlukan empat direktori yang secara standar bernama 
    <filename class="directory">templates/</filename>,
    <filename class="directory">templates_c/</filename>, <filename
    class="directory">configs/</filename> dan <filename
    class="directory">cache/</filename>
    </para></listitem>

    <listitem><para>Setiap dari yang di atas tersebut bisa didefinisikan 
    dengan properti kelas Smarty masing-masing
    <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>, dan
    <link linkend="variable.cache.dir">
    <varname>$cache_dir</varname></link>
    </para></listitem>

    <listitem><para>
    It is highly recommended
    that you setup a separate set of these directories for each application
    that will use Smarty
   </para></listitem>
    </itemizedlist>

    <para>
    For our installation example, we will be setting up the Smarty environment
    for a guest book application. We picked an application only for the purpose
    of a directory naming convention. You can use the same environment for any
    application, just replace <literal>guestbook/</literal> with
    the name of your application.
    </para>


   <example>
    <title>What the file structure looks like</title>
    <screen>
<![CDATA[
/usr/local/lib/Smarty-v.e.r/libs/
        Smarty.class.php
        Smarty_Compiler.class.php
        Config_File.class.php
        debug.tpl
        internals/*.php
        plugins/*.php

/web/www.example.com/
        guestbook/
                templates/
                    index.tpl
                templates_c/
                configs/
                cache/
                htdocs/
                    index.php
]]>
    </screen>
   </example>

   <para>
    Be sure that you know the location of your web server's document root as a
    file path. In the following examples, the document root is <filename
    class="directory">/web/www.example.com/guestbook/htdocs/</filename>.
    The Smarty
    directories are only accessed by the Smarty library and never accessed
    directly by the web browser. Therefore to avoid any security concerns, it
    is recommended (but not mandatory) to place these directories
    <emphasis>outside</emphasis> of the web server's document root.
   </para>

   <para>
    You will need as least one file under your document root, and that is the
    script accessed by the web browser. We will name our script
    <filename>index.php</filename>, and place it in a subdirectory under the
    document root <filename class="directory">/htdocs/</filename>.
   </para>


   <para>
    Smarty will need <emphasis role="bold">write access</emphasis>
    (windows users please ignore) to the
    <link linkend="variable.compile.dir">
    <parameter>$compile_dir</parameter></link> and
    <link linkend="variable.cache.dir">
    <parameter>$cache_dir</parameter></link> directories
    (<filename class="directory">templates_c/</filename> and
    <filename class="directory">cache/</filename>), so be sure the web server
    user account can write  to them.

    <note><para>This is usually user <quote>nobody</quote> and
    group <quote>nobody</quote>. For OS X users,
    the default is user <quote>www</quote> and group <quote>www</quote>.
    If you are using Apache, you can  look in your
    <filename>httpd.conf</filename> file to see
    what user and group are being used.</para></note>
    </para>

   <example>
    <title>Permissions and making directories writable</title>
    <programlisting role="shell">
<![CDATA[
chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/

chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/
]]>
    </programlisting>
   </example>

   <note>
    <title>Note</title>
    <para>
     <literal>chmod 770</literal> will be fairly tight security, it only allows
     user <quote>nobody</quote> and group <quote>nobody</quote> read/write access
     to the directories. If you would like to  open up read access to anyone
     (mostly for your own convenience of viewing
     these files), you can use <literal>775</literal> instead.
    </para>
   </note>

   <para>
    We need to create the <filename>index.tpl</filename> file that Smarty will
    display. This needs to be located in the <link linkend="variable.template.dir">
    <parameter>$template_dir</parameter></link>.
   </para>

   <example>
    <title>/web/www.example.com/guestbook/templates/index.tpl</title>
    <screen>
<![CDATA[
{* Smarty *}

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

   <note>
    <title>Technical Note</title>
    <para>
     <literal>{* Smarty *}</literal> is a template
     <link linkend="language.syntax.comments">comment</link>.
     It is not required, but it is good
     practice to start all your template files with this comment. It makes
     the file easy to recognize regardless of the file extension. For
     example, text editors could recognize the file and turn on special
     syntax highlighting.
    </para>
   </note>

   <para>
    Now lets edit <filename>index.php</filename>. We'll create an instance of Smarty,
    <link linkend="api.assign"><varname>assign()</varname></link> a
    template variable and <link linkend="api.display"><varname>display()</varname></link>
    the <filename>index.tpl</filename> file.
   </para>

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

require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty->template_dir = '/web/www.example.com/guestbook/templates/';
$smarty->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
$smarty->config_dir   = '/web/www.example.com/guestbook/configs/';
$smarty->cache_dir    = '/web/www.example.com/guestbook/cache/';

$smarty->assign('name','Ned');

//** un-comment the following line to show the debug console
//$smarty->debugging = true;

$smarty->display('index.tpl');

?>
]]>
    </programlisting>
   </example>

   <note>
    <title>Note</title>
    <para>
     In our example, we are setting absolute paths to all of the Smarty
     directories. If <filename
     class="directory">/web/www.example.com/guestbook/</filename> is
     within your PHP include_path, then these settings are not necessary.
     However, it is more efficient and (from experience) less error-prone to
     set them to absolute paths. This ensures that Smarty is getting files
     from the directories you intended.
    </para>
   </note>

   <para>
    Now naviagate to the <filename>index.php</filename> file with the web browser.
    You should see <emphasis>"Hello Ned, welcome to Smarty!"</emphasis>
   </para>
   <para>
    You have completed the basic setup for Smarty!
   </para>
  </sect1>





  <sect1 id="installing.smarty.extended">
   <title>Extended Setup</title>

   <para>
    This is a continuation of the <link
    linkend="installing.smarty.basic">basic installation</link>, please read
    that first!
   </para>
   <para>
    A slightly more flexible way to setup Smarty is to
    <ulink url="&url.php-manual;ref.classobj">extend the class</ulink> and
    initialize your Smarty environment. So instead of repeatedly setting
    directory paths, assigning the same vars, etc., we can do that in one place.
    </para>
    <para>
    Lets create a new directory <filename
    class="directory">/php/includes/guestbook/</filename>
     and make a new file called <filename>setup.php</filename>. In our example
     environment, <filename class="directory">/php/includes</filename> is in our
     <literal>include_path</literal>.
     Be sure you set this up too, or use absolute file paths.
   </para>

   <example>
    <title>/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/guestbook/templates/';
        $this->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
        $this->config_dir   = '/web/www.example.com/guestbook/configs/';
        $this->cache_dir    = '/web/www.example.com/guestbook/cache/';

        $this->caching = true;
        $this->assign('app_name', 'Guest Book');
   }

}
?>
]]>
    </programlisting>
   </example>

  <para>
   Now lets alter the <filename>index.php</filename> file to use
   <filename>setup.php</filename>:
  </para>

  <example>
   <title>/web/www.example.com/guestbook/htdocs/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>
   Now you see it is quite simple to bring up an instance of Smarty, just use
   <literal>Smarty_GuestBook()</literal> which automatically initializes everything for our
   application.
  </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
-->