Хелперы предзназначены для предоставления функций, которые часто нужны в отображниях для форматирования и представления данных удобным сопобом.
Введение
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 масивах.
charset
string $charset
boolean $return
Это используется для генерирования кодировки META-тега.
css
string $path
string $rel = 'stylesheet'
array $htmlAttributes
boolean $return = false
Создает связь с CSS таблицей стилей. Параметр $rel который позволяет вам предоставить rel= значение для вашего тега.
image
string $path
array $htmlAttributes
boolean $return = false
Рендерит тег изображения. Код, который вернула эта функция, можно использовать как входящие данные для функции link() чтобы автоматически создать связанные изображения.
link
string $title
string $url
array $htmlAttributes
string $confirmMessage = false
boolean $escapeTitle = true
boolean $return = false
Используйте эту функцию чтобы создать ссылки в вашем отображении. $confirmMessage используется если вы хотите использовать сообщение подтверждения Java Script, когда нажимается ссылка. Например, ссылка которая удаляет объект, вероятнее всего нужно будет вывести сообщения для подтверждения действия вроде «Вы уверены?». Установите значение true переменной $escapeTitle если вы хотите, чтобы HTML Хелпер упускал данные, которые вы отправили в переменную $title.
tableHeaders
array $names
array $tr_options
array $th_options
Используется для форматирования заголовка таблицы.
tableCells
array $data
array $odd_tr_options
array $even_tr_options
Используется для форматирования ячеек таблицы.
guiListTree
array $data
array $htmlAttributes
string $bodyKey = 'body'
string $childrenKey = 'children'
boolean $return = false
Генерирует неупорядочное дерво из масива.
Формы и верификация
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(); } ?>
Раз уж мы настроили наш контроллер, давайте посмотрим на код отображения (который можно найти в app/views/notes/edit.thtml). Наша модель Заметки достаточно простая на этом этапе, поскольку включает в себя только id. Этот код отображения подразумевает отображение данных заметки и позволяет пользователю вводить новые заничения и сохранять эти данные в модель.
HTML Хелпер доступен во всех отображениях по умолчанию, можно получить доступ используя $html.
Давайте просто взглянем на таблицу, где находятся все внутренности формы:
Образец кода отображения редактирования(edit.thtml)
<!-- Вот где мы используем 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->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 хелпер может сгенерировать (большинство из них прямолинейны):
submit
string $buttonCaption
array $htmlAttributes
boolean $return = false
password
string $fieldName
array $htmlAttributes
boolean $return = false
textarea
string $fieldName
array $htmlAttributes
boolean $return = false
checkbox
string $fieldName
array $htmlAttributes
boolean $return = false
file
string $fieldName
array $htmlAttributes
boolean $return = false
hidden
string $fieldName
array $htmlAttributes
boolean $return = false
input
string $fieldName
array $htmlAttributes
boolean $return = false
radio
string $fieldName
array $options
array $inbetween
array $htmlAttributes
boolean $return = false
tagErrorMsg
string $fieldName
string $message
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'])) {
Ajax Хелпер Cake'а использует постоянно заполненный Prototype и библиотеки script.aculo.us для операций Ajax и эффектов клиентской стороны. Для того, чтобы использовать этот хелпер, у вас должна быть текущая версия библиотек Java Script из http://script.aculo.us, которую нужно поместить в /app/webroot/js/. Кстати, все отображения, которые собираются использовать Ajax хелпер должны включать эти библиотеки.
Большинство функций этого хелпера подразумевают использование особого масива $options как параметра. Этот масив используется для определения разных вещей об операциях Ajax. Вот разные значения, которые вы можете определить:
Ключи $options Ajax Хелпера
Вот функции хелпера для того, чтобы сделать Ajax в Cake легким и быстрым:
link
string $title
string $href
array $options
boolean $confirm
boolean $escapeTitle
Отображает связанный текст $title, который находит удаленный документ в $options['url'] и обновляет DOM елемент $options['update']. С этой функцией можно использовать колбеки.
remoteFunction
array $options
Эта фунция используется для создания нужного Java Script для удаленных запросов. В основном используется как хелпер для linkToRemote. Используется редко, если вам не нужно сгенерировать какой-то особый скриптинг.
remoteTimer
array $options
Периодические вызовы определенного действи в $options['url'], каждые $options['frequency'] секунд (по умолчанию 10). Обычно используется для обновления опеределенного раздела (определенного $options['update']) результатами удаленного запроса. С этой функцией можно использовать колбеки.
form
string $action
string $type
array $options
Возвращает тег формы, которая отправляет данные в действие $action, используя XMLHttpRequest в фоне, кроме регулярных требующих перезагрузки отправок POST. Данные из этой формы ведут себя как обычные данные (например, они будут доступны в $this->params['form']). DOM елемент определенный $options['update'] обновится результатами с удаленного документа. С этой функцией можно использовать колбеки.
observeField
string $field_id
array $options
Наблюдает за полем с DOM ID определенным $field_id (каждые $options['frequency'] секунд) и вызывает действие из $options['url'] если содержание поле изменилось. Вы можете обновить DOM элемент с ID $options['update'] или же определить элемент формы используя $options['with']. С этой функцией можно использовать колбеки.
observeForm
string $form_id
array $options
Работает также как и observeField(), только наблюдает за всеми элементами указанной формы.
autoComplete
string $field
string $url
array $options
Рендерит текстовое поле с 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"; } ?>
А ваше отображения для действия autocomplete() будет выглядить так:
Функция autoComplete() использует информацию, чтобы отрендерить тектовое поле, и некоторые разделы, которые будут использованы, чтобы показать условия автозавершения, поддерживаемые вашим действием. Может вы захотите стилизировать отображение чем-то вроде следующего:
Делает 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,перетаскивание // будет принудительно производится токо по горизонтали //или по вертикали. ?>
drop
string $id
array $options
Делает DOM элемент с ID $id доступным к бросанию (drop). Вот некоторые дополнительные вещи, которые вы можете определить используя $options:
<? $options['accept'] // Устанавливает доступ строкам или масиву строк JavaScript, // которые описывают классы CSS. Доступность к броску // будет приниматься только от доступных к перетаскиванию элементов //содержащих один или больше из этих классов CSS.
$options['containment'] // Элементы доступные к броску будут принимать только // элементы доступные к перетаскиванию, которые содержат один из данных // id элементов (или элемента). Может быть один элемент // или масив элементов JS.
$options['overlap'] //Если установлено horizontal или vertical, доступные к бросанию // будут только реагировать на элементы доступые к перетаскиваниюif its //если покрытие больше 50% в данном направлении. ?>
dropRemote
string $id
array $options
array $ajaxOptions
Используется для создание цели броска, инициируемой XMLHttpRequest когда элемент доступный к перетаскиванию брошен. $options такие же как и в drop(), а $ajaxOptions такие же как в link().
sortable
string $id
array $options
Делает список или группу объектов (определенных 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(). ?>
editor
string $id
string $url
array $options
Создает внутренний редактор ajax, используя элементы с DOM ID как первый параметр. Когда применен, элементы будут подсвечивать по наведению мышкой, и будут превращатся в поле ввода текста по щелчку. Второй параметр – ссылка, куда должны отправится отредактированные данные. Дополнительные опции внутреннего редактора можно найти по адресу Script.aculo.us wiki.
Javascript
Java Script Хелпер используется чтобы помочь разработчику в извлечении хорошо отформатированных относяхщихся к Java Script тегов и данных.
codeBlock
string $string
Используется для возвращения $script помещенного в рамки Java Script тегов <script>.
link
string $url
Возвращает Java Script с включенным ссылающимся по $url тегом.
linkOut
string $url
Тоже что и link(), только включая ссылающийся тег, подразумевая, что $url находится не на том же домене.
escapeScript
string $script
Избегая каретку, возвращает и одинарные и двойные кавычки для сегментов кода Java Script.
event
string $object
string $event
string $observer
boolean $useCapture
Прикрепляет событие к элементу. Использует библиотеку Prototype.
cacheEvents
Кеширует события Java Script созданные с event().
writeEvents
Записывает кешированные события кешированные с cacheEvent().
includeScript
string $script
Number
Number хелпер включает в себя несколько милых функций для форматирования нумерованных данных в ваших отображениях.
precision
mixed $number
int $precision = 3
Возвращает $number с точностью определенной $precision.
toReadableSize
int $sizeInBytes
Возвращает удобчитаемый размер, данный $size в байтах. В основном, вы вводите число байт, и эта функция возвращает вам подходящее удобчитаемое значение в КБ, МБ, ГБ или ТБ.
toPercentage
mixed $number
int $precision = 2
Возвращает данное число $number как проценты, ограниченные точностью установленной в $precision.
Text
Text Хелпер предоставляет методы, которые могут понадобиться разработчику для извлечение хорошо отформатированного текста в браузер.
Возвращает текст перенесенный тегами определенными в $highlighter.
stripLinks
string $text
Возвращает текст с удаленными HTML ссылками (<a href= ...).
autoLinkUrls
string $text
array $htmlOptions
Возвращает $text с ссылками помещенными в соответсвующие теги <a>.
autoLinkEmails
string $text
array $htmlOptions
Возвращает $text с адресами e-mail помещенными в соответствующие теги <a>.
autoLink
string $text
array $htmlOptions
Возвращает $text с ссылками и адресами e-mail помещенными в соответсвующие теги <a>.
truncate
string $text
int $length
string $ending = '...'
Возвращает $length число символов $text следующего за $ending ('...' по умолчанию).
excerpt
string $text
string $phrase
int $radius = 100
string $ending = '...'
Извлекает отрывок из $text, набирая $phrase с количеством символов с каждой стороны определенных $radius.
flay
string $text
boolean $allowHtml = false
Text-to-HTML транслятор, такой же как Textile или Red Cloth только с другим синтаксисом.
Time
Time Хелпер предоставляет методы, которые могут понадобится разработчику для извлечения временных отметок Unix и/или строки времени-даты в более понятном виде в браузер.
Даты могут быть предоставлены во все функции как действительные строки времени-даты PHP или временные отметки Unix.
fromString
string $dateString
Возвращает временную отметку UNIX, данную как временную отметку UNIX или существующую строку даты strtotime().
nice
string $dateString
boolean $return = false
Возвращает приятно-отформатированную строку даты. Даты форматируются как D, M jS Y, H:i, или 'Mon, Jan 1st 2005, 12:00'.
niceShort
string $dateString
boolean $return = false
Форматирует строки дат как определено в nice(), но выводит «Сегодня 12:00" если эта дата сегодня, или «Вчера 12:00", если дата вчерашняя.
isToday
string $dateString
Возвращает true если данная строка времени-даты – сегодняшняя.
daysAsSql
string $begin
string $end
string $fieldName
boolean $return = false
Возвращает частичную строку SQL для поиска всех записей между двумя датами.
dayAsSql
string $dateString
string $fieldName
boolean $return = false
Возвращает частичную строку SQL для поиска всех записей между двумя временными отметками одного дня.
isThisYear
string $dateString
boolean $return = false
Возвращает true если данная строка времени-даты в пределах текущего года.
wasYesterday
string $dateString
boolean $return = false
Возвращает true если данная строка времени-даты была вчера.
isTomorrow
string $dateString
boolean $return = false
Возвращает true если данная строка времени-даты будет завтра.
toUnix
string $dateString
boolean $return = false
Возвращает временную отметку UNIX из текстового описания времени-даты.
toAtom
string $dateString
boolean $return = false
Возвращает дату, форматированную для Atom RSS.
toRSS
string $dateString
boolean $return = false
Форматирует дату для RSS.
timeAgoInWords
string $dateString
boolean $return = false
Возвращает либо относительную дату либо форматированную дату, в зависимости от разницы между текущим временем и данными времени-даты. $datetime должна быть в формате strtotime как время-дата My SQL.
relativeTime
string $dateString
boolean $return = false
Работает как timeAgoInWords(), но включает в себя способность создатвать также временные отметки и в будущем (например «Вчера 10:33", «Сегодня 9:42", и также «Завтра 4:34").
relativeTime
string $timeInterval
string $dateString
boolean $return = false
Возвращает 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, которые вам могут пригодиться:
output
string $string
boolean $return = false
Решает вывести или вернуть строку, базируясь на AUTO_OUTPUT (см. /app/config/core.php) и значении $return. Используйте эту функцию для возврата данных в ваше отображение.
loadConfig
Возвращает текущую центральную настройку вашего приложение и определения тегов.
Давайте используем output() чтобы отформатировать наш титул и ссылку и вернуть их в отображение.
/app/views/helpers/link.php (код добавлен) <? class LinkHelper extends Helper { function makeEdit($title, $url) { // Используем функцию извлечения хелпера чтобы вернуть // форматированные данные обратно в отображение:
Может быть вы захотите воспользоваться функциональностью других, уже существующих, хелперов. Воспользоваться этим вы можете, указав хелперы, которые хотите использовать в масиве $helpers.
/app/views/helpers/link.php (использование других хелперов) <? class LinkHelper extends Helper {
var $helpers = array('Html');
function makeEdit($title, $url) { // Используем HTML Хелпер для извлечения // форматированных данных:
Когда вы создали свой хелпер и поместили его в /app/views/helpers/, вы можете использовать его в своих контроллерах, при помощи специальной переменной $helpers.
<? class ThingsController { var $helpers = array('Html', 'Link'); } ?>
Не забудьте включить HTML хелпер в масив если планируете его где-то использовать. Схема присвоения имен та же, что и у моделей.
LinkHelper = имя класса
link = ключ в масиве хелперов
link.php = имя файла php в /app/views/helpers.
Содействие
Пожалуйта обратите внимание на то, чтобы дать свой код Cake – свяжитесь с одним из разработчиков, или откройте новый проет Cake Forge чтобы поделиться своим новым хелпером с другими.