smarty/docs/ru/getting-started.xml

<?xml version="1.0" encoding="windows-1251"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.18 Maintainer: freespace Status: ready -->
<part id="getting.started">
 <title>Приступая к работе</title>

 <chapter id="what.is.smarty">
   <title>Что такое Smarty?</title>
   <para>
    Smarty - это компилирующий обработчик шаблонов для PHP.
    Говоря более четко, он предоставляет один из инструментов, которые
    позволяет добиться отделения прикладной логики и данных от
    представления. Это очень удобно в ситуациях, когда программист и
    верстальщик шаблона - различные люди.
   </para>
   
   <para>
    Например, скажем, вы создаете страницу, которая показывает газетную
    статью.
   </para>
   <itemizedlist>
    <listitem>
     <para>
      Название статьи, автор и сама статья - элементы, которые не
      содержат никакой информации о том, как они будут представлены. Их
      <link linkend="api.assign">передают</link>
      в Smarty из приложения.
     </para>
    </listitem>
    <listitem>
     <para>
      Затем верстальщик шаблона редактирует
      шаблоны и использует комбинацию тэгов HTML и
      <link linkend="language.basic.syntax">тэгов шаблона</link>,
      чтобы отформатировать представление этих
      <link linkend="language.syntax.variables">переменных</link>,
      содержащих элементы типа таблиц HTML, фоновых цветов, размеров шрифта,
      стилей, SVG и т.д.).
     </para>
    </listitem>
    <listitem>
     <para>
      Однажды программист захочет изменить способ хранения статьи, то есть
      внести изменения в логику приложения.
      Это изменение не вызовет изменений в шаблонах. Содержание будет все еще
      передаваться в шаблон таким же самым способом.
     </para>
    </listitem>
    <listitem>
     <para>
      Аналогично, если верстальщик захочет полностью перепроектировать
      шаблоны, это не потребует никаких изменений в прикладной логике.
     </para>
    </listitem>
    <listitem>
     <para>
      Таким образом, программист может вносить изменения в прикладную логику
      без необходимости изменения шаблонов, а дизайнер шаблонов может
      вносить изменения в шаблоны без вреда для прикладной логики.
     </para>
    </listitem>
   </itemizedlist>

   <para>
    Одно из предназначений Smarty - это отделение логики приложения от
    представления.
   </para>
   
   <itemizedlist>
    <listitem>
     <para>
      Конечно же, шаблоны могут содержать в себе логику, но
      лишь при условии, что эта логика необходима для правильного представления
      данных. Такие задачи, как
      <link linkend="language.function.include">подключение</link>
      других шаблонов,
      <link linkend="language.function.cycle">чередующаяся</link>
      окраска строчек в таблице,
      <link linkend="language.modifier.upper">приведение букв к верхнему
      регистру</link>,
      <link linkend="language.function.foreach">циклический проход</link>
      по массиву для его
      <link linkend="api.display">отображения</link> и т.д. - всё это
      примеры логики представления.
     </para>
    </listitem>
    <listitem>
     <para>
      Тем не менее, не следует полагать, что Smarty заставляет вас разделять
      прикладную логику и логику представления.
      Smarty не видит разницы между этими вещами, так что переносить
      прикладную логику в шаблоны вы можете на свой страх и риск.
     </para>
    </listitem>
    <listitem>
     <para>
      Если же вы считаете, что в шаблоне <emphasis>вообще</emphasis>
      не должно быть логики, вы можете ограничиться использованием чистого
      текста и переменных.
     </para>
    </listitem>
   </itemizedlist>
   
   <para>
    Одна из уникальных возможностей Smarty - компилирование шаблонов. Это
    означает, что Smarty читает файлы шаблонов и создает PHP-код на их основе.
    Код создаётся один раз и потом только выполняется. Поэтому нет
    необходимости в медленной обработке файл шаблона для каждого запроса.
    Каждый шаблон может пользоваться всеми преимуществами таких компиляторов
    PHP и кэшируюших решений, как
    <ulink url="&url.e-accel;">eAccelerator</ulink>,
    <ulink url="&url.ion-accel;">ionCube</ulink>,
    <ulink url="&url.mmcache-accel;">mmCache</ulink>,
    <ulink url="&url.zend-accel;">Zend Accelerator</ulink>
    и прочих.
   </para>
   <para>
    <emphasis role="bold">Некоторые особенности Smarty:</emphasis>
   </para>
   <itemizedlist>
    <listitem>
     <para>
      Он очень быстр.
     </para>
    </listitem>
    <listitem>
     <para>
      Он эффективен, так как обработчик PHP делает за него грязную работу.
     </para>
    </listitem>
    <listitem>
     <para>
      Никакой лишней обработки шаблонов, они компилируются только один раз.
     </para>
    </listitem>
    <listitem>
     <para>
      <link linkend="variable.compile.check">Перекомпилируются</link>
      только те шаблоны, которые изменились.
     </para>
    </listitem>
    <listitem>
     <para>
      Вы можете легко создавать собственные пользовательские <link
      linkend="language.custom.functions">функции</link> и
      <link linkend="language.modifiers">модификаторы переменных</link>,
      что делает язык шаблонов чрезвычайно расширяемым.
     </para>
    </listitem>
    <listitem>
     <para>
      Настраиваемые
      <link linkend="variable.left.delimiter">{разделители}</link> тэгов
      шаблона, то есть вы можете использовать
      <literal>{$foo}</literal>, <literal>{{$foo}}</literal>,
      <literal>&lt;!--{$foo}--&gt;</literal> и т.д.
     </para>
    </listitem>
    <listitem>
     <para>
      Конструкции
      <link linkend="language.function.if">
      <literal>{if}..{elseif}..{else}..{/if}</literal></link>
      передаются обработчику PHP, так что синтаксис выражения
      <literal>{if...}</literal> может быть настолько простым или сложным,
      насколько вам угодно.
     </para>
    </listitem>
    <listitem>
     <para>
      Допустимо неограниченное вложение
      <link linkend="language.function.section">секций</link>,
      условий и т.д.
     </para>
    </listitem>
    <listitem>
     <para>
      Существует возможность
      <link linkend="language.function.php">включения PHP-кода</link>
      прямо в ваш шаблон, однако обычно в этом нет необходимости
      (и это не рекоммендуется), так как движок весьма гибок и
      <link linkend="plugins">расширяем</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      Встроенный механизм <link linkend="caching">кэширования</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      Произвольные источники
      <link linkend="template.resources">шаблонов</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      Пользовательские функции
      <link linkend="section.template.cache.handler.func">кэширования</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      <link linkend="plugins">Компонентная</link> архитектура.
     </para>
    </listitem>
   </itemizedlist>
 </chapter>





 <chapter id="installation">
  <title>Установка</title>

  <sect1 id="installation.requirements">
   <title>Требования</title>
   <para>
    Для установки и работы Smarty необходим веб-сервер с установленным PHP
    версии 4.0.6 или выше.
   </para>
  </sect1>
  <sect1 id="installing.smarty.basic">
    <title>Базовая установка</title>
    <para>
     Скопируйте файлы Smarty, которые находятся в субдиректории
     <filename class="directory">/libs/</filename>
     дистрибутива. Редактировать эти PHP-файлы НЕ СЛЕДУЕТ. Они должны
     использоваться всеми приложениями и изменяться только при обновлении
     Smarty до новой версии.
    </para>
    <para>
     В следующих примерах архив с исходным кодом Smarty был распакован в
     <itemizedlist>
      <listitem>
       <para>
        <filename class="directory">/usr/local/lib/Smarty-v.e.r/</filename>
        для машин под *nix
       </para>
      </listitem>
      <listitem>
       <para>
        и
        <filename class="directory">c:\webroot\libs\Smarty-v.e.r\</filename>
        для машин под Windows.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    
    <example>
     <title>Необходимые файлы библиотеки Smarty</title>
     <screen>
<![CDATA[
Smarty-v.e.r/
    libs/
        Smarty.class.php
        Smarty_Compiler.class.php
        Config_File.class.php
        debug.tpl
        internals/*.php (все файлы)
        plugins/*.php (все файлы)
]]>
     </screen>
    </example>
    <para>
     Smarty использует <ulink url="&url.php-manual;define">константу</ulink> PHP
     <link linkend="constant.smarty.dir">
     <constant>SMARTY_DIR</constant></link>, которая указывает
     <emphasis role="bold">полный путь</emphasis> к директории
     <filename>libs/</filename> из Smarty.
     Обычно, если ваше приложение может
     найти файл <filename>Smarty.class.php</filename>, то нет необходимости
     устанавливать
     <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
      - Smarty сам во всём разберётся.
      Однако, если
     <filename>Smarty.class.php</filename> не может
     быть найден в вашем include_path или вы не указывали абсолютный путь к
     нему в приложении, то вы должны определить
     <constant>SMARTY_DIR</constant> вручную.
     <constant>SMARTY_DIR</constant> <emphasis role="bold">должна включать
     завершающий слэш</emphasis>.
    </para>
    
    <informalexample>
     <para>
      Вот как следует создавать экземпляр объекта Smarty в ваших PHP-скриптах:
     </para>
	 <programlisting role="php">
<![CDATA[
<?php
// Обратите внимание: в слове Smarty буква 'S' должна быть заглавной
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
     </programlisting>
    </informalexample>

    <para>
     Попробуйте выполнить вышеуказанный код. Если Вы получаете ошибку о том,
     что <filename>Smarty.class.php</filename> не найден, попробуйте следующие
     варианты действий:
    </para>

    <example>
     <title>Ручная установка константы SMARTY_DIR</title>
     <programlisting role="php">
<![CDATA[
<?php
// стиль *nix (не забывайте о заглавной 'S')
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');

// стиль windows
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// пример хака для работы одновременно с *nix и windows
// предполагается, что Smarty находится в директории 'includes/' относительно текущего скрипта
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>Передача абсолютного пути к файлам библиотеки</title>
     <programlisting role="php">
<![CDATA[
<?php
// стиль *nix (не забывайте о заглавной 'S')
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');

// стиль windows
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

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

    <example>
     <title>Добавление библиотеки в путь в файле <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>
      Дописывание include_path из PHP-скрипта используя
      <literal><ulink url="&url.e-accel;">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>
    Теперь, когда все файлы находятся на своих местах, пришло время
    установки директорий Smarty в вашем приложении.
   </para>
   <itemizedlist>
    <listitem>
     <para>   
      Smarty нужно четыре директории, которые по умолчанию называются
      <filename class="directory">templates/</filename>,
      <filename class="directory">templates_c/</filename>,
      <filename class="directory">configs/</filename> и
      <filename class="directory">cache/</filename>
     </para>
    </listitem>
    <listitem>
     <para>
      Каждая из них определяется свойствами класса 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> и
      <link linkend="variable.cache.dir">
      <varname>$cache_dir</varname></link> соответственно.
      Настойчиво рекомендуется использовать разные наборы
      этих директорий для каждого приложения, использующего Smarty.
     </para>
    </listitem>
   </itemizedlist>
   
   <para>
    В нашем примере мы будем устанавливать Smarty для некоторой гостевой
    книги. Приложение было выбрано только для того, чтобы использовать его
    имя в именах директорий. Вы можете использовать те же настройки с любым
    другим приложением, просто меняя <literal>guestbook/</literal>
    на имя вашего приложения.
   </para>

   <example>
    <title>Вот как выглядит файловая структура</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>
    Убедитесь, что вы знаете расположение корневой директории документов
    вашего веб-сервера. В следующих примерах, корневой директорией документов
    является <filename
    class="directory">/web/www.example.com/guestbook/htdocs/</filename>.
    Доступ к директориям Smarty происходит только из библиотеки Smarty и
    никогда не происходит через веб-браузер. Поэтому, в целях безопасности
    рекоммендуется располагать эти директории <emphasis>за пределами</emphasis>
    корневой директории документов сервера, хотя это и не обязательно.
   </para>
   <para>
    Вам понадобиться как минимум один файл внутри корневой директории
    документов - это скрипт, вызываемый веб-браузером. Мы назовем наш скрипт
    <filename>index.php</filename> и положим его в поддиректорию внутри
    корневой директории документов <filename class="directory">/htdocs/</filename>.
   </para>
   
   <para>
    Smarty понадобятся <emphasis role="bold">права на запись</emphasis>
    (пользователей Windows это не касается) в директории
    <link linkend="variable.compile.dir">
    <parameter>$compile_dir</parameter></link> и
    <link linkend="variable.cache.dir">
    <parameter>$cache_dir</parameter></link>
    (<filename class="directory">templates_c/</filename> и
    <filename class="directory">cache/</filename>),
    так что убедитесь, что у веб-сервера есть эти права.
    
    <note>
     <para>
      Обычно это пользователь <quote>nobody</quote> и группа
  	  <quote>nobody</quote>. Для пользователей OS X, пользователь по умолчанию
  	  - это <quote>www</quote> и группа - <quote>www</quote>.
  	  Если вы используете Apache, вы можете узнать используемые
  	  имя пользователя и группу из файла <filename>httpd.conf</filename>.
     </para>
    </note>
   </para>

   <example>
    <title>Установка прав доступа к файлам и директориям</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>Примечание</title>
    <para>
     <literal>chmod 770</literal> даёт достаточно жесткую защиту -
     разрешает только пользователю
     <quote>nobody</quote> и группе <quote>nobody</quote> доступ
     на чтение и запись в эти директории.
     Если вы хотите открыть доступ на чтение для всех (обычно для собственного
     удобства при просмотре этих файлов), вы можете использовать значение
     <literal>775</literal>.
    </para>
   </note>

   <para>
    Нам необходимо создать файл <filename>index.tpl</filename>,
    которы будет загружаться Smarty.
    Он будет расположен в
    <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 *}

Привет, {$name}! Добро пожаловать в Smarty!
]]>
    </screen>
   </example>

   <note>
    <title>Техническое замечание</title>
    <para>
     <literal>{* Smarty *}</literal> - это
     <link linkend="language.syntax.comments">комментарий</link> шаблона.
     Он не является обязательным, но его размещение в начале каждого шаблона
     является хорошим тоном. Это позволяет проще различать файлы независимо
     от их расширения. К примеру, текстовые редакторы могут узнавать этот
     файл и включать особенную подсветку синтаксиса.
    </para>
   </note>

   <para>
    Теперь давайте отредактируем <filename>index.php</filename>.
    Мы создадим экземпляр Smarty,
    <link linkend="api.assign">присвоим</link> значение переменной шаблона и
    <link linkend="api.display">отобразим</link> файл
    <filename>index.tpl</filename>.
   </para>

   <example>
    <title>/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', 'Катруська');

//** раскомментируйте следующую строку для отображения отладочной консоли
//$smarty->debugging = true;

$smarty->display('index.tpl');
?>
]]>
    </programlisting>
   </example>

   <note>
    <title>Примечание</title>
    <para>
     В нашем примере мы устанавливаем абсолютные пути ко всем директориям
     Smarty. Если <filename
     class="directory">/web/www.example.com/guestbook/</filename>
     находится в include_path вашего PHP, то эти настройки не обязательны.
     Тем не менее, более эффективным и (из опыта) менее глюкоопасным является
     использование абсолютных путей. Это придаст уверенность в том, что Smarty
     получает файлы из тех директорий, из которых вы хотите.
    </para>
   </note>

   <para>
    Теперь перейдите к файлу <filename>index.php</filename> при помощи вашего
    веб-браузера. Вы должны увидеть надпись
    <emphasis>"Привет, Катруська! Добро пожаловать в Smarty!"</emphasis>
   </para>
   <para>
    Вы закончили базовую установку Smarty!
   </para>
  </sect1>
  <sect1 id="installing.smarty.extended">
   <title>Расширенная установка</title>

   <para>
    Эта глава является продолжением <link
    linkend="installing.smarty.basic">базовой установки</link>; пожалуйста,
    сперва прочитайте её.
   </para>
   <para>
    Немного более гибким способом установки Smarty является
    <ulink url="&url.php-manual;ref.classobj">наследование класса</ulink>
    и инициализация вашего собственного окружения Smarty. Таким образом, вместо
    того, чтобы постоянно устанавливать пути директорий, присваивать одни и те
    же переменные и т.д., мы можем всё это сделать в одном месте.
   </para>
   <para>
    Давайте создадим новую директорию <filename
    class="directory">/php/includes/guestbook/</filename>,а в ней -
    новый файл, который назовем <filename>setup.php</filename>. По условиям
    нашего примера, <filename class="directory">/php/includes</filename>
    находится в <literal>include_path</literal>. Убедитесь, чтобы
    то же самое было и у вас, или используетй абсолютные пути.
   </para>

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

// загружаем библиотеку Smarty
require('Smarty.class.php');

// Файл setup.php - это хорошее место для
// подключения библиотечных файлов вашего приложения,
// вы можете сделать это прямо здесь. Пример:
// require('guestbook/guestbook.lib.php');

class Smarty_GuestBook extends Smarty {

   function Smarty_GuestBook()
   {

        // Конструктор класса.
        // Он автоматически вызывается при создании нового экземпляра.

        $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>
   Теперь давайте изменим <filename>index.php</filename>,
   чтобы он использовал <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>
   Теперь вы видите, что создать экземпляр Smarty довольно просто - нужно лишь
   использовать <literal>Smarty_GuestBook</literal>, который автоматически
   инициализирует все настройки для нашего приложения.
  </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
-->