Home PageКаталог Изменения НовыеКомментарии Пользователи Регистрация
CakePHP: Manual11/Helpers ...

Помощники


Оглавление документа

Хелперы

Хелперы предзназначены для предоставления функций, которые часто нужны в отображниях для форматирования и представления данных удобным сопобом.

Введение

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

Это используется для генерирования кодировки META-тега.

css

Создает связь с CSS таблицей стилей. Параметр $rel который позволяет вам предоставить rel= значение для вашего тега.

image

Рендерит тег изображения. Код, который вернула эта функция, можно использовать как входящие данные для функции link() чтобы автоматически создать связанные изображения.

link

Используйте эту функцию чтобы создать ссылки в вашем отображении. $confirmMessage используется если вы хотите использовать сообщение подтверждения Java Script?, когда нажимается ссылка. Например, ссылка которая удаляет объект, вероятнее всего нужно будет вывести сообщения для подтверждения действия вроде «Вы уверены?». Установите значение true переменной $escapeTitle если вы хотите, чтобы HTML Хелпер упускал данные, которые вы отправили в переменную $title.

tableHeaders

Используется для форматирования заголовка таблицы.

tableCells

Используется для форматирования ячеек таблицы.

guiListTree

Генерирует неупорядочное дерво из масива.

Формы и верификация

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)

<!-- Этот тег создает тег нашей формы -->

<?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 хелпер может сгенерировать (большинство из них прямолинейны):

submit

password

textarea

checkbox

file

hidden

input

radio

tagErrorMsg


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']))
         {

         ...
?>

  1. dayOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)
  2. yearOptionTag ($tagName, $value=null, $minYear=null, $maxYear=null, $selected=null, $optionAttr=null)
  3. monthOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)
  4. hourOptionTag ($tagName, $value=null, $format24Hours=false, $selected=null, $optionAttr=null)
  5. minuteOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)
  6. meridianOptionTag ($tagName, $value=null, $selected=null, $optionAttr=null)
  7. dateTimeOptionTag ($tagName, $dateFormat= 'DMY', $timeFormat= '12', $selected=null, $optionAttr=null)

AJAX

Ajax Хелпер Cake'а использует постоянно заполненный Prototype и библиотеки script.aculo.us для операций Ajax и эффектов клиентской стороны. Для того, чтобы использовать этот хелпер, у вас должна быть текущая версия библиотек Java Script? из http://script.aculo.us, которую нужно поместить в /app/webroot/js/. Кстати, все отображения, которые собираются использовать Ajax хелпер должны включать эти библиотеки.


Большинство функций этого хелпера подразумевают использование особого масива $options как параметра. Этот масив используется для определения разных вещей об операциях Ajax. Вот разные значения, которые вы можете определить:

Ключи $options Ajax Хелпера


Вот функции хелпера для того, чтобы сделать Ajax в Cake легким и быстрым:

link

Отображает связанный текст $title, который находит удаленный документ в $options['url'] и обновляет DOM елемент $options['update']. С этой функцией можно использовать колбеки.

remoteFunction

Эта фунция используется для создания нужного Java Script? для удаленных запросов. В основном используется как хелпер для linkToRemote. Используется редко, если вам не нужно сгенерировать какой-то особый скриптинг.

remoteTimer

Периодические вызовы определенного действи в $options['url'], каждые $options['frequency'] секунд (по умолчанию 10). Обычно используется для обновления опеределенного раздела (определенного $options['update']) результатами удаленного запроса. С этой функцией можно использовать колбеки.

form

Возвращает тег формы, которая отправляет данные в действие $action, используя XMLHttpRequest в фоне, кроме регулярных требующих перезагрузки отправок POST. Данные из этой формы ведут себя как обычные данные (например, они будут доступны в $this->params['form']). DOM елемент определенный $options['update'] обновится результатами с удаленного документа. С этой функцией можно использовать колбеки.

observeField

Наблюдает за полем с DOM ID определенным $field_id (каждые $options['frequency'] секунд) и вызывает действие из $options['url'] если содержание поле изменилось. Вы можете обновить DOM элемент с ID $options['update'] или же определить элемент формы используя $options['with']. С этой функцией можно использовать колбеки.

observeForm

Работает также как и observeField(), только наблюдает за всеми элементами указанной формы.

autoComplete

Рендерит текстовое поле с 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() будет выглядить так:
<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> 

drag

Делает 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


Делает DOM элемент с ID $id доступным к бросанию (drop). Вот некоторые дополнительные вещи, которые вы можете определить используя $options:

<?
$options
['accept']      // Устанавливает доступ строкам или масиву строк JavaScript,
                        // которые описывают классы CSS. Доступность к броску
                        // будет приниматься только от доступных к перетаскиванию элементов
                        //содержащих один или больше из этих классов CSS.

$options['containment'// Элементы доступные к броску будут принимать только
                        // элементы доступные к перетаскиванию, которые содержат один из данных
                        // id элементов (или элемента). Может быть один элемент
                        // или масив элементов JS.

$options['overlap']     //Если установлено horizontal или vertical, доступные к бросанию
                        // будут только реагировать на элементы доступые к перетаскиваниюif its
                        //если покрытие больше 50% в данном направлении.
?>

dropRemote

Используется для создание цели броска, инициируемой XMLHttpRequest когда элемент доступный к перетаскиванию брошен. $options такие же как и в drop(), а $ajaxOptions такие же как в link().

sortable

Делает список или группу объектов (определенных 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

Создает внутренний редактор ajax, используя элементы с DOM ID как первый параметр. Когда применен, элементы будут подсвечивать по наведению мышкой, и будут превращатся в поле ввода текста по щелчку. Второй параметр – ссылка, куда должны отправится отредактированные данные. Дополнительные опции внутреннего редактора можно найти по адресу Script.aculo?.us wiki.

Javascript

Java Script? Хелпер используется чтобы помочь разработчику в извлечении хорошо отформатированных относяхщихся к Java Script? тегов и данных.

codeBlock

Используется для возвращения $script помещенного в рамки Java Script? тегов <script>.

link

Возвращает Java Script? с включенным ссылающимся по $url тегом.

linkOut

Тоже что и link(), только включая ссылающийся тег, подразумевая, что $url находится не на том же домене.

escapeScript

Избегая каретку, возвращает и одинарные и двойные кавычки для сегментов кода Java Script?.

event

Прикрепляет событие к элементу. Использует библиотеку Prototype.

cacheEvents

Кеширует события Java Script? созданные с event().

writeEvents

Записывает кешированные события кешированные с cacheEvent().

includeScript

Number

Number хелпер включает в себя несколько милых функций для форматирования нумерованных данных в ваших отображениях.

precision

Возвращает $number с точностью определенной $precision.

toReadableSize

Возвращает удобчитаемый размер, данный $size в байтах. В основном, вы вводите число байт, и эта функция возвращает вам подходящее удобчитаемое значение в КБ, МБ, ГБ или ТБ.

toPercentage

Возвращает данное число $number как проценты, ограниченные точностью установленной в $precision.

Text

Text Хелпер предоставляет методы, которые могут понадобиться разработчику для извлечение хорошо отформатированного текста в браузер.

highlight

Возвращает текст перенесенный тегами определенными в $highlighter.

stripLinks

Возвращает текст с удаленными HTML ссылками (<a href= ...).

autoLinkUrls

Возвращает $text с ссылками помещенными в соответсвующие теги <a>.

autoLinkEmails

Возвращает $text с адресами e-mail помещенными в соответствующие теги <a>.

autoLink

Возвращает $text с ссылками и адресами e-mail помещенными в соответсвующие теги <a>.

truncate

Возвращает $length число символов $text следующего за $ending ('...' по умолчанию).

excerpt

Извлекает отрывок из $text, набирая $phrase с количеством символов с каждой стороны определенных $radius.

flay

Text-to-HTML транслятор, такой же как Textile или Red Cloth? только с другим синтаксисом.

Time

Time Хелпер предоставляет методы, которые могут понадобится разработчику для извлечения временных отметок Unix и/или строки времени-даты в более понятном виде в браузер.
Даты могут быть предоставлены во все функции как действительные строки времени-даты PHP или временные отметки Unix.

fromString


Возвращает временную отметку UNIX, данную как временную отметку UNIX или существующую строку даты strtotime().

nice

Возвращает приятно-отформатированную строку даты. Даты форматируются как “D, M jS Y, H:i”, или 'Mon, Jan 1st 2005, 12:00'.

niceShort

Форматирует строки дат как определено в nice(), но выводит «Сегодня 12:00" если эта дата сегодня, или «Вчера 12:00", если дата вчерашняя.

isToday

Возвращает true если данная строка времени-даты – сегодняшняя.

daysAsSql

Возвращает частичную строку SQL для поиска всех записей между двумя датами.

dayAsSql

Возвращает частичную строку SQL для поиска всех записей между двумя временными отметками одного дня.

isThisYear

Возвращает true если данная строка времени-даты в пределах текущего года.

wasYesterday

Возвращает true если данная строка времени-даты была вчера.

isTomorrow

Возвращает true если данная строка времени-даты будет завтра.

toUnix

Возвращает временную отметку UNIX из текстового описания времени-даты.

toAtom

Возвращает дату, форматированную для Atom RSS.

toRSS

Форматирует дату для RSS.

timeAgoInWords

Возвращает либо относительную дату либо форматированную дату, в зависимости от разницы между текущим временем и данными времени-даты. $datetime должна быть в формате strtotime как время-дата My SQL?.

relativeTime

Работает как timeAgoInWords(), но включает в себя способность создатвать также временные отметки и в будущем (например «Вчера 10:33", «Сегодня 9:42", и также «Завтра 4:34").

relativeTime

Возвращает 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

Решает вывести или вернуть строку, базируясь на AUTO_OUTPUT (см. /app/config/core.php) и значении $return. Используйте эту функцию для возврата данных в ваше отображение.

loadConfig

Возвращает текущую центральную настройку вашего приложение и определения тегов.


Давайте используем 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 хелпер в масив если планируете его где-то использовать. Схема присвоения имен та же, что и у моделей.

  1. LinkHelper = имя класса
  2. link = ключ в масиве хелперов
  3. link.php = имя файла php в /app/views/helpers.

Содействие

Пожалуйта обратите внимание на то, чтобы дать свой код Cake – свяжитесь с одним из разработчиков, или откройте новый проет Cake Forge? чтобы поделиться своим новым хелпером с другими.


 
Комментарии

Как выхвать свой хэлпер в элемент?

108-149-124-91.pool.ukrtel.net (2009-01-09 19:16:04)
как предварительно чекнуть radio ?

$options=array('M'=>'Male','F'=>'Female');
$attributes=array('legend'=>false);
echo $form->radio('gender',$options,$attributes);

как выбрать по дефолту F?
195.12.102.12 (2010-02-15 09:00:00)
Добавить комментарий:

Файлы [Скрыть файлы/форму]