Справочные элементы представления

Написание и сопровождение разметки HTML может быстро стать утомительной задачей из-за соглашений об именовании и множества атрибутов, которые необходимо учитывать. Phalcon решает эту сложность, предлагая Phalcon\Tag, который, в свою очередь, предлагает вспомогательные элементы представления для генерации разметки HTML.

Этот компонент можно использовать в простом представлении HTML+PHP или в шаблоне Volt.

Данное руководство не предназначено для полного описания доступных помощников и их аргументов. Обратитесь к странице Phalcon\Tag в API для получения полной справки.

Тип документа содержимого

Phalcon предоставляет помощник Phalcon\Tag::setDoctype() для установки типа документа содержимого. Установка типа документа может повлиять на вывод HTML, производимый другими вспомогательными элементами тегов. Например, если вы установите семейство типов документов XHTML, помощники, которые возвращают или выводят теги HTML, будут генерировать самозакрывающиеся теги для соответствия стандарту валидного XHTML.

Доступные константы типов документов в пространстве имен Phalcon\Tag:

Константа	Тип документа
HTML32	HTML 3.2
HTML401_STRICT	HTML 4.01 Строгий
HTML401_TRANSITIONAL	HTML 4.01 Переходный
HTML401_FRAMESET	HTML 4.01 Рамка
HTML5	HTML 5
XHTML10_STRICT	XHTML 1.0 Строгий
XHTML10_TRANSITIONAL	XHTML 1.0 Переходный
XHTML10_FRAMESET	XHTML 1.0 Рамка
XHTML11	XHTML 1.1
XHTML20	XHTML 2.0
XHTML5	XHTML 5

Установка типа документа.

<?php $this->tag->setDoctype(\Phalcon\Tag::HTML401_STRICT); ?>

Получение типа документа.

<?= $this->tag->getDoctype() ?>
<html>
<!-- your HTML code -->
</html>

Следующий HTML будет сгенерирован.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
<html>
<!-- your HTML code -->
</html>

Синтаксис Volt:

{{ get_doctype() }}
<html>
<!-- your HTML code -->
</html>

Генерация ссылок

Обычная задача любого веб-приложения или веб-сайта — создание ссылок, позволяющих переходить с одной страницы на другую. При внутренних URL-адресах их можно создать следующим образом:

<!-- for the default route -->
<?= $this->tag->linkTo("products/search", "Search") ?>

<!-- with CSS attributes -->
<?= $this->tag->linkTo(array('products/edit/10', 'Edit', 'class' => 'edit-btn')) ?>

<!-- for a named route -->
<?= $this->tag->linkTo(array(array('for' => 'show-product', 'title' => 123, 'name' => 'carrots'), 'Show')) ?>

На самом деле все сгенерированные URL-адреса генерируются компонентом Phalcon\Mvc\Url (или службой «url», если она доступна).

Те же ссылки, сгенерированные с помощью Volt:

<!-- for the default route -->
{{ link_to("products/search", "Search") }}

<!-- for a named route -->
{{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show') }}

<!-- for a named route with class -->
{{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show','class'=>'edit-btn') }}

Создание форм

Формы в веб-приложениях играют важную роль в получении входных данных пользователя. Следующий пример демонстрирует, как реализовать простую форму поиска с помощью вспомогательных элементов представления:

<!-- Sending the form by method POST -->
<?= $this->tag->form("products/search") ?>
    <label for="q">Search:</label>
    <?= $this->tag->textField("q") ?>
    <?= $this->tag->submitButton("Search") ?>
<?= $this->tag->endForm() ?>

<!-- Specifying another method or attributes for the FORM tag -->
<?= $this->tag->form(array("products/search", "method" => "get")); ?>
    <label for="q">Search:</label>
    <?= $this->tag->textField("q"); ?>
    <?= $this->tag->submitButton("Search"); ?>
<?= $this->tag->endForm() ?>

Этот код сгенерирует следующий HTML:

<form action="/store/products/search/" method="get">
     <label for="q">Search:</label>
     <input type="text" id="q" value="" name="q" />
     <input type="submit" value="Search" />
</form>

Та же форма, сгенерированная в Volt:

<!-- Specifying another method or attributes for the FORM tag -->
{{ form("products/search", "method": "get") }}
    <label for="q">Search:</label>
    {{ text_field("q") }}
    {{ submit_button("Search") }}
{{ endform() }}

Phalcon также предоставляет построитель форм для создания форм объектно-ориентированным способом.

Вспомогательные элементы для генерации элементов форм

Phalcon предоставляет ряд вспомогательных элементов для генерации элементов форм, таких как текстовые поля, кнопки и т. д. Первый параметр каждого помощника всегда — имя генерируемого элемента. При отправке формы имя будет передано вместе с данными формы. В контроллере вы можете получить эти значения, используя то же имя, с помощью методов getPost() и getQuery() объекта запроса ($this->request).

<?php echo $this->tag->textField("username") ?>

<?php echo $this->tag->textArea(array(
    "comment",
    "This is the content of the text-area",
    "cols" => "6",
    "rows" => 20
)) ?>

<?php echo $this->tag->passwordField(array(
    "password",
    "size" => 30
)) ?>

<?php echo $this->tag->hiddenField(array(
    "parent_id",
    "value"=> "5"
)) ?>

Синтаксис Volt:

{{ text_field("username") }}

{{ text_area("comment", "This is the content", "cols": "6", "rows": 20) }}

{{ password_field("password", "size": 30) }}

{{ hidden_field("parent_id", "value": "5") }}

Создание выпадающих списков

Генерация выпадающих списков (select box) проста, особенно если связанные данные хранятся в ассоциативных массивах PHP. Вспомогательные элементы для элементов select — Phalcon\Tag::select() и Phalcon\Tag::selectStatic(). Phalcon\Tag::select() был специально разработан для работы с Phalcon\Mvc\Model, а Phalcon\Tag::selectStatic() может работать с массивами PHP.

// Using data from a resultset
echo $this->tag->select(
    array(
        "productId",
        Products::find("type = 'vegetables'"),
        "using" => array("id", "name")
    )
);

// Using data from an array
echo $this->tag->selectStatic(
    array(
        "status",
        array(
            "A" => "Active",
            "I" => "Inactive",
        )
    )
);

Следующий HTML будет сгенерирован:

<select id="productId" name="productId">
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>

<select id="status" name="status">
    <option value="A">Active</option>
    <option value="I">Inactive</option>
</select>

Вы можете добавить опцию «пусто» в сгенерированный HTML:

// Creating a Select Tag with an empty option
echo $this->tag->select(
    array(
        "productId",
        Products::find("type = 'vegetables'"),
        "using" => array("id", "name"),
        "useEmpty" => true
    )
);

<select id="productId" name="productId">
    <option value="">Choose..</option>
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>

// Creating a Select Tag with an empty option with default text
echo $this->tag->select(
    array(
        'productId',
        Products::find("type = 'vegetables'"),
        'using' => array('id', "name"),
        'useEmpty' => true,
        'emptyText' => 'Please, choose one...',
        'emptyValue' => '@'
    )
);

<select id="productId" name="productId">
    <option value="@">Please, choose one..</option>
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>

Синтаксис Volt для приведенного выше примера:

{# Creating a Select Tag with an empty option with default text #}
{{ select('productId', products, 'using': ['id', 'name'],
    'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }}

Назначение атрибутов HTML

Все помощники принимают массив в качестве первого параметра, который может содержать дополнительные атрибуты HTML для генерируемого элемента.

<?php $this->tag->textField(
    array(
        "price",
        "size"        => 20,
        "maxlength"   => 30,
        "placeholder" => "Enter a price",
    )
) ?>

или с помощью Volt:

{{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }}

Следующий HTML сгенерирован:

<input type="text" name="price" id="price" size="20" maxlength="30"
    placeholder="Enter a price" />

Установка значений помощников

Из контроллеров

Хорошим принципом программирования для фреймворков MVC является установка определенных значений для элементов форм в представлении. Вы можете задать эти значения непосредственно из контроллера, используя Phalcon\Tag::setDefault(). Этот помощник предварительно загружает значение для всех помощников, присутствующих в представлении. Если у любого помощника в представлении есть имя, совпадающее с предварительно загруженным значением, оно будет использоваться, если не задано значение непосредственно в помощнике в представлении.

class ProductsController extends \Phalcon\Mvc\Controller
{

    public function indexAction()
    {
        $this->tag->setDefault("color", "Blue");
    }

}

В представлении помощник selectStatic соответствует тому же индексу, который используется для предварительной установки значения. В этом случае — «цвет»:

echo $this->tag->selectStatic(
    array(
        "color",
        array(
            "Yellow" => "Yellow",
            "Blue"   => "Blue",
            "Red"    => "Red"
        )
    )
);

Это сгенерирует следующий тег select со значением «Синий»:

<select id="color" name="color">
    <option value="Yellow">Yellow</option>
    <option value="Blue" selected="selected">Blue</option>
    <option value="Red">Red</option>
</select>

Из запроса

Особенностью помощников Phalcon\Tag является сохранение значений элементов форм между запросами. Таким образом, вы можете легко отображать сообщения об ошибках валидации, не теряя введённых данных.

Прямое задание значений

Каждый помощник формы поддерживает параметр «значение». С помощью него вы можете указать значение для помощника непосредственно. Если этот параметр присутствует, любые предварительно заданные значения с помощью setDefault() или через запрос будут проигнорированы.

Динамическое изменение заголовка документа

Phalcon\Tag предлагает помощники для динамического изменения заголовка документа из контроллера. Следующий пример демонстрирует это:

class PostsController extends \Phalcon\Mvc\Controller
{

    public function initialize()
    {
        $this->tag->setTitle("Your Website");
    }

    public function indexAction()
    {
        $this->tag->prependTitle("Index of Posts - ");
    }

}

<html>
    <head>
        <?php echo $this->tag->getTitle(); ?>
    </head>
    <body>

    </body>
</html>

Следующий HTML будет сгенерирован:

<html>
    <head>
        <title>Index of Posts - Your Website</title>
    </head>
      <body>

      </body>
</html>

Вспомогательные элементы статического содержимого

Phalcon\Tag также предоставляет помощники для генерации тегов, таких как script, link или img. Они помогают быстро и легко генерировать статические ресурсы вашего приложения

Изображения

// Generate <img src="/your-app/img/hello.gif">
echo $this->tag->image("img/hello.gif");

// Generate <img alt="alternative text" src="/your-app/img/hello.gif">
echo $this->tag->image(
    array(
       "img/hello.gif",
       "alt" => "alternative text"
    )
);

Синтаксис Volt:

{# Generate <img src="/your-app/img/hello.gif"> #}
{{ image("img/hello.gif") }}

{# Generate <img alt="alternative text" src="/your-app/img/hello.gif"> #}
{{ image("img/hello.gif", "alt": "alternative text") }}

Стили

// Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css">
echo $this->tag->stylesheetLink("http://fonts.googleapis.com/css?family=Rosario", false);

// Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css">
echo $this->tag->stylesheetLink("css/styles.css");

Синтаксис Volt:

{# Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css"> #}
{{ stylesheet_link("http://fonts.googleapis.com/css?family=Rosario", false) }}

{# Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css"> #}
{{ stylesheet_link("css/styles.css") }}

JavaScript

// Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script>
echo $this->tag->javascriptInclude("http://localhost/javascript/jquery.min.js", false);

// Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script>
echo $this->tag->javascriptInclude("javascript/jquery.min.js");

Синтаксис Volt:

{# Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script> #}
{{ javascript_include("http://localhost/javascript/jquery.min.js", false) }}

{# Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script> #}
{{ javascript_include("javascript/jquery.min.js") }}

Элементы HTML5 — общий помощник HTML

Phalcon предлагает общий помощник HTML, который позволяет генерировать любые элементы HTML. Разработчик должен передать в помощник имя валидного элемента HTML.

// Generate
// <canvas id="canvas1" width="300" class="cnvclass">
// This is my canvas
// </canvas>
echo $this->tag->tagHtml("canvas", array("id" => "canvas1", "width" => "300", "class" => "cnvclass"), false, true, true);
echo "This is my canvas";
echo $this->tag->tagHtmlClose("canvas");

Синтаксис Volt:

{# Generate
<canvas id="canvas1" width="300" class="cnvclass">
This is my canvas
</canvas> #}
{{ tag_html("canvas", ["id": "canvas1", width": "300", "class": "cnvclass"], false, true, true) }}
    This is my canvas
{{ tag_html_close("canvas") }}

Служба тегов

Phalcon\Tag доступен через службу «тег», это означает, что вы можете получить к нему доступ из любой части приложения, где находится контейнер сервисов:

<?php echo $this->tag->linkTo('pages/about', 'About') ?>

Вы можете легко добавить новые помощники в пользовательский компонент, заменив службу «тег» в контейнере сервисов:

class MyTags extends \Phalcon\Tag
{
    //...

    //Create a new helper
    static public function myAmazingHelper($parameters)
    {
        //...
    }

    //Override an existing method
    static public function textField($parameters)
    {
        //...
    }
}

Затем измените определение службы «тег»:

$di['tag'] = function() {
    return new MyTags();
};

Создание собственных помощников

Вы можете легко создавать собственные помощники. Начните с создания новой папки в той же директории, что и ваши контроллеры и модели. Назовите её, указывая на то, что вы создаете. В данном примере назовем её «customhelpers». Затем создайте новый файл с именем MyTags.php в этой папке. В этот момент у вас получится структура, подобная: /app/customhelpers/MyTags.php. В MyTags.php мы расширим Phalcon\Tag и реализуем собственный помощник. Вот простой пример пользовательского помощника:

class MyTags extends \Phalcon\Tag
{

    /**
     * Generates a widget to show a HTML5 audio tag
     *
     * @param array
     * @return string
     */
    static public function audioField($parameters)
    {

        // Converting parameters to array if it is not
        if (!is_array($parameters)) {
            $parameters = array($parameters);
        }

        // Determining attributes "id" and "name"
        if (!isset($parameters[0])) {
            $parameters[0] = $parameters["id"];
        }

        $id = $parameters[0];
        if (!isset($parameters["name"])) {
            $parameters["name"] = $id;
        } else {
            if (!$parameters["name"]) {
                $parameters["name"] = $id;
            }
        }

        // Determining widget value,
        // \Phalcon\Tag::setDefault() allows to set the widget value
        if (isset($parameters["value"])) {
            $value = $parameters["value"];
            unset($parameters["value"]);
        } else {
            $value = self::getValue($id);
        }

        // Generate the tag code
        $code = '<audio id="'.$id.'" value="'.$value.'" ';
        foreach ($parameters as $key => $attributeValue) {
            if (!is_integer($key)) {
                $code.= $key.'="'.$attributeValue.'" ';
            }
        }
        $code.=" />";

        return $code;
    }

}

После создания пользовательского помощника, мы загрузим новую директорию, содержащую класс нашего помощника, из нашего файла «index.php», расположенного в директории public.

try {

    $loader = new \Phalcon\Loader();
    $loader->registerDirs(array(
        '../app/controllers',
        '../app/models',
        '../app/customhelpers' // Add the new helpers folder
    ))->register();

    $di = new Phalcon\DI\FactoryDefault();

    // Assign our new tag a definition so we can call it
    $di->set('MyTags',  function()
    {
        return new MyTags();
    });

    $application = new \Phalcon\Mvc\Application($di);
    echo $application->handle()->getContent();

    } catch(\Phalcon\Exception $e) {
         echo "PhalconException: ", $e->getMessage();
    }

}

Теперь вы готовы использовать новый помощник в своих представлениях:

<body>

    <?php
    echo MyTags::audioField(array(
        'name' => 'test',
        'id' => 'audio_test',
        'src' => '/path/to/audio.mp3'
        ));
    ?>

</body>

В следующей главе мы поговорим о Volt, более быстром движке шаблонов для PHP, где вы можете использовать более удобный синтаксис для использования помощников, предоставленных Phalcon\Tag.

© 2011–2016 Phalcon Framework Team
Licensed under the Creative Commons Attribution License 3.0.
https://docs.phalconphp.com/en/2.0.0/reference/tags.html