smarty/docs/ru/getting-started.xml

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

 <chapter id="what.is.smarty">
   <title>Что такое Smarty?</title>
   <para>
    Smarty - это компилирующий обработчик шаблонов для PHP и на PHP.
    Говоря более четко, он предоставляет один из инструментов, которые
    позволяет добиться отделения прикладной логики и данных от
    представления. Это очень удобно в ситуациях, когда программист и
    верстальщик шаблона - различные люди.
   </para>
   <para>
    Например, скажем, вы создаете страницу, которая показывает газетную
    статью. Название статьи, автор и сама статья - элементы, которые не
    содержат никакой информации о том, как они будут представлены. Их
    передают в Smarty из приложения, а верстальщик шаблона редактирует
    шаблоны и использует комбинацию тэгов HTML и тэгов шаблона, чтобы
    отформатировать представление этих элементов (таблицы HTML, фоновые
    цвета, размеры шрифта, стиля и т.д.). Однажды программист захочет
    изменить способ хранения статьи (сделать изменения в логике приложения).
    Это изменение не вызовет изменений в шаблонах. Содержание будет все еще
    передаваться в шаблон таким же самым способом.
    Аналогично, если верстальщик захочет полностью перепроектировать
    шаблоны, это не потребует никаких изменений в прикладной логике.
   </para>
   <para>
    Одно из предназначений Smarty - это отделение логики приложения от
    представления. Конечно же, шаблоны могут содержать в себе логику, но
    лишь при условии, что эта логика необходима для правильного представления
    данных. Такие задачи, как подключение других шаблонов, чередующаяся окраска
    строчек в таблице, приведение букв к верхнему регистру, циклический проход
    по массиву для его отображения и т.д. - всё это является примером логики
    представления. Не следует думать, что Smarty заставляет вас разделять
    логику приложения и представление. Smarty не видит разницы между этими
    вещами, так что помещать или не помещать логику приложения в шаблоны -
    решать вам. Если же вы считаете, что в шаблоне <emphasis>вообще</emphasis>
    не должно быть логики, вы можете ограничиться использованием чистого
    текста и переменных.
   </para>
   <para>
    Одна из уникальных возможностей Smarty - компилирование шаблонов. Это
    означает, что Smarty читает файлы шаблонов и создает PHP-код на их основе.
    Код создаётся один раз и потом только выполняется. Поэтому нет
    необходимости обрабатывать файл шаблона для каждого запроса и каждый
    шаблон может пользоваться всеми преимуществами таких кэшируюших решений,
    как Zend Accelerator
   (<ulink url="&url.zend;">&url.zend;</ulink>) или PHP Accelerator
   (<ulink url="&url.php-accelerator;">&url.php-accelerator;</ulink>).
   </para>
   <para>
    Некоторые особенности Smarty:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      Он очень быстр.
     </para>
    </listitem>
    <listitem>
     <para>
      Он эффективен, так как обработчик PHP делает за него грязную работу.
     </para>
    </listitem>
    <listitem>
     <para>
      Никакой лишней обработки шаблонов, они компилируются только один раз.
     </para>
    </listitem>
    <listitem>
     <para>
      Перекомпилируются только те шаблоны, которые изменились.
     </para>
    </listitem>
    <listitem>
     <para>
      Вы можете создавать пользовательские <link
      linkend="language.custom.functions">функции</link>
      и <link
      linkend="language.modifiers">модификаторы</link>, что делает язык
      шаблонов чрезвычайно расширяемым.
     </para>
    </listitem>
    <listitem>
     <para>
      Настраиваемые разделители тэгов шаблона, то есть вы можете
      использовать {}, {{}}, &lt;!--{}--&gt;, и т.д.
     </para>
    </listitem>
    <listitem>
     <para>
      Конструкции if/elseif/else/endif конструкции передаются обработчику PHP,
      так что синтаксис выражения {if ...} может быть настолько простым или
      сложным, насколько вам угодно.
     </para>
    </listitem>
    <listitem>
     <para>
      Допустимо неограниченное вложение секций, условий и т.д.
     </para>
    </listitem>
    <listitem>
     <para>
      Существует возможность включения PHP-кода прямо в ваш шаблон, однако
      обычно в этом нет необходимости (и это не рекоммендуется), так как
      движок весьма гибок и расширяем.
     </para>
    </listitem>
    <listitem>
     <para>
      Встроенный механизм кэширования.
     </para>
    </listitem>
    <listitem>
     <para>
      Произвольные источники шаблонов.
     </para>
    </listitem>
    <listitem>
     <para>
      Пользовательские функции кэширования.
     </para>
    </listitem>
    <listitem>
     <para>
      Компонентная архитектура.
     </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, которые находятся в директории /libs/
     дистрибутива. Редактировать эти файлы НЕ СЛЕДУЕТ. Они должны
     использоваться всеми приложениями и изменяться только при обновлении
     Smarty до новой версии.
    </para>
    <example>
     <title>Файлы библиотеки Smarty</title>
     <screen>
<![CDATA[
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/plugins/*.php (все файлы)
/internals/*.php (все файлы)
]]>
     </screen>
    </example>
    <para>
     Smarty использует константу PHP <link
     linkend="constant.smarty.dir">SMARTY_DIR</link>, которая указывает путь к
     директории библиотеки Smarty. Обычно, если приложение может найти файл
     <filename>Smarty.class.php</filename>, то нет необходимости устанавливать
     SMARTY_DIR. Однако, если <filename>Smarty.class.php</filename> не может
     быть найден в вашем include_path или вы не указывали абсолютный путь к
     нему в приложении, то вы должны определить SMARTY_DIR вручную.
     SMARTY_DIR <emphasis>должен</emphasis> включать завершающий слэш.
    </para>
    <para>
     Вот как следует создавать экземпляр объекта Smarty в ваших PHP-скриптах:
    </para>
	   <example>
     <title>Создание обекта Smarty</title>
     <programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
     </programlisting>
    </example>

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

    <example>
     <title>Укажите абсолютный путь к директории Smarty</title>
     <programlisting role="php">
<![CDATA[
<?php
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;
?>
]]>
     </programlisting>
    </example>

   	<example>
     <title>Добавьте директорию Smarty к include_path</title>
     <programlisting role="php">
<![CDATA[
<?php
// Отредактируйте ваш файл php.ini, добавьте путь к Smarty
// в include_path и перезапустите веб сервер.
// Следующий код должен работать без ошибок:
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
     </programlisting>
    </example>

	   <example>
     <title>Установите значение константы 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>
     Теперь, когда все файлы находятся на своих местах, пришло время
     установки директорий Smarty в вашем приложении. Smarty требует
     четыре директории, которые (по умолчанию) называются
     <filename class="directory">templates</filename>,
     <filename class="directory">templates_c</filename>,
     <filename class="directory">configs</filename> и
     <filename class="directory">cache</filename>. Каждая из
     них определяется свойствами класса Smarty:
     <varname>$template_dir</varname>, <varname>$compile_dir</varname>,
     <varname>$config_dir</varname> и <varname>$cache_dir</varname>
     соответственно. Настойчиво рекомендуется использовать разные наборы
     этих директорий для каждого приложения, использующего Smarty.
    </para>
    <para>
     Убедитесь, что вы знаете расположение корневой директории для документов
     вашего веб-сервера. В нашем примере это <filename
     class="directory">/web/www.example.com/docs/</filename>.
     Так как доступ к директориям Smarty получает только библиотека Smarty
     и они никогда не запрашиваются напрямую веб-браузером, вам рекомендуется
     вынести директории Smarty <emphasis>за пределы</emphasis> корневой
     директории для документов, чтобы избежать лишнего беспокойства
     относительно безопасности.
    </para>
    <para>
     В нашем примере мы будем устанавливать Smarty для некоторой гостевой
     книги. Приложение было выбрано только для того, чтобы использовать его
     имя в именах директорий. Вы можете использовать те же настройки с любым
     другим приложением, просто меняя "guestbook" на имя вашего приложения.
     Мы же разместим наши директории Smarty тут:
     <filename
     class="directory">web/www.example.com/smarty/guestbook/</filename>
    </para>
   <para>
    Вам понадобится как минимум один файл в корневой директории для документов
    - это скрипт, к которому обращается веб-браузер. Мы назовём наш скрипт
    <filename>index.php</filename> и поместим его в поддиректорию
    <filename class="directory">/guestbook/</filename> корневой директории
    для документов.
   </para>

   <note>
    <title>Техническое замечание</title>
    <para>
     Бывает удобно настроить веб-сервер так, чтобы "index.php" расценивался
     как индексный файл дирекотрии по умолчанию, чтобы при запросе страницы
     "http://www.example.com/guestbook/", вызывался скрипт index.php без
     "index.php" в конце адресной строки. В веб-сервере Apache вы можете
     настроить это, добавив "index.php" в конец директивы DirectoryIndex
     (записи разделяются пробелами).
    </para>
   </note>

   <para>
    Давайте взгляним на текущую файловую структуру:
   </para>

   <example>
    <title>Файловая структура примера</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 понадобятся права на запись в <emphasis>$compile_dir</emphasis> и
    <emphasis>$cache_dir</emphasis>, так что убедитесь, что у веб-сервера
    есть эти права. Обычно сервер запущен от имени пользователя "nobody" группы
    "nobody". Для пользователей OS X пользователем по умолчанию является "www"
    группы "www". Если вы используете Apache, вы можете заглянуть в ваш файл
    httpd.conf (который обычно расположен в "/usr/local/apache/conf/") чтобы
    узнать, какой пользователь и группа используются.
   </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>
     chmod 770 даёт достаточно жесткую защиту - разрешает только пользователю
     "nobody" и группе "nobody" доступ на чтение и запись в эти директории.
     Если вы хотите открыть доступ на чтение для всех (обычно для собственного
     удобства при просмотре этих файлов), вы можете использовать значение 775.
    </para>
   </note>

   <para>
    Нам необходимо создать файл index.tpl, которы будет загружаться Smarty.
    Он будет расположен в вашей $template_dir.
   </para>

   <example>
    <title>Редактирование /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
    <screen>
<![CDATA[

{* Smarty *}

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

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

   <para>
    Теперь давайте отредактируем index.php. Мы создадим экземпляр Smarty,
    присвоим значение переменной шаблона и отобразим файл index.tpl.
    В условиях нашего примера, мы поместили "/usr/local/lib/php/Smarty" в
    include_path. Убедитесь, что вы сделали то же самое или используете
    абсолютные пути.
   </para>

   <example>
    <title>Редактироение /web/www.example.com/docs/guestbook/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php

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

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

   <para>
    Эта глава является продолжением <link
    linkend="installing.smarty.basic">базовой установки</link>; пожалуйста,
    сперва прочитайте её.
   </para>
   <para>
    Немного более гибким способом установки Smarty является наследование класса
    и инициализация вашего собственного окружения Smarty. Таким образом, вместо
    того, чтобы постоянно устанавливать пути директорий, присваивать одни и те
    же переменные и т.д., мы можем всё это сделать в одном месте.
    Давайте создадим новую директорию "/php/includes/guestbook/",а в ней -
    новый файл, который назовем <filename>setup.php</filename>. По условиям
    нашего примера, "/php/includes" находится в include_path. Убедитесь, чтобы
    то же самое было и у вас, или используетй абсолютные пути.
   </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/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>
   Теперь давайте изменим index.php, чтобы он использовал setup.php:
  </para>

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