Хелперы предзназначены для предоставления функций, которые часто нужны в отображниях для форматирования и представления данных удобным сопобом.
HTML Хелпер, это один из способов Cake сделать разработку менее монотонной и более быстрой. HTML Хелпер имеет две основные цели: помочь в использовании повторяющихся разделов HTML кода, и помочь быстро и легко создавать веб-формы. Следующие разделы проведут вас через самые важные функции хелпера, но помните, что полный справочник всегда доступен по адресу 
http://api.cakephp.org.
Большинство функций в хелпере используют теги, определенные в файле под названием tags.ini.php. В основной конфигурации Cake содержится tags.ini.php, но если вы хотите внести какие-то изменения, создайте копию /cake/config/tags.ini.php и поместите ее в ваш каталог /app/config/. Хелпер использует теги, определенные в этом файле чтобы сгенерировать теги, которые вы запросили. Использования HTML Хелпера может быть полезным для создания некоторого кода для ваших отображений, также изменения в файле tags.ini.php выплывут в изменениях каскада сайта.
К тому же, если AUTO_OUTPUT имеет значение true в основном конфиг-файле вашего приложения (/app/config/core.php), хелпер будет автоматически выводить теги, а не возвращать значения. Это попытка удовлитворить тех, кто не любит короткие теги (<?= ?>) или множество запросов echo() в своих кодах отображений. Функции включающие параметр $return позволяют вам принудительно заменять настройки в вашем центральном конфиге. Установите $return true если хотите, чтобы хелпер возвратил HTML код не обращая внимания ни на какие настройки AUTO_OUTPUT.
Функции HTML Хелпера также включают в себя параметр $htmlAttributes, который позволяет вам присоединять дополнительные атрибуты к вашим тегам. Например, если у вас есть тег, к которому вы хотите добавить атрибут class, вы вставляете его в переменную $htmlAttribute как значение:
array('class'=>'someClass')
Если вы хотите использовать Cake для добавление хорошо согласованых и часто-повторяющихся элементов в свой HTML код, HTML Хелпер прекрасно подходит для этого. Вот функции этого хелпера, которые вставляют медиа, помогают с таблицами, и даже guiListTree, который создает неупорядочный список, базируясь на PHP масивах.
Это используется для генерирования кодировки META-тега.
Создает связь с CSS таблицей стилей. Параметр $rel который позволяет вам предоставить rel= значение для вашего тега.
Рендерит тег изображения. Код, который вернула эта функция, можно использовать как входящие данные для функции link() чтобы автоматически создать связанные изображения.
Используйте эту функцию чтобы создать ссылки в вашем отображении. $confirmMessage используется если вы хотите использовать сообщение подтверждения Java Script?, когда нажимается ссылка. Например, ссылка которая удаляет объект, вероятнее всего нужно будет вывести сообщения для подтверждения действия вроде «Вы уверены?». Установите значение true переменной $escapeTitle если вы хотите, чтобы HTML Хелпер упускал данные, которые вы отправили в переменную $title.
Используется для форматирования заголовка таблицы.
Используется для форматирования ячеек таблицы.
Генерирует неупорядочное дерво из масива.
HTML Хелпер действительно улыбается вам, когда нужно ускорить написание кода для форм в ваших отображениях. Он генерирует все теги формы, автоматически заполняя значение во время ошибочных ситуаций, убирая сообщения об ошибках. Чтобы помочь проиллюстрировать это, давайте пройдем через быстрый пример. Представьте, что в вашем приложении есть модель Заметка(Note), и вы хотите создать код контроллера и отображения чтобы добавлять и редактировать объекты Заметки. В вашем Notes Controller?, должно быть действие редактирования, которое может выглядить как это:
Действие редактирования в NotesController
<?
function edit($id)
{
// Во-первых, давайте проверим отправлены ли данные из формы
// в действие.
if (!empty($this->data['Note']))
{
// Вот здесь мы пытаемся проверить данные формы
// и сохранить их
if ($this->Note->save($this->data['Note']))
{
// Если мы успешно сохранили, отправляем пользователя
// в подходящее место
$this->flash('Your information has been saved.', '/notes/edit/' . $id);
exit();
}
else
{
// Генерируем сообщения об ошибках для подходищих полей
// это не обязательно, посколько сохранение это уже сделало, но это пример
//вызываем $this->Note->validates($this->data['Note']); если вы не делаете сохранения
//затем используем метод ниже, чтобы заполнить метод хелпера tagErrorMsg()
$this->validateErrors($this->Note);
//И рендерим редактированный код отображения
$this->render();
}
}
//Если мы не получили никаких данных из формы, берем заметку, которую хотим редактировать, и отправляем
//эту информацию в отображение
$this->set('note', $this->Note->find("id = $id"));
$this->render();
}
?>
HTML Хелпер доступен во всех отображениях по умолчанию, можно получить доступ используя $html.
Давайте просто взглянем на таблицу, где находятся все внутренности формы:
Образец кода отображения редактирования(edit.thtml)
<!-- Этот тег создает тег нашей формы -->
<?php echo $html->formTag('/notes/edit/' . $html->tagValue('Note/id')?>
<table cellpadding="10" cellspacing="0">
<tr>
<td align="right">Body: </td>
<td>
<!-- Вот где мы используем HTML Хелпер чтобы отрендерить тег
textarea и его возможные сообщения об ошибках
переменная $note была создана контроллером, и местит
данные для заметки, которую мы редактируем. -->
<?php echo
$html->textarea('Note/body', array('cols'=>'60', 'rows'=>'10'));
?>
<?php echo $html->tagErrorMsg('Note/body',
'Please enter in a body for this note.') ?>
</td>
</tr>
<tr>
<td></td>
<td>
<!-- Мы также можем использовать HTML Хелпер чтобы включить
спрятанные теги внутрь нашей таблицы -->
<?php echo $html->hidden('Note/id')?>
<?php echo $html->hidden('note/submitter_id', $this->controller->Session->read('User.id'))?>
</td>
</tr>
</table>
<!--И наконец подтверждающая кнопка-->
<?php echo $html->submit()?>
</form>
Большинство функций генерирования тегов (вместе с tagErrorMsg) обязывают вас включать $fieldName. Эта $fieldName позволяет Cake узнавать какие данные вы вставляете, так что он может проверить и сохранить данные коректно. Строка вставленная в параметр $fieldName находится в модели формы «modelname/fieldname». Если вы собираетесь добавить новое поле title в нашу Заметку, вы можете добавить в отображение что-то вроде этого:
<?php echo $html->input('Note/title') ?>
<?php echo $html->tagErrorMsg('Note/title', 'Please supply a title for this note.')?>
Сообщения об ошибках отображаются функцией tagErrorMsg() согласно <div class="error_message"></div> для простоты CSS стайлинга.
Вот теги формы, которые HTML хелпер может сгенерировать (большинство из них прямолинейны):
HTML Хелпер также включает набор функций которые помогают в создании тегов, относящихся к датам. С параметром $tagName следует обращаться также как и с параметром $fieldName. Просто предоставьте имя поля, к которому относиться этот тег работы с датой(date option tag). Когда данные обработаются, вы увидите это в вашем контроллере с частью данных, которыми он управляет до конца имени поля. Например, если в моих Заметках есть поле завершения срока, и мой dayOptionTag, параметр $tagName, имеет значение 'note/deadline', данные дня будут показаны в переменной $params, когда данные из формы отправлены в действие контроллера:
$this->data['Note']['deadline_day']
Потом вы можете воспользоваться этой информацией, чтобы перевести дату в формат, который соответствует настройкам вашей базы данных. Этот код помещается как раз перед попыткой сохранить данные, и сохраненные данные из масива $data используются для сохранения информации в модель.
Перевод даты перед сохранением модели (выдержка из NotesController)
<?
function edit($id)
{
//Во-первых, давайте проверим были ли посланы какие-то данные из формы в действие.
if (!empty($this->data['Note']))
{
//Перевод даты для хранения...
$this->data['Note']['deadline'] =
$this->data['Note']['deadline_year'] . "-" .
$this->data['Note']['deadline_month'] . "-" .
$this->data['Note']['deadline_day'];
//Вот где мы пытаемся проверить данные формы (см. Главу 10) и сохранить их
if ($this->Note->save($this->data['Note']))
{
...
?>
Ajax Хелпер Cake'а использует постоянно заполненный Prototype и библиотеки script.aculo.us для операций Ajax и эффектов клиентской стороны. Для того, чтобы использовать этот хелпер, у вас должна быть текущая версия библиотек Java Script? из http://script.aculo.us, которую нужно поместить в /app/webroot/js/. Кстати, все отображения, которые собираются использовать Ajax хелпер должны включать эти библиотеки.
Большинство функций этого хелпера подразумевают использование особого масива $options как параметра. Этот масив используется для определения разных вещей об операциях Ajax. Вот разные значения, которые вы можете определить:
Вот функции хелпера для того, чтобы сделать Ajax в Cake легким и быстрым:
Отображает связанный текст $title, который находит удаленный документ в $options['url'] и обновляет DOM елемент $options['update']. С этой функцией можно использовать колбеки.
Эта фунция используется для создания нужного Java Script? для удаленных запросов. В основном используется как хелпер для linkToRemote. Используется редко, если вам не нужно сгенерировать какой-то особый скриптинг.
Периодические вызовы определенного действи в $options['url'], каждые $options['frequency'] секунд (по умолчанию 10). Обычно используется для обновления опеределенного раздела (определенного $options['update']) результатами удаленного запроса. С этой функцией можно использовать колбеки.
Возвращает тег формы, которая отправляет данные в действие $action, используя XMLHttpRequest в фоне, кроме регулярных требующих перезагрузки отправок POST. Данные из этой формы ведут себя как обычные данные (например, они будут доступны в $this->params['form']). DOM елемент определенный $options['update'] обновится результатами с удаленного документа. С этой функцией можно использовать колбеки.
Наблюдает за полем с DOM ID определенным $field_id (каждые $options['frequency'] секунд) и вызывает действие из $options['url'] если содержание поле изменилось. Вы можете обновить DOM элемент с ID $options['update'] или же определить элемент формы используя $options['with']. С этой функцией можно использовать колбеки.
Работает также как и observeField(), только наблюдает за всеми элементами указанной формы.
Рендерит текстовое поле с ID $field с autoComplete. Действие из $url должна вернуть условия autoComplete: в основном, нужно чтобы ваши действия снимали из неупорядоченного списка (<ul></ul>) элементы, которые соответсвуют условиям autoComplete. Если вы хотите автозавершить поля, которые возвращают темы постов в вашем блоге, ваше действие контроллера может выглядить как это:
<?
function autocomplete ()
{
$this->set('posts',
$this->Post->findAll(
"subject LIKE '{$this->data['Post']['subject']}'")
);
$this->layout = "ajax";
}
?>
<ul>
<?php foreach($posts as $post): ?>
<li><?php echo $post['Post']['subject']; ?></li>
<?php endforeach; ?>
</ul>
Фактическое поле авто-завершения, как оно будет выглядить в отображении, будет выглядить так:
<form action="/users/index" method="POST">
<?php echo $ajax->autoComplete('Post/subject', '/posts/autoComplete')?>
<?php echo $html->submit('View Post')?>
</form>
Функция autoComplete() использует информацию, чтобы отрендерить тектовое поле, и некоторые разделы, которые будут использованы, чтобы показать условия автозавершения, поддерживаемые вашим действием. Может вы захотите стилизировать отображение чем-то вроде следующего:
<style type="text/css">
div.auto_complete {
position :absolute;
width :250px;
background-color :white;
border :1px solid #888;
margin :0px;
padding :0px;
}
li.selected { background-color: #ffb; }
</style>
Делает DOM элемент с ID $id доступным для перетаскивания. Вот некоторые дополнительные вещи, которые вы можете определить используя $options:
// (The version numbers refer to script.aculo.us versions)
<?
$options['handle'] // (v1.0) Устанавливает должен ли элемент быть
// доступным для перестасикания только внедреным манипулятором.Значение должно быть
//ссылкой на жлемент или id элемента.
$options['handle'] // (V1.5)Как и выше, кроме того, что теперь значение может быть
// строкой ссылающейся на значение класса CSS. string referencing a CSS class value. Первый
// найденный элемент child/grandchild/etc. у которого есть
// это значение класса CSS будет использован
// как манипулятор.
$options['revert'] // (V1.0) Если установленно true, то элемент будет возвращаться
// на свою исходную позицию по окончанию перетаскивания.
$options['revert'] // (V1.5) Revert также может быть произвольно-вызванной, по окончанию
// перетаскивания, функцией.
$options['constraint'] //Если установлено horizontal или vertical,перетаскивание
// будет принудительно производится токо по горизонтали
//или по вертикали.
?>
Делает DOM элемент с ID $id доступным к бросанию (drop). Вот некоторые дополнительные вещи, которые вы можете определить используя $options:
<?
$options['accept'] // Устанавливает доступ строкам или масиву строк JavaScript,
// которые описывают классы CSS. Доступность к броску
// будет приниматься только от доступных к перетаскиванию элементов
//содержащих один или больше из этих классов CSS.
$options['containment'] // Элементы доступные к броску будут принимать только
// элементы доступные к перетаскиванию, которые содержат один из данных
// id элементов (или элемента). Может быть один элемент
// или масив элементов JS.
$options['overlap'] //Если установлено horizontal или vertical, доступные к бросанию
// будут только реагировать на элементы доступые к перетаскиваниюif its
//если покрытие больше 50% в данном направлении.
?>
Используется для создание цели броска, инициируемой XMLHttpRequest когда элемент доступный к перетаскиванию брошен. $options такие же как и в drop(), а $ajaxOptions такие же как в link().
Делает список или группу объектов (определенных ID элементов $id) сортируемым. Масивом $options можно настроить вашу сортировку так:
<?
$options['tag'] // Устанавливает вид тега (дочерних элементов
// контейнера) который будет сделан сортируемым. Для UL и
// OL контрейнеров, это LI, вам нужно предоставить
// вид тега для других видов дочених тегов.
// По умолчанию 'li'.
$options['only'] //Дальнейшее ограничение выбора дочерних элементов
// элементами с данным классом CSS
// (или, если вы предоставите масив строк, любым из
// классов).
$options['overlap'] // Либо vertical(по-умолчанию) или horizontal.
// Для плавающих сортировок или горизонтальных списков, выбирете
// horizontal. Для вертикальных списков используйте vertical.
$options['constraint'] // Ограничивает передвижения элементов доступных к перетаскиванию,
// 'vertical' или 'horizontal'.
$options['containment'] // Включает возможность перетаскивания и бросания между сортируемыми.
// Беперт масив элементов или id-номеров элементов (из
// контейнера).
$options['handle'] // Заствялет созданные доступные к перетаскиванию элементы, использовать манипуляторы,
// смотрите опцию handle в drag().
?>
Создает внутренний редактор ajax, используя элементы с DOM ID как первый параметр. Когда применен, элементы будут подсвечивать по наведению мышкой, и будут превращатся в поле ввода текста по щелчку. Второй параметр – ссылка, куда должны отправится отредактированные данные. Дополнительные опции внутреннего редактора можно найти по адресу Script.aculo?.us wiki.
Java Script? Хелпер используется чтобы помочь разработчику в извлечении хорошо отформатированных относяхщихся к Java Script? тегов и данных.
Используется для возвращения $script помещенного в рамки Java Script? тегов <script>.
Возвращает Java Script? с включенным ссылающимся по $url тегом.
Тоже что и link(), только включая ссылающийся тег, подразумевая, что $url находится не на том же домене.
Избегая каретку, возвращает и одинарные и двойные кавычки для сегментов кода Java Script?.
Прикрепляет событие к элементу. Использует библиотеку Prototype.
Кеширует события Java Script? созданные с event().
Записывает кешированные события кешированные с cacheEvent().
Number хелпер включает в себя несколько милых функций для форматирования нумерованных данных в ваших отображениях.
Возвращает $number с точностью определенной $precision.
Возвращает удобчитаемый размер, данный $size в байтах. В основном, вы вводите число байт, и эта функция возвращает вам подходящее удобчитаемое значение в КБ, МБ, ГБ или ТБ.
Возвращает данное число $number как проценты, ограниченные точностью установленной в $precision.
Text Хелпер предоставляет методы, которые могут понадобиться разработчику для извлечение хорошо отформатированного текста в браузер.
Возвращает текст перенесенный тегами определенными в $highlighter.
Возвращает текст с удаленными HTML ссылками (<a href= ...).
Возвращает $text с ссылками помещенными в соответсвующие теги <a>.
Возвращает $text с адресами e-mail помещенными в соответствующие теги <a>.
Возвращает $text с ссылками и адресами e-mail помещенными в соответсвующие теги <a>.
Возвращает $length число символов $text следующего за $ending ('...' по умолчанию).
Извлекает отрывок из $text, набирая $phrase с количеством символов с каждой стороны определенных $radius.
Text-to-HTML транслятор, такой же как Textile или Red Cloth? только с другим синтаксисом.
Time Хелпер предоставляет методы, которые могут понадобится разработчику для извлечения временных отметок Unix и/или строки времени-даты в более понятном виде в браузер.
Даты могут быть предоставлены во все функции как действительные строки времени-даты PHP или временные отметки Unix.
Возвращает временную отметку UNIX, данную как временную отметку UNIX или существующую строку даты strtotime().
Возвращает приятно-отформатированную строку даты. Даты форматируются как “D, M jS Y, H:i”, или 'Mon, Jan 1st 2005, 12:00'.
Форматирует строки дат как определено в nice(), но выводит «Сегодня 12:00" если эта дата сегодня, или «Вчера 12:00", если дата вчерашняя.
Возвращает true если данная строка времени-даты – сегодняшняя.
Возвращает частичную строку SQL для поиска всех записей между двумя датами.
Возвращает частичную строку SQL для поиска всех записей между двумя временными отметками одного дня.
Возвращает true если данная строка времени-даты в пределах текущего года.
Возвращает true если данная строка времени-даты была вчера.
Возвращает true если данная строка времени-даты будет завтра.
Возвращает временную отметку UNIX из текстового описания времени-даты.
Возвращает дату, форматированную для Atom RSS.
Форматирует дату для RSS.
Возвращает либо относительную дату либо форматированную дату, в зависимости от разницы между текущим временем и данными времени-даты. $datetime должна быть в формате strtotime как время-дата My SQL?.
Работает как timeAgoInWords(), но включает в себя способность создатвать также временные отметки и в будущем (например «Вчера 10:33", «Сегодня 9:42", и также «Завтра 4:34").
Возвращает true если определенные время-дата были в пределах установленного интервала, иначе false. Временной интервал нужно определять как с цифрами так и единицами: '6 hours', '2 days', etc.
Cache
Нужна помощь с кодом отображения? Если вам понадобится определенная часть кода снова и снова, вы можете создать свой собственный View Хелпер.
Расширение класса Хелпера Cake
Скажем нам захотелось создать хелпер, который можно использовать для извлечения стилизованных ссылок CSS, которые нам нужны в приложении. Чтобы добавить свой код в существующую структуру хелпера Cake, нам понадобится создать новый класс в /app/views/helpers. Давайте назовем наш хелпер Link Helper?. Тогда файл класса PHP будет выглядить так:
/app/views/helpers/link.php
<?
class LinkHelper extends Helper
{
function makeEdit($title, $url)
{
//Здесь идет код создания специально-отформатированной ссылки...
}
}
?>
Вот несколько функций, которые включает в себя класс хелпера Cake, которые вам могут пригодиться:
Решает вывести или вернуть строку, базируясь на AUTO_OUTPUT (см. /app/config/core.php) и значении $return. Используйте эту функцию для возврата данных в ваше отображение.
Возвращает текущую центральную настройку вашего приложение и определения тегов.
Давайте используем output() чтобы отформатировать наш титул и ссылку и вернуть их в отображение.
/app/views/helpers/link.php (код добавлен)
<?
class LinkHelper extends Helper
{
function makeEdit($title, $url)
{
// Используем функцию извлечения хелпера чтобы вернуть
// форматированные данные обратно в отображение:
return $this->output("<div class=\"editOuter\"><a href=\"$url\" class=\"edit\">$title</a></div>");
}
}
?>
Может быть вы захотите воспользоваться функциональностью других, уже существующих, хелперов. Воспользоваться этим вы можете, указав хелперы, которые хотите использовать в масиве $helpers.
/app/views/helpers/link.php (использование других хелперов)
<?
class LinkHelper extends Helper
{
var $helpers = array('Html');
function makeEdit($title, $url)
{
// Используем HTML Хелпер для извлечения
// форматированных данных:
$link = $this->Html->link($title, $url, array('class' => 'edit'));
return $this->output("<div class=\"editOuter\">$link</div>");
}
}
?>
Когда вы создали свой хелпер и поместили его в /app/views/helpers/, вы можете использовать его в своих контроллерах, при помощи специальной переменной $helpers.
<?
class ThingsController
{
var $helpers = array('Html', 'Link');
}
?>
Не забудьте включить HTML хелпер в масив если планируете его где-то использовать. Схема присвоения имен та же, что и у моделей.
Пожалуйта обратите внимание на то, чтобы дать свой код Cake – свяжитесь с одним из разработчиков, или откройте новый проет Cake Forge? чтобы поделиться своим новым хелпером с другими.