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

Написание и сопровождение разметки 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 Strict
HTML401_TRANSITIONAL	HTML 4.01 Transitional
HTML401_FRAMESET	HTML 4.01 Frameset
HTML5	HTML 5
XHTML10_STRICT	XHTML 1.0 Strict
XHTML10_TRANSITIONAL	XHTML 1.0 Transitional
XHTML10_FRAMESET	XHTML 1.0 Frameset
XHTML11	XHTML 1.1
XHTML20	XHTML 2.0
XHTML5	XHTML 5

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

use Phalcon\Tag;

$this->tag->setDoctype(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(["products/edit/10", "Edit", "class" => "edit-btn"]) ?>

<!-- for a named route -->
<?= $this->tag->linkTo([["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 a HTML 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(["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(
    [
        "comment",
        "This is the content of the text-area",
        "cols" => "6",
        "rows" => 20,
    ]
) ?>

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

<?php echo $this->tag->hiddenField(
    [
        "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-боксов) проста, особенно если связанные данные хранятся в ассоциативных массивах PHP. Вспомогательные элементы для элементов select — это Phalcon\Tag::select() и Phalcon\Tag::selectStatic(). Phalcon\Tag::select() был специально разработан для работы с Phalcon\Mvc\Model, в то время как Phalcon\Tag::selectStatic() может работать с массивами PHP.

$products = Products::find("type = 'vegetables'");

// Using data from a resultset
echo $this->tag->select(
    [
        "productId",
        $products,
        "using" => [
            "id",
            "name",
        ]
    ]
);

// Using data from an array
echo $this->tag->selectStatic(
    [
        "status",
        [
            "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:

$products = Products::find("type = 'vegetables'");

// Creating a Select Tag with an empty option
echo $this->tag->select(
    [
        "productId",
        $products,
        "using"    => [
            "id",
            "name",
        ],
        "useEmpty" => true,
    ]
);

Производит этот HTML:

<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>

$products = Products::find("type = 'vegetables'");

// Creating a Select Tag with an empty option with default text
echo $this->tag->select(
    [
        "productId",
        $products,
        "using"      => [
            "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(
    [
        "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(). Этот вспомогательный элемент предварительно загружает значение для всех вспомогательных элементов, присутствующих в представлении. Если у любого вспомогательного элемента в представлении есть имя, соответствующее предварительно загруженному значению, оно будет использоваться, если только значение не задано непосредственно для вспомогательного элемента в представлении.

use Phalcon\Mvc\Controller;

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

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

echo $this->tag->selectStatic(
    [
        "color",
        [
            "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 предлагает вспомогательные элементы для динамического изменения заголовка документа из контроллера. Следующий пример демонстрирует это:

use Phalcon\Mvc\Controller;

class PostsController extends 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(
    [
       "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", ["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 доступен через сервис ‘tag’, что означает, что вы можете получить к нему доступ из любой части приложения, где находится контейнер сервисов:

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

Вы можете легко добавить новые вспомогательные элементы в пользовательский компонент, заменив сервис ‘tag’ в контейнере сервисов:

use Phalcon\Tag;

class MyTags extends Tag
{
    // ...

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

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

Затем измените определение сервиса ‘tag’:

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

Создание собственных вспомогательных элементов

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

use Phalcon\Tag;

class MyTags extends Tag
{
    /**
     * Generates a widget to show a HTML5 audio tag
     *
     * @param array
     * @return string
     */
    public static function audioField($parameters)
    {
        // Converting parameters to array if it is not
        if (!is_array($parameters)) {
            $parameters = [$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.

use Phalcon\Loader;
use Phalcon\Mvc\Application;
use Phalcon\Di\FactoryDefault();
use Phalcon\Exception as PhalconException;

try {
    $loader = new Loader();

    $loader->registerDirs(
        [
            "../app/controllers",
            "../app/models",
            "../app/customhelpers", // Add the new helpers folder
        ]
    );

    $loader->register();

    $di = new FactoryDefault();

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

    $application = new Application($di);

    $response = $application->handle();

    $response->send();
} catch (PhalconException $e) {
    echo "PhalconException: ", $e->getMessage();
}

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

<body>

    <?php

    echo MyTags::audioField(
        [
            "name" => "test",
            "id"   => "audio_test",
            "src"  => "/path/to/audio.mp3",
        ]
    );

    ?>

</body>

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

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