Helpers¶

Edit Action inside of the NotesController¶

<?php
function edit($id)
{
  //First, let's check to see if any form data has been
  //submitted to the action.
  if (!empty($this->data['Note']))
  {
     //Here's where we try to validate the form data (see Chap. 12)
     //and save it
     if ($this->Note->save($this->data['Note']))
     {
        //If we've successfully saved, take the user
        //to the appropriate place
        $this->flash('Your information has been saved.', '/notes/edit/' . $id);
        exit();
     }
     else
     {

        //Generate the error messages for the appropriate fields
        //this is not really necessary as save already does this, but it is an example
        //call $this->Note->validates($this->data['Note']); if you are not doing a save
        //then use the method below to populate the tagErrorMsg() helper method
        $this->validateErrors($this->Note);

        //And render the edit view code
        $this->render();
     }
  }

  // If we haven't received any form data, get the note we want to edit, and hand
  // its information to the view
  $this->set('note', $this->Note->find("id = $id"));
  $this->render();
}

Once we’ve got our controller set up, let’s look at the view code (which would be found in app/views/notes/edit.thtml). Our Note model is pretty simple at this point as it only contains an id, a submitter’s id and a body. This view code is meant to display Note data and allow the user to enter new values and save that data to the model.

The HTML helper is available in all views by default, and can be accessed using $html.

Specifically, let’s just look at the table where the guts of the form are found:

Edit View code (edit.thtml) sample¶

<!-- This tag creates our form tag -->

<?php echo $html->formTag('/notes/edit/' . $html->tagValue('Note/id')) ?>

<table cellpadding="10" cellspacing="0">
<tr>
   <td align="right">Body: </td>
   <td>

      <!-- Here's where we use the HTML helper to render the text
           area tag and its possible error message the $note
           variable was created by the controller, and contains
           the data for the note we're editing. -->
      <?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>

      <!-- We can also use the HTML helper to include
           hidden tags inside our table -->

      <?php echo $html->hidden('Note/id')?>
      <?php echo $html->hidden('note/submitter_id', $this->controller->Session->read('User.id'))?>
   </td>
</tr>
</table>

<!-- And finally, the submit button-->
<?php echo $html->submit()?>

</form>

Most of the form tag generating functions (along with tagErrorMsg) require you to supply a $fieldName. This $fieldName lets Cake know what data you are passing so that it can save and validate the data correclty. The string passed in the $fieldName parameter is in the form “modelname/fieldname.” If you were going to add a new title field to our Note, you might add something to the view that looked like this:

<?php echo $html->input('Note/title') ?><br />
<?php echo $html->tagErrorMsg('Note/title', 'Please supply a title for this note.')?>

Error messages displayed by the tagErrorMsg() function are wrapped in <div class=”error_message”></div> for easy CSS styling.

Here are the form tags the HTML helper can generate (most of them are straightforward):

• 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

• string $title = null

• 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

The HTML helper also includes a set of functions that aid in creating date-related option tags. The $tagName parameter should be handled in the same way as the $fieldName parameter. Just provide the name of the field this date option tag is relevant to. Once the data is processed, you’ll see it in your controller with the part of the date it handles concatenated to the end of the field name. For example, if my Note had a deadline field that was a date, and my dayOptionTag $tagName parameter was set to ‘note/deadline’, the day data would show up in the $params variable once the form has been submitted to a controller action:

<?php
$this->data['Note']['deadline_day']

You can then use this information to concatenate the time data in a format that is friendly to your current database configuration. This code would be placed just before you attempt to save the data, and saved in the $data array used to save the information to the model.

Pre-populating a form element is done by supplying a ‘value’ key-value pair in the $htmlAttributes parameter. For text-based fields, the value will be shown in the form element. For discrete form elements, supply the id or key of the element you’d like to have be selected by default:

<?php
// Sets the radio element with
// 'Complete' selected by default.<br />
$html->radio('Note/status', array('1' => 'Complete', '2' => 'In Progress'), null, array('value' => '1'));

Concatenating time data before saving a model (excerpt from NotesController)¶

<?php
function edit($id)
   {
      //First, let's check to see if any form data has been submitted to the action.
      if (!empty($this->data['Note']))
      {

         //Concatenate time data for storage...
         $this->data['Note']['deadline'] =
            $this->data['Note']['deadline_year'] . "-" .
            $this->data['Note']['deadline_month'] . "-" .
            $this->data['Note']['deadline_day'];

         //Here's where we try to validate the form data (see Chap. 10) and save it
         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)

General Options¶

Callbacks¶

JavaScript code to be executed at certain times during the XMLHttpRequest process.

Here are the helper’s functions for making Ajax in Cake quick and easy:

• link

• string $title

• string $href

• array $options

• boolean $confirm

• boolean $escapeTitle

Displays linked text $title, which retrieves the remote document at $options[‘url’] and updates the DOM element $options[‘update’]. Callbacks can be used with this function.

• remoteFunction

• array $options

This function creates the JavaScript needed to make a remote call. It is primarily used as a helper for linkToRemote. This isn’t often used unless you need to generate some custom scripting.

• remoteTimer

• array $options

Periodically calls the specified action at $options[‘url’], every $options[‘frequency’] seconds (default is 10). Usually used to update a specified div (specified by $options[‘update’]) with the results of the remote call. Callbacks can be used with this function.

• form

• string $action

• string $type

• array $options

Returns a form tag that will submit to the action at $action using XMLHttpRequest in the background instead of the regular reload-required POST submission. The form data from this form will act just as a normal form data would (i.e. it will be available in $this->params[‘form’]). The DOM element specified by $options[‘update’] will be updated with the resulting remote document. Callbacks can be used with this function.

• observeField

• string $field_id

• array $options

Observes the field with the DOM ID specified by $field_id (every $options[‘frequency’] seconds) and calls the action at $options[‘url’] when its contents have changed. You can update a DOM element with ID $options[‘update’] or specify a form element using $options[‘with’] as well. Callbacks can be used with this function.

• observeForm

• string $form_id

• array $options

Works the same as observeField(), only this observes all the elements in a given form.

• autoComplete

• string $field

• string $url

• array $options

Renders a text field with ID $field with autocomplete. The action at $url should be able to return the autocomplete terms: basically, your action needs to spit out an unordered list (<ul></ul>) with list items that are the auto complete terms. If you wanted an autocomplete field that retrieved the subjects of your blog posts, your controller action might look something like:

<?php
function autocomplete ()
{
    $this->set('posts',
        $this->Post->findAll(
            "subject LIKE '{$this->data['Post']['subject']}'")
        );
    $this->layout = "ajax";
}

And your view for the autocomplete() action above would look something like:

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

The actual auto-complete field as it would look in a view would look like this:

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

The autoComplete() function will use this information to render a text field, and some divs that will be used to show the autocomplete terms supplied by your action. You might also want to style the view with something like the following:

<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

Makes the DOM element with ID $id draggable. There are some additional things you can specify using $options (The version numbers refer to script.aculo.us versions):

• drop

• string $id

• array $options

Makes the DOM element with ID $id drop-able. There are some additional things you can specify using $options:

• dropRemote

• string $id

• array $options

• array $ajaxOptions

Used to create a drop target that initiates a XMLHttpRequest when a draggable element is dropped on it. The $options are the same as in drop(), and the $ajaxOptions are the same as in link().

• sortable

• string $id

• array $options

Makes a list or group of floated objects (specified by DOM element ID $id) sortable. The $options array can configure your sorting as follows:

• editor

• string $id

• string $url

• array $options

Creates an in-place ajax editor using the element with the DOM id supplied as the first parameter. When implemented, the element will highlight on mouseOver, and will turn into a single text input field when clicked. The second parameter is the URL that the edited data should be sent to. The action should also return the updated contents of the element. Additional options for the in-place editor can be found on the Script.aculo.us wiki.

/app/views/helpers/link.php¶

<?php
class LinkHelper extends Helper
{
    function makeEdit($title, $url)
    {
        // Logic to create specially formatted link goes here...
    }
}

There are a few functions included in Cake’s helper class you might want to take advantage of:

• output

• string $string

• boolean $return = false

Decides whether to output or return a string based on AUTO_OUTPUT (see /app/config/core.php) and $return’s value. You should use this function to hand any data back to your view.

• loadConfig

Returns your application’s current core configuration and tag definitions.

Let’s use output() to format our link title and URL and hand it back to the view.

/app/views/helpers/link.php (logic added)¶

<?php
class LinkHelper extends Helper
{
    function makeEdit($title, $url)
    {
        // Use the helper's output function to hand formatted
        // data back to the view:

        return $this->output("<div class=\"editOuter\"><a href=\"$url\" class=\"edit\">$title</a></div>");
    }
}

/app/views/helpers/link.php (using other helpers)¶

<?php
class LinkHelper extends Helper
{

    var $helpers = array('Html');

    function makeEdit($title, $url)
    {
        // Use the HTML helper to output
        // formatted data:

        $link = $this->Html->link($title, $url, array('class' => 'edit'));

        return $this->output("<div class=\"editOuter\">$link</div>");
    }
}