10. 헬퍼 (Helpers)

 

 

10. 헬퍼 (Helpers)^#

 

10.1. 헬퍼^#

헬퍼는 편리한 방법으로 데이터를 가공하고 표현하기 위해 뷰에서 일반적으로 필요한 함수를 제공하는 것이다

10.1.1. HTML^#

10.1.1.1. 소개^#

HTML 헬퍼는, 단조로운 일을 줄이고, 좀 더 빠르게 개발할 수 있도록 하는 Cake 의 방식의 하나다. HTML 헬퍼에게는 두가지 주요 목표가 있다. 그것은, 자주 사용하는 HTML 코드를 삽입할 수 있도록 하는 것, 그리고 웹 폼을 빠르고 간단히 작성할 수 있도록 하는 것이다. 계속되는 섹션에서, 헬퍼의 주요 함수에 대해서 설명하지만, 최종적 레퍼런스로, http://api.cakephp.org 를 읽어야 하는 것을 꼭 기억하라.

 

HTML 헬퍼내의 함수가 사용하고 있는 HTML 태그의 정의는, tags.ini.php 라는 파일에 있다. Cake 의 코어 설정으로 tags.ini.php 가 있지만, 변경을 더하고 싶은 경우는, /cake/config/tags.ini.php 의 복사본를 만들고, 자신의 /app/config/ 폴더에 넣는다. HTML 헬퍼는 리퀘스트된 태그의 생성에 이 파일의 태그 정의를 사용한다. tags.ini.php 파일을 변경하면 사이트 전체가 변경이 되기 때문에, HTML 헬퍼에 뷰의 코드를 작성하면 편리하다.

 

부가적으로, 코어의 config 파일( /app/config/core.php ) 내에, AUTO_OUTPUT 이 true 로 설정되면, 헬퍼는 값을 반환하는 것은 아니고, 자동적으로 태그를 출력하게 된다. 이것은, short tag (<?= ?>) 의 사용이나 많은 echo() 호출 등을 뷰 코드에 넣기 싫어 하는 이들을 위해서 구현되었다. $return 파라미터를 사용하면, 코어의 config 의 설정을 강제적으로 오브라이드할 수 있다. AUTO_OUTPUT 의 설정으로 관계되어 없이, HTML 헬퍼가 HTML 코드를 반환하도록 하고 싶은 경우, $return 을 true 로 설정한다.

 

또한, HTML 헬퍼의 기능에는, $htmlAttributes 파라미터가 포함되고 있다. 이것은, 태그에 추가 속성을 더 할 수 있도록 하는 것이다. 예를 들면, class 속성을 추가하고 싶은 태그가 있는 경우, 그것을 $htmlAttribute 값을 사용해 아래와 같이 지정할 수 있다.

 

1. array('class'=>'someClass')

 

10.1.1.2. 잘 포맷된 요소 (Well-Formatted elements) 삽입하기^#

HTML 코드 속에 잘 포맷 되었고, 여러 번 반복하는 요소를 Cake 를 사용해 삽입하고 싶은 경우, HTML 헬퍼가 그 작업에 적격이다. 이 헬퍼 중에는, 미디어, 테이블을 만드는 데 도움이 되는 함수나, PHP 의 배열에 기초하고, ul 요소의 리스트를 만드는 guiListTree 등도 있다.

 

• charset
  • string $charset
  • boolean $return

 

이것은, charset 의 meta 태그를 생성할 때 사용한다.

 

• css
  • string $path
  • string $rel = 'stylesheet'
  • array $htmlAttributes
  • boolean $return = false

 

CSS 스타일 시트에의 링크를 만듭니다. $rel 파라미터에, 태그의 rel=값 을 지정할 수 있다.

 

• image
  
  • string $path
  • array $htmlAttributes
  • boolean $return = false

 

image 태그를 표시합니다. 이 함수로 리턴된 코드는, link() 함수의 입력으로서 사용할 수 있기 때문에, 링크된 이미지를 자동 생성할 수 있다.

 

• link
  • string $title
  • string $url
  • array $htmlAttributes
  • string $confirmMessage = false
  • boolean $escapeTitle = true
  • boolean $return = false

 

뷰에 링크를 작성할때 이 함수를 사용해 한다. 링크를 클릭 했을 때 한 번, 자바스크립트로 확인 메세지를 표시시킬 경우, $confirmMessage 를 이용한다. 예를 들면, 어떤 오브젝트를 삭제하는 링크이면, 링크 앞의 액션을 실행하기 전에 "정말로 삭제하시겠습니까?" 의 메세지를 나타낼 수 있다. 만일, $title 변수에 전달되는 데이터를 HTML 헬퍼가 escape 하도록 하고 싶은 경우에는, $escapeTitle 를 true 로 설정하면 된다.

 

• 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

 

배열에서 ul 요소의 리스트 트리를 생성한다.

 

10.1.1.3. 폼과 자료 검증^#

HTML 헬퍼는, 뷰 내에 폼의 코드를 신속하게 만들 때에 대단한 빛을 발한다. 폼 태그를 전부 생성하고, 에러가 일어난 경우에는 자동적으로 값을 채워 되돌리고, 에러 메세지를 해당하는 장소에 표시한다. 이해하기 쉽도록, 짧은 예를 보도록 하자. 애플리케이션에 Note 모델이 있고, Note 의 오브젝트(데이터)를 추가, 편집하기 위한 컨트롤러 로직과 뷰를 작성한다고 하자. NotesController 에서, edit 액션은 다음과 같이 될 것이다 :

 

예10.1. NotesController 의 Edit 액션 내부

 

1.    function edit($id)
      {
         //먼저 폼데이터가 이 액션에 의해 
         //전송되었는지 아닌지를 체크한다.
         if (!empty($this->data['Note']))
         {
            //여기서 폼데이터의 검증을 한다. (12장 참조)
            //그리고 저장한다.
            if ($this->Note->save($this->data['Note']))
            {
               //저장이 잘 되었을 경우,
               //유저를 적당한 장소로 이동시킨다.
               $this->flash('Your information has been saved.', '/notes/edit/' . $id);
               exit();
            }
            else
            {
   
               //해당하는 필드 위치에 에러 메시지를 생성한다.
               //save 가 작용하기 때문에, 실제로는 필요하지 않지만, 이것은 예이다.
               //save 하지 않을 경우, $this->Note->validates($this->data['Note']); 를 호출하도록 한다.
               //그리고 아래 메소드를 사용하여, tagErrorMsg() 헬퍼 메소드에 값을 출력한다.
               $this->validateErrors($this->Note);
   
               //그리고 edit view 코드를 출력한다.
               $this->render();
            }
         }
   
         // 아직 폼 데이터를 아무것도 전송 받지 않았을 경우, 편집하고 싶은 note 를 받고
         // 그 정보를 뷰에 전달한다
         $this->set('note', $this->Note->find("id = $id"));
         $this->render();
      }

 

컨트롤러를 설정해 보았기에, 뷰 코드( app/views/notes/edit.thtml 에 있다. )를 보자.  Note 모델은 지금의 시점에는 꽤 간단하고, id 와 송신자의 id, 본문(body)밖에 없다. 이 뷰 코드는, Note 데이타를 표시하고, 유저가 새로운 값을 입력하고, 모델에 데이타를 저장할 수 있게 한다.

 

HTML 헬퍼는 기본적으로 모든 뷰에서 사용할 수 있고, $html 로 액세스한다.

 

특히, 폼의 중요한 부분의 테이블을 보자 :

 

예10.2. Edit view의 코드 (edit.thtml) 샘플

 

1. <!-- 이 태그는 폼태그를 작성한다 -->
   
   <?php echo $html->formTag('/notes/edit/' . $html->tagValue('Note/id')?>
   
   <table cellpadding="10" cellspacing="0">
   <tr>
      <td align="right">Body: </td>
      <td>
   
         <!-- 여기에 HTML 헬퍼를 사용하여 text area 태그,
   컨트롤러에 의해 작성된 $note 변수,
   편집하고 있는 데이터 등을 표시한다 -->
         <?php echo
         $html->textarea('Note/body', array('cols'=>'60', 'rows'=>'10'));
         ?>
         <?php echo $html->tagErrorMsg('Note/body',
         '이 노트에 내용을 입력해 주십시오.') ?>
      </td>
   </tr>
   <tr>
      <td></td>
      <td>
   
         <!-- 또한 HTML helper 로 테이블 안에
              hidden 태그를 넣을 수 있다 -->
   
         <?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 파라미터에 폼으로 넘겨받는 문자열은, "모델명/필드명" 형식이다. Note 에 이번에 title 필드를 추가하고 싶다면, 뷰에 아래와 같은 코드를 더한다:

 

1. <?php echo $html->input('Note/title') ?>
2. <?php echo $html->tagErrorMsg('Note/title', '이 노트에 제목을 입력해 주십시오.')?>

 

tagErrorMsg() 함수에 표시되는 에러 메세지는, CSS 로 스타일링하기 쉽도록, <div class="error_message"></div> 로 둘러 쌓여 있다.

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 파라미터와 같은 방법으로 다룬다. 이 날짜 옵션 태그에 관련된 필드명을 지정한다. 데이터가 처리되면, 콘트롤러 내에서는 필드명이 끝나는 날짜의 일부분의 이름(year,month,day...)이 연결된 것으로 보인다. 일례로서, Note 가 deadline 이라는 날짜 필드를 갖고 있고, dayOptionTag 의 $tagName 파라미터가 'note/deadline' 로 설정 되어 있으면, 폼이 컨트롤러 액션에 전송되었을 때 날짜 데이터가 $params 변수에 나타난다:

 

1. $this->data['Note']['deadline_day']

 

현재의 데이터베이스 설정에 따라, 이 정보를 시간의 데이터로서 연결해 맞출 수 있다. 이 코드는 데이터를 저장하기 직전에 위치하고, $data 배열 중에 저장되며 그 정보가 모델에 저장된다.

 

예10.3. 모델을 저장하기 전, time 데이터를 연결한다 ( NotesController 에서 발췌)

 

1. 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)

 

10.1.2. AJAX^#

Cake 의 ajax 헬퍼는, Ajax 의 조작과 클라이언트 사이드의 효과를 위해서, 굉장이 유명한 Prototype 과 script.aculo.us 라이브러리를 이용한다. 이 헬퍼를 사용하려면, http://script.aculo.us 에서 최신 버전의 자바스크립트 라이브러리를 다운 받아, /app/webroot/js/ 에 넣는다. 또 ajax 헬퍼를 사용할 예정인 모든 뷰에, 이러한 라이브러리를 include 한다.

 

이 헬퍼의 대부분의 함수에는, 특별한 $options 배열이 파라미터로서 필요하다. 이 배열은 ajax 조작에 관한 여러가지 사항을 지정할때 사용한다. 지정할 수 있는 여러가지 값에는 다음과 같다.

 

예 10.4. AjaxHelper $options Keys

 

1. /* General Options */
   
   $options['url']         // 호출하기 원하는 액션의 URL.
   
   $options['frequency']   // remoteTimer() 또는
                           // observeField() 가 체크를 실행하기까지의 초단위 시간.
   
   $options['update']      // Ajax 조작 결과를
                           // 업데이트하고 싶은 요소의 DOM ID.
   
   $options['with']        // Ajax 의 폼 전송에
                           // serialize 하고,  전송하는 폼 요소의 DOM ID.
   
   $options['type']        // 'asynchronous' (기본) 또는,  'synchronous'
                           // 옵션 선택.
   
   /* 콜백:XMLHttpReques 프로세스 동안
   여러번 실행되는 JS 코드 */
   
   $options['loading']     // 브라우저에 원격 문서의 데이터가
                           // 로딩중일때 실행되는 JS 코드.
   
   $options['loaded']      // 브라우저가 원격 문서에 로딩을
                           // 마쳤을 때 실행되는 JS 코드.
   
   $options['interactive'] // 로딩이 마치지 않아도, 사용자가 원격 문서와
                           // 송수신 가능할 때 실행되는 JS 코드.
   
   $options['complete']    // XMLHttpRequest 가 완료되었을때
                           // 호출되는 JS 코드.
   
   $options['confirm']     // XMLHttpRequest 액션이 시작되기 전에
                           // cconfirm 대화상자에 표시되는 텍스트.
   
   $options['condition']   // XMLHttpRequest 를  초기화하기 전에 충족되어야 하는
                           // JS 조건
   
   $options['before']      // 리퀘스트가 초기화되기 전에 호출되는 JS 코드.
   
   $options['after']       // 리퀘스트가 초기화되고,
                           // 'loading' 이 시작되는 직전에 호출되는 JS code.

 

다음은 Cake 에서 Ajax 를 빠르고 간단하게 작성하기 위한 헬퍼 함수들이다 :

 

• link
  • string $title
  • string $href
  • array $options
  • boolean $confirm
  • boolean $escapeTitle

 

링크를 텍스트 $title 를 표시한다. $options['url'] 에 있는 원격문서를 로딩하고 $options['update'] 로 지정된 DOM 요소를 업데이트한다. 이 함수에 콜백을 사용할 수 있다.

 

• remoteFunction
  • array $options

 

이 함수는 원격 호출이 필요한 자바스크립트를 만든다. 주로, linkToRemote 의 헬퍼로 사용된다. 커스터마이징한 스크립트를 생성하는 것은 아니면, 이 함수는 자주 사용하지 않는다.

 

• remoteTimer
  • array $options

 

정기적으로 $options['url'] 로 지정된 액션을 $options['frequency'] (기본값은 10)초마다 호출한다. 보통, 리모트 호출의 결과로, 특정 div ($options['update'] 으로 지정)을 업데이트할 때 사용한다. 이 함수에서는 콜백을 사용할 수 있다.

 

• form
  • string $action
  • string $type
  • array $options

 

일반적으로 리로드가 필요한 POST 전송 대신, XMLHttpRequest 를 사용하여 $action 에 지정된 액션을 백그라운드에 전송하는 폼 태그를 반환한다. 이 폼으로 전송된 데이터는, 보통 폼 데이타와 같이 행동한다 ($ this->param['form'] 로 이용할 수 있다). $options['update'] 로 지정된 DOM 요소가 원격 문서의 결과로 업데이트 된다. 이 함수는 콜백을 사용할 수 있다.

 

• observeField
  • string $field_id
  • array $options

 

$field_id 로 지정된 DOM ID 의 필드를 ($options['frequency'] 초마다) 관찰하고, 내용이 변경되었을 때 $options['url'] 의 액션을 실행한다. ID $options['update'] 또는 $options['with'] 로 폼 요소를 지정하고, DOM 요소를 업데이트하는 것도 가능하다. 이 함수는 콜백을 사용할 수 있다.

 

• observeForm
  • string $form_id
  • array $options

 

observeField() 와 같이 작동한다. 이 함수는 지정된 폼의 모든 요소 외에는 관찰하지 않는다.

 

• autoComplete
  • string $field
  • string $url
  • array $options

 

ID $field 를 자동 완성이 붙은 텍스트 필드로 표시한다. $url 의 액션은, 자동 완성의 용어 리스트를 리턴해야 한다 : 기본적으로 액션은 자동 완성의 용어를 ul 요소 (<ul></ul>) 의 리스트 항목에서 내는 것이 필요합니다. 블로그에 작성한 제목을 불러내는 자동 완성 필드를 작성하고 싶은 경우, 컨트롤러의 액션은 다음과 같다:

 

1. function autocomplete ()

2. {

3.     $this->set('posts',

4.         $this->Post->findAll(

5.             "subject LIKE '{$this->data['Post']['subject']}'")

6.         );

7.     $this->layout = "ajax";

8. }

위 autocomplete() 액션에 대한 뷰는 이와 같다 :

 

1. <ul>
   <?php foreach($posts as $post): ?>
   <li><?php echo $post['Post']['subject']; ?></li>
   <?php endforeach; ?>
   </ul>

 

뷰내의 실제 자동 완성 필드는 아래와 같다:

 

1. <form action="/users/index" method="POST">
       <?php echo $ajax->autoComplete('Post/subject', '/posts/autoComplete')?>
       <?php echo $html->submit('View Post')?>
   </form>

autoComplete() 함수는 텍스트 필드와 액션이 작성한 자동 완성 용어 리스트를 표시하기 위해 사용하는 몇가지의 div 의 표시에 이 정보를 사용한다. 또 아래와 같이 하여 뷰의 스타일도 설정할 수 있다 :

 

1. <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
  • string $id
  • array $options

 

ID 가 $id 인 DOM 요소를 드래그할 수 있게 만든다. $options 을 사용하면, 기타 추가 사항도 지정할 수 있다.

 

1. // (버전 번호는,  script.aculo.us 의 버전이다. )
   
   $options['handle']     // (v1.0) 임베디드 핸들에 의해서만 드래그할 수 있도록
                          // 할 것인지 설정한다. 값은 반드시
                          // 요소의 레퍼런스나 요소의 ID 여야한다.
   
   $options['handle']     // (V1.5) 앞서 말한 대로, 값은 CSS 의 클래스치를 나타내는 문자열이다.
                          // 최초의 아들(child)/손자(grandchild)/등이다.
                          // 이 CSS 클래스 값을 가진 요소내의 요소는, 핸들로서 이용된다.
   
   $options['revert']     // V1.0) true 로 설정하면, 드래그가 끝났을 때
                          // 요소(element)는 원래의 위치를 반환한다.
   
   $options['revert']     // (V1.5) Revert 도 임의의 함수 레퍼런스가 될 수 있고, 
                          // 드래그가 끝났을 때 호출된다.
   
   $options['constraint'] // horizontal 또는 vertical 로 설정되면,
                          // 드래그 방향이 횡방향 또는
                          // 종방향으로 제한된다.

 

• drop
  • string $id
  • array $options

 

ID $id 로 지정된 DOM 요소를 드롭할 수 있게 한다. $options 를 사용해 지정할 수 있는 몇가지 추가 사항이 있다.

 

1. $options['accept']      // CSS 클래스를 나타낸 문자열 또는 자바스크립트의 배열을  accept 에 지정한다.
                           // 드롭 가능한 것은, 드래그할 수 있도록 되어 있다.
                           // CSS 클래스를 하나 이상 갖고 있는 것만을 받아들인다.
   
   $options['containment'] // 드롭 가능한 요소는, 지정된 요소(또는 요소 ID)로 제한되어 있는 경우,
                           // 그 드래그할 수 있는 요소만을 받아들인다.
                           // 단일 요소 또는 요소의 JS 배열일 수 있다.
   
   $options['overlap']     // horizontal 또는 vertical 로 설정될 때,
                           // 지정된 방향으로 50% 이상 겹친 경우에,
                           // 드롭 가능한 것은 드래그할 수 있는 요소에 대해서만 반응한다.

 

• dropRemote
  • string $id
  • array $options
  • array $ajaxOptions

 

드래그할 수 있는 요소가 드롭되었을 때 XMLHttpRequest 를 시작하는 드롭 대상을 작성하기위해 사용된다. $options 은 drop() 과 같고, $ajaxOptions 은 link() 와 같다.

 

• sortable
  • string $id
  • array $options

 

float 오브젝트의 그룹 또는 리스트 (DOM요소 ID $id 로 지정) 를 정렬할 수 있게 한다. $options 배열을 다음과 같은 정렬 방법을 설정할 수 있다:

 

1. $options['tag']         // 정렬 가능한 태그 (컨테이너(container) 의 자식 요소(child element)) 의 종류를 설정한다.
                           // UL 과 OL 컨테이너용으로, 이것은
                           // LI 이다. 자식 태그 (child tag) 의 기타의 정렬용으로
                           // 태그의 종류를 지정할 필요가 있다.
                           // 기본값은 'li' 이다.
   
   $options['only']        // 자식 요소의 선택을,
2.                         // 지정된 CSS 클래스를 포함하는 요소만을 포함도록, 더 제한한다.
                           // (또는, 문자열의 배열을 설정한 경우는, 어떤 클래스상이라도. )
   
   $options['overlap']     // vertical(기본값) 또는 horizontal 이다. 
                           // floating sortables 또는 horizontal lists 는 horizontal 을 선택한다.
                           // vertical list 는 vertical 이어야 한다.
   
   $options['constraint']  // 드래그할 수 있는 요소의 움직임을
                           // vertical'(종방향) 또는 'horizontal'(횡방향) 으로 제한한다.
   
   $options['containment'] // sortable 사이에서 드래그와 드롭을 가능하게 한다..
                           // (콘테이너의)요소의 배열 또는 요소의 id 의 배열을 잡는다.
   
   $options['handle']      // 작성된 드래그 가능 요소가 핸들을 사용하도록 한다.
                           //  drag() 의 handle 옵션을 참조하라.

 

• editor
  • string $id
  • string $url
  • array $options

 

첫번째 파라미터로서 지정된 DOM id 의 요소를 사용하고, in-place ajax 에디터를 작성한다. 구현되면, mouseOver 로 하이라이트 되고, 클릭하면 단일의 텍스트 입력 필드로 변한다. 두번째 파라미터는, 편집한 데이타가 보내져야 하는 URL 입니다. 액션도 갱신된 요소의 내용을 반하라. in-place 에디터의 추가 옵션은, Script.aculo.us wiki 에서 참조한다.

 

10.1.3. 자바스크립트^#

자바스크립트 헬퍼는 자바스크립트에 관한 태그와 데이타를 잘 포맷 된 형태로 출력할 수 있도록 개발자를 도와준다.

 

• codeBlock
  • string $string

 

$script 를 자바스크립트의 <script> 태그로 둘러싼 뒤 반환한다.

 

• link
  • string $url

 

$url 로 참조되는 스크립트를 자바스크립트 인클루드 태그로 반환한다..

 

• linkOut
  • string $ur

 

link()와 같지만, 인클루드 태그는 $url 로 참조되는 스크립트와 같은 도메인이 아니라고 가정한다.

 

• escapeScript
  • string $script

 

자바스크립트의 코드 부분 처리를 위해 캐리지 리턴(CR), 싱글 쿼트( ' ), 더블 쿼트( " ) 를 escape 한다.

 

• event
  • string $object
  • string $event
  • string $observer
  • boolean $useCapture

 

Prototype 라이브러리를 사용하여 요소에 이벤트를 덧붙인다.

 

• cacheEvents

 

event() 로 작성된 자바스크립트 이벤트를 캐시한다.

 

• writeEvents

 

cacheEvents() 로 캐시된 캐시 이벤트를 기록한다.

 

• includeScript
  • string $script

 

10.1.4. 숫자^#

숫자 헬퍼는 뷰내에서 숫자에 관한 데이터를 포맷하기 위한 몇가지 아주 좋은 함수가 포함되어 있다.

 

• precision
  • mixed $number
  • int $precision = 3

 

$precision 로 지정된 레벨의 정밀도로 포맷된 $number 를 반환한다.

 

• toReadableSize
  • int $sizeInBytes

 

$size 로 지정한 Byte 를 사람이 읽을 수 있게 하여 반환한다. 기본적으로 몇 Byte 인지 입력하면 사람이 읽을 수 있는 적당한 값 KB, MB, GB, TB 로 반환한다.

 

• toPercentage
  • mixed $number
  • int $precision = 2

 

입력된 숫자를 $precision 로 지정된 범위의 퍼센티지(%)로 포맷하여 반환한다.

 

10.1.5. 문자^#

문자 헬퍼는, 개발자가 텍스트를 브라우저에 출력할 때 필요한 메소드를 제공한다.

 

• highlight
  • string $text
  • string $highlighter = '<span class="highlight">\1</span>'

 

$text 속에 포함된 $phrase 를 모두 $highlighter 로 지정한 태그로 둘러싼 뒤 반환한다.

 

• stripLinks
  • string $text

 

HTML 링크 (<a href= ...) 을 제외하고 $text 를 반환한다.

 

• autoLinkUrls
  • string $text
  • array $htmlOptions

 

대응하는 <a> 태그로 둘러싸인 URL 로 $text 를 반환한다.

 

• autoLinkEmails
  • string $text
  • array $htmlOptions

 

대응하는 <a> 태그로 둘러싸인 이메일 주소로 $text 를 반환한다.

 

• autoLink
  • string $text
  • array $htmlOptions

 

대응하는 <a> 태그로 둘러싸인 URL 과 이메일 주소로 $text 를 반환한다.

 

• truncate
  • string $text
  • int $length
  • string $ending = '...'

 

$text 를 최초의 $length 길이의 문자로 반환한다. 문자 끝에 $ending (기본값은 '...' )을 붙는다.

 

• excerpt
  • string $text
  • string $phrase
  • int $radius = 100
  • string $ending = '...'

 

$text 로부터 $radius 로 정해진 각각의 위치에 있는 다수의 문자로 $phrase 를 잡아내 인용을 추출한다.

Extracts an excerpt from the $text, grabbing the $phrase with a number of characters on each side determined by $radius.

 

• autoLinkEmails
  • string $text
  • boolean $allowHtml = false

 

텍스트를 HTML로 파싱한다, 구문은 조금 다르나, Textile 이나 RedCloth 를 닮았다.

 

10.1.6. 시간^#

시간 헬퍼는 유닉스 타임스탬프나 datetime 문자열을 좀 더 이해하기 쉬운 형태로 브라우저에 출력하기 위해, 개발자가 필요로 하는 것을 제공한다.

모든 함수에 대해, 날짜는, 유효한 PHP datetime 문자열이나 유닉스 타임스탬프 중 어떤 것을 지정해도 된다.

 

• fromString
  • string $dateString

 

유닉스 타임스탬프 또는 유효한 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() 와 같은 형태로 포맷하지만, 문자열이 오늘이 경우에는 "Today, 12:00" 과 같이 출력하고, 어제이면, "Yesterday, 12:00" 과 같이 출력합니다.

 

• isToday
  • string $dateString

 

지정된 datetime 문자열이 오늘이면 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

 

입력받은 datetime 문자열이 올해면, ture 를 반환한다.

 

• wasYesterday
  • string $dateString
  • boolean $return = false

 

입력받은 datetime 문자열이 어제이면, ture 를 반환한다.

 

• isTomorrow
  • string $dateString
  • boolean $return = false

 

입력받은 datetime 문자열이 내일이면, ture 를 반환한다.

 

• toUnix
  • string $dateString
  • boolean $return = false

 

텍스트에 기술된 datetime 을 유닉스 타임스탬프로 반환한다. PHP strtotime() 함수의 래퍼다.

 

• toAtom
  • string $dateString
  • boolean $return = false

 

Atom RSS 피드용 날짜 포맷을 반환한다.

 

• toRSS
  • string $dateString
  • boolean $return = false

 

RSS 피드용 날짜 포맷을 반환한다.

 

• timeAgoInWords
  • string $dateString
  • boolean $return = false

 

현재의 시간과 입력 받은 datetime 의 차에 기초하여 상대적인 날짜 또는 포맷된 날짜를 반환한다. $datetime 은 MySQL datetime 과 같이, strtotime 으로 파싱 가능한 포맷이어야 한다.

 

• relativeTime
  • string $dateString
  • boolean $return = false

 

timeAgoInWords() 와 같이 작동하지만, 미래의 타임스탬프도 출력할 수 있다. ("Yesterday, 10:33", "Today, 9:42", "Tomorrow, 4:34". )

 

• relativeTime
  
  • string $timeInterval
  • string $dateString
  • boolean $return = false

 

지정된 datetime 이 지정된 interval 의 사이에 속하면 true 를 반환하고, 아니면 false 를 반환한다. 시간의 간격은 숫자 또는 '6 hours', '2 days' 등과 같이 지정한다.

 

10.2. 자신의 헬퍼 작성하기^#

뷰 코드에 도움이 좀 필요한 적 있는가? 만일 뷰로직의 특정한 코드가 계속해서 반복되는 것을 발견했다면, 자기 자신만의 뷰 헬퍼를 만들 수 있다.

10.2.1. Cake 헬퍼 클래스 확장(extend)^#

애플리케이션 중에서, CSS로 스타일을 조절한 링크를 출력하는 헬퍼를 작성한다고 하자. Cake 의 기존 헬퍼 구조로 맞추기 때문에, /app/views/helpers 속에 새로운 클래스를 작성해야 한다. LinkHelper 라는 이름으로 한다. 실제의 PHP 클래스 파일은, 이와 같다:

 

예 10.5. /app/views/helpers/link.php

 

1. class LinkHelper extends Helper
   {
       function makeEdit($title, $url)
       {
           // 링크를 조정하는 로직은 여기에...
       }
   }

 

활용할 수 있는 Cake 의 헬퍼 클래스의 몇가지 함수가 있다:

 

• output
  • string $string
  • boolean $return = false

 

AUTO_OUTPUT ( /app/config/core.php 를 참조)에 기초하여, 출력하는지, 문자열로 반환하는지를 결정한다. 뷰에 되돌리고 싶은 데이터가 있는 경우에는 이 함수를 사용한다.

 

• loadConfig

 

애플리케이션으로, 현재의 코어 정의와 태그 정의를 반환한다.

링크의 타이틀과, URL 을 output() 으로 조정한 뒤 뷰에 리턴해 보자.

 

예 10.6. /app/views/helpers/link.php (로직추가)

 

1. class LinkHelper extends Helper
   {
       function makeEdit($title, $url)
       {
           // 헬퍼의 출력 함수를 사용하고,  조절한 데이터를
           // 뷰에 반환한다:
   
           return $this->output("<div class=\"editOuter\"><a href=\"$url\" class=\"edit\">$title</a></div>");
       }
   }

 

10.2.2. 다른 헬퍼의 포함^#

다른 헬퍼의 기존 기능을 이용하고 싶은 경우가 있다. 이 경우는 컨트롤러에서의 경우와 같은 서식에, 사용하고 싶은 헬퍼를 $helpers 배열에 지정할 수 있다.

 

예10.7. /app/views/helpers/link.php (다른 헬퍼 사용)

 

1. 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>");
       }
   }

 

10.2.3. 커스텀 헬퍼 사용^#

헬퍼를 작성하고, /app/views/helpers/ 에 넣으면, 컨트롤러내에서는 $helpers 라는 특별한 변수에 그것을 include 할 수 있게 된다.

 

1. class ThingsController
   {
       var $helpers = array('Html', 'Link');
   }

 

어떤 부분에 HTML 헬퍼를 사용할 예정이면, 잊지 않고 포함시켜야 한다. 네이밍 규약은 모델과 같다.

 

1. LinkHelper = 클래스명

2. link = 헬퍼 배열내에서의 키

3. link.php = /app/views/helpers 내의 PHP 파일명.

 

10.2.4. 기여하기^#

Cake 에 당신의 코드를 제공하는 것도 고려해 주기 바란다 - trac 시스템이나 메일링 리스트의 개발자게 알릴 수 있고, CakeForge 로 새로운 프로젝트를 열고, 새로운 헬퍼를 다른 사람에게 배포할 수 있다.