Selected_Records_Actions

Creating a Custom Selected Records Action

If you view the list tab in any of your Xataface applications, you'll notice that there is a checkbox next to each row of the list, and there are a number of actions listed at the bottom of the list that you can perform on the selected records. Xataface comes pre-built with only a few of these actions:

1. Delete selected
2. Update selected
3. Copy selected

However it is quite easy to add your own actions here that are performed on selected records. This article describes exactly how to do this.

What is a Selected Record action?

A Selected Record action is no different than any other action in Xataface, except that it is meant to act on the records that have been selected in the list tab.

Example Action: Approve Records

Consider a news site where news stories are automatically imported into the database en masse, but each news story has a field approved to indicate whether the store has been approved to appear on the site yet. The usage pattern of this application involves a lot of looking through lists of news stories and approving them. Therefore it would be convenient if the user could just select the rows that he wants to approve and click a button to approve them all.

Out of the box Xataface would allow the user to select the records, click update selected records, then update them all via the update selected records form. But avoiding this extra step will improve usability greatly.

Step 1: Design the Action

First we need to specifically decide how our action will work. In this case, the flow goes as follows:

1. User selects the news items they want to approve.
2. User clicks the Approve Selected button. (to be created)
3. Our action approves the selected records.
4. User is automatically redirected back to the list tab with a message stating how many records were successfully approved, and whether there were any errors.

Step 2: Gather Our Tools

Before we actually create the action, let's look at a few tools that we'll be using from the Xataface framework to make this happen.

1. In the actions.ini file, the selected_result_actions? category is reserved for actions that act on selected records of the list tab. E.g.

   [delete_selected]
       ...
       category=selected_result_actions
       ...

2. The df_get_selected_records() function returns an array of Dataface_Record objects that represent the rows that were selected to initiate the action. E.g.

   $app =& Dataface_Application::getInstance();
   $query =& $app->getQuery();
   $records = df_get_selected_records($query);
   foreach ($records as $record){
       ...
   }

3. The Dataface_Record::checkPermission() method allows us to see if the current user has access to a specific permission on the given record. We'll use this method to ensure that the user has permission to approve the news record. E.g.

   if ( !$record->checkPermission('edit', array('field'=>'approved')) ){
       return PEAR::raiseError("You don't have permission to edit the approved field for this record.");
   }

4. The Xataface will pass the redirect URL where your action should send the user upon completion of the action as the --redirect attribute of the POST variables. This value is base64_encoded so you'll need to decode it before redirecting. E.g.:

   if ( @$_POST['--redirect'] ) 
       $url = base64_decode($_POST['--redirect']);
   $url .= '&--msg='.urlencode($updated.' records were deleted.');
   header('Location: '.$url);
   exit;

Step 3: Create the Action

We will call our action approve_news so we'll place it in the actions/approve_news.php file of our application:

<?php
class actions_approve_news {
    function handle(&$params){
        // First get the selected records
        $app =& Dataface_Application::getInstance();
        $query =& $app->getQuery();
        $records =& df_get_selected_records($query);

        $updated = 0;  // Count the number of records we update
        $errs = array();   // Log the errors we encounter

        foreach ($records as $rec){
            if ( !$rec->checkPermission('edit'), array('field'=>'approved')) ){
                $errs[] = Dataface_Error::permissionDenied(
                    "You do not have permission to approve '".
                    $rec->getTitle().
                    "' because you do not have the 'edit' permission.");
                continue;
            }
            $rec->setValue('approved', 1);
 
            $res = $rec->save(true /*secure*/);
            if ( PEAR::isError($res) ) $errs[] = $res->getMessage();
            else $updated++;
            
        }
        
        if ( $errs ){
            // Errors occurred.  Let's let the user know.
            // The $_SESSION['--msg'] content will be displayed to the user as a message
            // in the next page request.
            $_SESSION['--msg'] = 'Errors Occurred:<br/> '.implode('<br/> ', $errs);
        } else {
            $_SESSION['--msg'] = "No errors occurred";
        }
        

        $url = $app->url('-action=list');   // A default URL in case no redirect was supplied
        if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']);
        $url .= '&--msg='.urlencode($updated.' records were deleted.');

        // Redirect back to the previous page
        header('Location: '.$url);
        exit;
    }
}

Step 4: Add the action to your actions.ini file

The actions.ini file allows us to specify how and where this action is used, and by whom. We can specify permissions that are required to perform the action, conditions that are required to display the action, confirmation messages that are to be displayed to the user when they are about to perform the action, and more. Our actions.ini file entry looks like:

[approve_news]
    label="Approve"
    description="Approve selected records"
    permission = edit
    category=selected_result_actions
    confirm="Are you sure you want to approve the selected records?"
    icon="${dataface_site_url}/images/approve.gif"
    condition="$query['-table'] == 'news'"
    url="{$this->url('-action=approve_news')}"

This should be fairly straight forward. The only special items here are the category and confirm directives. The condition directive tells Xataface that this action should only be shown for the news table.

The confirm directive defines a confirmation message that should be displayed to the user when they attempt to approve records.

The icon directive allows you to specify the path to an icon to display for the action. In our case we have an icon located in the images directory of our application.

Step 5: Trying it out

Now when we go to the list tab of the news table there is an Approve button along the bottom where it says "With Selected". You we can click on this button to approve any of the selected rows.