Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

License

Content on this site is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Source code for file /joomla/application/component/controller.php

Documentation is available at controller.php

  1. <?php
  2. /**
  3. * @version        $Id: controller.php 9764 2007-12-30 07:48:11Z ircmaxell $
  4. * @package        Joomla.Framework
  5. * @subpackage    Application
  6. * @copyright    Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
  7. * @license        GNU/GPL, see LICENSE.php
  8. *  Joomla! is free software. This version may have been modified pursuant
  9. *  to the GNU General Public License, and as distributed it includes or
  10. *  is derivative of works licensed under the GNU General Public License or
  11. *  other free or open source software licenses.
  12. *  See COPYRIGHT.php for copyright notices and details.
  13. */
  14.  
  15. // Check to ensure this file is within the rest of the framework
  16. defined('JPATH_BASE') or die();
  17.  
  18. /**
  19.  * Base class for a Joomla Controller
  20.  *
  21.  * Controller (controllers are where you put all the actual code) Provides basic
  22.  * functionality, such as rendering views (aka displaying templates).
  23.  *
  24.  * @abstract
  25.  * @package        Joomla.Framework
  26.  * @subpackage    Application
  27.  * @author        Johan Janssens <johan.janssens@joomla.org>
  28.  * @author        Louis Landry <louis.landry@joomla.org>
  29.  * @author         Andrew Eddie
  30.  * @since        1.5
  31.  */
  32. class JController extends JObject
  33. {
  34.     /**
  35.      * The base path of the controller
  36.      *
  37.      * @var        string 
  38.      * @access     protected
  39.      */
  40.     var $_basePath = null;
  41.  
  42.     /**
  43.      * The name of the controller
  44.      *
  45.      * @var        array 
  46.      * @access    protected
  47.      */
  48.     var $_name = null;
  49.  
  50.     /**
  51.      * Array of class methods
  52.      *
  53.      * @var    array 
  54.      * @access    protected
  55.      */
  56.     var $_methods     = null;
  57.  
  58.     /**
  59.      * Array of class methods to call for a given task.
  60.      *
  61.      * @var    array 
  62.      * @access    protected
  63.      */
  64.     var $_taskMap     = null;
  65.  
  66.     /**
  67.      * Current or most recent task to be performed.
  68.      *
  69.      * @var    string 
  70.      * @access    protected
  71.      */
  72.     var $_task         = null;
  73.  
  74.     /**
  75.      * The mapped task that was performed.
  76.      *
  77.      * @var    string 
  78.      * @access    protected
  79.      */
  80.     var $_doTask     = null;
  81.  
  82.     /**
  83.      * The set of search directories for resources (views).
  84.      *
  85.      * @var array 
  86.      * @access    protected
  87.      */
  88.     var $_path = array(
  89.         'view'    => array()
  90.     );
  91.  
  92.     /**
  93.      * URL for redirection.
  94.      *
  95.      * @var    string 
  96.      * @access    protected
  97.      */
  98.     var $_redirect     = null;
  99.  
  100.     /**
  101.      * Redirect message.
  102.      *
  103.      * @var    string 
  104.      * @access    protected
  105.      */
  106.     var $_message     = null;
  107.  
  108.     /**
  109.      * Redirect message type.
  110.      *
  111.      * @var    string 
  112.      * @access    protected
  113.      */
  114.     var $_messageType     = null;
  115.  
  116.     /**
  117.      * ACO Section for the controller.
  118.      *
  119.      * @var    string 
  120.      * @access    protected
  121.      */
  122.     var $_acoSection         = null;
  123.  
  124.     /**
  125.      * Default ACO Section value for the controller.
  126.      *
  127.      * @var    string 
  128.      * @access    protected
  129.      */
  130.     var $_acoSectionValue     = null;
  131.  
  132.     /**
  133.      * Constructor.
  134.      *
  135.      * @access    protected
  136.      * @param    array An optional associative array of configuration settings.
  137.      *  Recognized key values include 'name', 'default_task', 'model_path', and
  138.      *  'view_path' (this list is not meant to be comprehensive).
  139.      * @since    1.5
  140.      */
  141.     function __construct( $config = array() )
  142.     {
  143.         //Initialize private variables
  144.         $this->_redirect    = null;
  145.         $this->_message        = null;
  146.         $this->_messageType = 'message';
  147.         $this->_taskMap        = array();
  148.         $this->_methods        = array();
  149.         $this->_data        = array();
  150.  
  151.         // Get the methods only for the final controller class
  152.         $thisMethods    = get_class_methods( get_class( $this ) );
  153.         $baseMethods    = get_class_methods( 'JController' );
  154.         $methods        = array_diff( $thisMethods, $baseMethods );
  155.  
  156.         // Add default display method
  157.         $methods[] = 'display';
  158.  
  159.         // Iterate through methods and map tasks
  160.         foreach ( $methods as $method )
  161.         {
  162.             if ( substr( $method, 0, 1 ) != '_' ) {
  163.                 $this->_methods[] = strtolower( $method );
  164.                 // auto register public methods as tasks
  165.                 $this->_taskMap[strtolower( $method )] = $method;
  166.             }
  167.         }
  168.  
  169.         //set the view name
  170.         if (empty( $this->_name ))
  171.         {
  172.             if (array_key_exists('name', $config))  {
  173.                 $this->_name = $config['name'];
  174.             } else {
  175.                 $this->_name = $this->getName();
  176.             }
  177.         }
  178.  
  179.         // Set a base path for use by the controller
  180.         if (array_key_exists('base_path', $config)) {
  181.             $this->_basePath    = $config['base_path'];
  182.         } else {
  183.             $this->_basePath    = JPATH_COMPONENT;
  184.         }
  185.  
  186.         // If the default task is set, register it as such
  187.         if ( array_key_exists( 'default_task', $config ) ) {
  188.             $this->registerDefaultTask( $config['default_task'] );
  189.         } else {
  190.             $this->registerDefaultTask( 'display' );
  191.         }
  192.  
  193.         // set the default model search path
  194.         if ( array_key_exists( 'model_path', $config ) ) {
  195.             // user-defined dirs
  196.             $this->addModelPath($config['model_path']);
  197.         } else {
  198.             $this->addModelPath($this->_basePath.DS.'models');
  199.         }
  200.  
  201.         // set the default view search path
  202.         if ( array_key_exists( 'view_path', $config ) ) {
  203.             // user-defined dirs
  204.             $this->_setPath( 'view', $config['view_path'] );
  205.         } else {
  206.             $this->_setPath( 'view', $this->_basePath.DS.'views' );
  207.         }
  208.     }
  209.  
  210.     /**
  211.      * Execute a task by triggering a method in the derived class.
  212.      *
  213.      * @access    public
  214.      * @param    string The task to perform. If no matching task is found, the
  215.      *  '__default' task is executed, if defined.
  216.      * @return    mixed|falseThe value returned by the called method, false in
  217.      *  error case.
  218.      * @since    1.5
  219.      */
  220.     function execute( $task )
  221.     {
  222.         $this->_task = $task;
  223.  
  224.         $task = strtolower( $task );
  225.         if (isset( $this->_taskMap[$task] )) {
  226.             $doTask = $this->_taskMap[$task];
  227.         } elseif (isset( $this->_taskMap['__default'] )) {
  228.             $doTask = $this->_taskMap['__default'];
  229.         } else {
  230.             return JError::raiseError( 404, JText::_('Task ['.$task.'] not found') );
  231.         }
  232.  
  233.         // Record the actual task being fired
  234.         $this->_doTask = $doTask;
  235.  
  236.         // Make sure we have access
  237.         if ($this->authorize( $doTask ))
  238.         {
  239.             $retval = $this->$doTask();
  240.             return $retval;
  241.         }
  242.         else
  243.         {
  244.             return JError::raiseError( 403, JText::_('Access Forbidden') );
  245.         }
  246.  
  247.     }
  248.  
  249.     /**
  250.      * Authorization check
  251.      *
  252.      * @access    public
  253.      * @param    string    $task    The ACO Section Value to check access on
  254.      * @return    boolean    True if authorized
  255.      * @since    1.5
  256.      */
  257.     function authorize( $task )
  258.     {
  259.         // Only do access check if the aco section is set
  260.         if ($this->_acoSection)
  261.         {
  262.             // If we have a section value set that trumps the passed task ???
  263.             if ($this->_acoSectionValue) {
  264.                 // We have one, so set it and lets do the check
  265.                 $task = $this->_acoSectionValue;
  266.             }
  267.             // Get the JUser object for the current user and return the authorization boolean
  268.             $user = & JFactory::getUser();
  269.             return $user->authorize( $this->_acoSection, $task );
  270.         }
  271.         else
  272.         {
  273.             // Nothing set, nothing to check... so obviously its ok :)
  274.             return true;
  275.         }
  276.     }
  277.  
  278.     /**
  279.      * Typical view method for MVC based architecture
  280.      *
  281.      * This function is provide as a default implementation, in most cases
  282.      * you will need to override it in your own controllers.
  283.      *
  284.      * @access    public
  285.      * @param    string    $cachable    If true, the view output will be cached
  286.      * @since    1.5
  287.      */
  288.     function display($cachable=false)
  289.     {
  290.         $document =& JFactory::getDocument();
  291.  
  292.         $viewType    = $document->getType();
  293.         $viewName    = JRequest::getCmd( 'view', $this->getName() );
  294.         $viewLayout    = JRequest::getCmd( 'layout', 'default' );
  295.  
  296.         $view = & $this->getView( $viewName, $viewType, '', array( 'base_path'=>$this->_basePath));
  297.  
  298.         // Get/Create the model
  299.         if ($model = & $this->getModel($viewName)) {
  300.             // Push the model into the view (as default)
  301.             $view->setModel($model, true);
  302.         }
  303.  
  304.         // Set the layout
  305.         $view->setLayout($viewLayout);
  306.  
  307.         // Display the view
  308.         if ($cachable) {
  309.             global $option;
  310.             $cache =& JFactory::getCache($option, 'view');
  311.             $cache->get($view, 'display');
  312.         } else {
  313.             $view->display();
  314.         }
  315.     }
  316.  
  317.     /**
  318.      * Redirects the browser or returns false if no redirect is set.
  319.      *
  320.      * @access    public
  321.      * @return    boolean    False if no redirect exists.
  322.      * @since    1.5
  323.      */
  324.     function redirect()
  325.     {
  326.         if ($this->_redirect) {
  327.             global $mainframe;
  328.             $mainframe->redirect( $this->_redirect, $this->_message, $this->_messageType );
  329.         }
  330.         return false;
  331.     }
  332.  
  333.     /**
  334.      * Method to get a model object, loading it if required.
  335.      *
  336.      * @access    public
  337.      * @param    string    The model name. Optional.
  338.      * @param    string    The class prefix. Optional.
  339.      * @param    array    Configuration array for model. Optional.
  340.      * @return    object    The model.
  341.      * @since    1.5
  342.      */
  343.     function &getModel( $name = '', $prefix = '', $config = array() )
  344.     {
  345.         if ( empty( $name ) ) {
  346.             $name = $this->getName();
  347.         }
  348.  
  349.         if ( empty( $prefix ) ) {
  350.             $prefix = $this->getName() . 'Model';
  351.         }
  352.  
  353.         if ( $model = & $this->_createModel( $name, $prefix, $config ) )
  354.         {
  355.             // task is a reserved state
  356.             $model->setState( 'task', $this->_task );
  357.  
  358.             // Lets get the application object and set menu information if its available
  359.             $app    = &JFactory::getApplication();
  360.             $menu    = &$app->getMenu();
  361.             if (is_object( $menu ))
  362.             {
  363.                 if ($item = $menu->getActive())
  364.                 {
  365.                     $params    =& $menu->getParams($item->id);
  366.                     // Set Default State Data
  367.                     $model->setState( 'parameters.menu', $params );
  368.                 }
  369.             }
  370.         }
  371.         return $model;
  372.     }
  373.  
  374.     /**
  375.      * Adds to the stack of model paths in LIFO order.
  376.      *
  377.      * @static
  378.      * @param    string|arrayThe directory (string), or list of directories
  379.      *                        (array) to add.
  380.      * @return    void 
  381.      */
  382.     function addModelPath( $path )
  383.     {
  384.         jimport('joomla.application.component.model');
  385.         JModel::addIncludePath($path);
  386.     }
  387.  
  388.     /**
  389.      * Gets the available tasks in the controller.
  390.      * @access    public
  391.      * @return    array Array[i] of task names.
  392.      * @since    1.5
  393.      */
  394.     function getTasks()
  395.     {
  396.         return $this->_methods;
  397.     }
  398.  
  399.     /**
  400.      * Get the last task that is or was to be performed.
  401.      *
  402.      * @access    public
  403.      * @return     string The task that was or is being performed.
  404.      * @since    1.5
  405.      */
  406.     function getTask()
  407.     {
  408.         return $this->_task;
  409.     }
  410.  
  411.     /**
  412.      * Method to get the controller name
  413.      *
  414.      * The dispatcher name by default parsed using the classname, or it can be set
  415.      * by passing a $config['name'] in the class constructor
  416.      *
  417.      * @access    public
  418.      * @return    string The name of the dispatcher
  419.      * @since    1.5
  420.      */
  421.     function getName()
  422.     {
  423.         $name = $this->_name;
  424.  
  425.         if (empty( $name ))
  426.         {
  427.             $r = null;
  428.             if ( !preg_match( '/(.*)Controller/i', get_class( $this ), $r ) ) {
  429.                 JError::raiseError(500, "JController::getName() : Cannot get or parse class name.");
  430.             }
  431.             $name = strtolower( $r[1] );
  432.         }
  433.  
  434.         return $name;
  435.     }
  436.  
  437.     /**
  438.      * Method to get a reference to the current view and load it if necessary.
  439.      *
  440.      * @access    public
  441.      * @param    string    The view name. Optional, defaults to the controller
  442.      *  name.
  443.      * @param    string    The view type. Optional.
  444.      * @param    string    The class prefix. Optional.
  445.      * @param    array    Configuration array for view. Optional.
  446.      * @return    object    Reference to the view or an error.
  447.      * @since    1.5
  448.      */
  449.     function &getView( $name = '', $type = '', $prefix = '', $config = array() )
  450.     {
  451.         static $views;
  452.  
  453.         if ( !isset( $views ) ) {
  454.             $views = array();
  455.         }
  456.  
  457.         if ( empty( $name ) ) {
  458.             $name = $this->getName();
  459.         }
  460.  
  461.         if ( empty( $prefix ) ) {
  462.             $prefix = $this->getName() . 'View';
  463.         }
  464.  
  465.         if ( empty( $views[$name] ) )
  466.         {
  467.             if ( $view = & $this->_createView( $name, $prefix, $type, $config ) ) {
  468.                 $views[$name] = & $view;
  469.             } else {
  470.                 $result = JError::raiseError(
  471.                     500, JText::_( 'View not found [name, type, prefix]:' )
  472.                         . ' ' . $name . ',' . $type . ',' . $prefix
  473.                 );
  474.                 return $result;
  475.             }
  476.         }
  477.  
  478.         return $views[$name];
  479.     }
  480.  
  481.     /**
  482.      * Add one or more view paths to the controller's stack, in LIFO order.
  483.      *
  484.      * @static
  485.      * @param    string|arrayThe directory (string), or list of directories
  486.      *  (a