MidCOM component request class

1. Request switches
1. Handler
2. Fixed arguments
3. Variable arguments
2. Method _can_handle_<handler name>
3. Method _handler_<handler name>
4. Method _show_<handler name>

The core function of handler files is to handle url requests passed to the component.

MidCOM component handles URL requests in the following order

1. check if a request switch has been defined for the request
   • placed in method _on_initialize
2. checks against url hijacking
   • method _can_handle_<handler name>
   • required only in some cases
3. check the validity of request switch
   • method _handler_<handler name>
   • called before any output has been sent for the user during the $_MIDCOM->codeinit() phase
4. prints out the style elements
   • method _show_<handler name>
   • called when website root style calls for $_MIDCOM->content() (usually in <(content)>)

Request switches

Request switch is an array, which defines all the accepted URL requests. Request switches are defined in method _on_initialize of the component viewer class.

$this->_request_switch['latest'] = array (
    'handler'       => array ('net_nehmer_blog_handler_index', 'latest'),
    'fixed_args'    => array ('latest'),
    'variable_args' => 1,
);

Handler

Array key handler describes which handler class file is included and which method will be used. In this case file handler/index.php will be loaded.

The second part of the array, handler method, will define the method chain which will be used. In the example above method the chain would be

1. _can_handle_latest
2. _handler_latest
3. _show_latest

Fixed arguments

Fixed arguments define URL path used for choosing which handler will be used.

Variable arguments

Variable arguments are used to pass variable information (eg. filename or GUID) for the component.

Method _can_handle_<handler name>

Method _can_handle_<handler name> is used to prevent the component from hijacking the URL space. MidCOM checks with this method if the component is supposed to

If a request switch has only variable arguments defined and without any fixed arguments, this step is required to prevent hijacking. If this method doesn't exist in the case defined, MidCOM is unable to detect if the URL requested is a variable argument or a call to a subfolder. This means that the component will receive all requests pointed to its subfolders.

function _can_handle_view($handler_id, $args, &$data)
{
    $qb = midcom_db_article::new_query_builder();
    $qb->add_constraint( 'topic', '=', $this->_topic->id );
    $qb->add_constraint( 'name', '=', $args[0] );

    // No article with name $argv0can be found
    if ($qb->count() === 0)
    {
        return false;
    }

    return true;
}

Method _handler_<handler name>

In method _handler_<handler name> MidCOM checks whether the requested URL is valid and does all required data processing like saving forms.

This is where it is possible to send HTTP header based error messages and to load content information used to display in _show_<handler name>.

User can also be directed to another URL at this phase using the $_MIDCOM->relocate() method.

function _handler_view($handler_id, $args, &$data)
{
    $qb = midcom_db_article::new_query_builder();
    $qb->add_constraint( 'topic', '=', $this->_topic->id );
    $qb->add_constraint( 'name', '=', $args[0] );

    // No article with name $argv[0] can be found
    if ($qb->count() === 0)
    {
        $_MIDCOM->generate_error(MIDCOM_ERRNOTFOUND, "The article {$args0 could not be found!");
        // This will exit
    }

    // Article was found, populate it to request data to be used in show phase
    $articles = $qb->execute();
    $this->_request_data['article'] = $articles[0];

    // Everything OK, allow MidCOM to proceed to show phase.
    return true;
}

In the example above MidCOM checks if it can find an article requested. If article cannot be found, method generate_error gives an error message to user and exits gracefully.

If the article can be found, MidCOM is informed that it is allowed to continue.

Method _show_<handler name>

Method _show_<handler name> is used to send output for Midgard to display when the root style of the webpage calls for <(content)>.

 function _show_latest($handler_id, &$data)
 {
     // Show  the header style element
     midcom_show_style('show-latest-header');

     // If no articles were found in _handler_latest, 
     if (count($this->_articles) === 0)
     {
         midcom_show_style('show-latest-noresults');
     }
     else
     {
         // Loop through the articles
         foreach ($this->_articles as $article)
         {
             // Get the schema based information of the requested
             // article and pass the information for the style
             // element
             $this->_request_data['article'] = $this->_load($article);
             midcom_show_style('show-latest-item');
         }
     }

     // Show the footer element
     midcom_show_style('show-latest-footer');
 }

In this example in _handler_latest MidgardQueryBuilder has been used to get a list of the articles. Depending on the amount of hits MidCOM is requested to display either - with no results to display - a message indicating no results (show-latest-noresults) or each item separately with style element show-latest-item.