Source for file form.php

Documentation is available at form.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Site
  4.  * @subpackage  com_config
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. /**
  13.  * Prototype form model.
  14.  *
  15.  * @package     Joomla.Site
  16.  * @subpackage  com_config
  17.  * @see         JForm
  18.  * @see         JFormField
  19.  * @see         JFormRule
  20.  * @since       3.2
  21.  */
  22. abstract class ConfigModelForm extends ConfigModelCms
  23. {
  24.     /**
  25.      * Array of form objects.
  26.      *
  27.      * @var    array 
  28.      * @since  3.2
  29.      */
  30.     protected $forms = array();
  31.  
  32.     /**
  33.      * Method to checkin a row.
  34.      *
  35.      * @param   integer  $pk  The numeric id of the primary key.
  36.      *
  37.      * @return  boolean  False on failure or error, true otherwise.
  38.      *
  39.      * @since   3.2
  40.      * @throws  RuntimeException
  41.      */
  42.     public function checkin($pk = null)
  43.     {
  44.         // Only attempt to check the row in if it exists.
  45.         if ($pk)
  46.         {
  47.             $user = JFactory::getUser();
  48.  
  49.             // Get an instance of the row to checkin.
  50.             $table = $this->getTable();
  51.  
  52.             if (!$table->load($pk))
  53.             {
  54.                 throw new RuntimeException($table->getError());
  55.             }
  56.  
  57.             // Check if this is the user has previously checked out the row.
  58.             if ($table->checked_out > 0 && $table->checked_out != $user->get('id') && !$user->authorise('core.admin', 'com_checkin'))
  59.             {
  60.                 throw new RuntimeException($table->getError());
  61.             }
  62.  
  63.             // Attempt to check the row in.
  64.             if (!$table->checkin($pk))
  65.             {
  66.                 throw new RuntimeException($table->getError());
  67.             }
  68.         }
  69.  
  70.         return true;
  71.     }
  72.  
  73.     /**
  74.      * Method to check-out a row for editing.
  75.      *
  76.      * @param   integer  $pk  The numeric id of the primary key.
  77.      *
  78.      * @return  boolean  False on failure or error, true otherwise.
  79.      *
  80.      * @since   3.2
  81.      */
  82.     public function checkout($pk = null)
  83.     {
  84.         // Only attempt to check the row in if it exists.
  85.         if ($pk)
  86.         {
  87.             $user = JFactory::getUser();
  88.  
  89.             // Get an instance of the row to checkout.
  90.             $table = $this->getTable();
  91.  
  92.             if (!$table->load($pk))
  93.             {
  94.                 throw new RuntimeException($table->getError());
  95.             }
  96.  
  97.             // Check if this is the user having previously checked out the row.
  98.             if ($table->checked_out > 0 && $table->checked_out != $user->get('id'))
  99.             {
  100.                 throw new RuntimeException(JText::_('JLIB_APPLICATION_ERROR_CHECKOUT_USER_MISMATCH'));
  101.             }
  102.  
  103.             // Attempt to check the row out.
  104.             if (!$table->checkout($user->get('id'), $pk))
  105.             {
  106.                 throw new RuntimeException($table->getError());
  107.             }
  108.         }
  109.  
  110.         return true;
  111.     }
  112.  
  113.     /**
  114.      * Abstract method for getting the form from the model.
  115.      *
  116.      * @param   array    $data      Data for the form.
  117.      * @param   boolean  $loadData  True if the form is to load its own data (default case), false if not.
  118.      *
  119.      * @return  mixed  A JForm object on success, false on failure
  120.      *
  121.      * @since   3.2
  122.      */
  123.     abstract public function getForm($data = array(), $loadData = true);
  124.  
  125.     /**
  126.      * Method to get a form object.
  127.      *
  128.      * @param   string   $name     The name of the form.
  129.      * @param   string   $source   The form source. Can be XML string if file flag is set to false.
  130.      * @param   array    $options  Optional array of options for the form creation.
  131.      * @param   boolean  $clear    Optional argument to force load a new form.
  132.      * @param   string   $xpath    An optional xpath to search for the fields.
  133.      *
  134.      * @return  mixed  JForm object on success, False on error.
  135.      *
  136.      * @see     JForm
  137.      * @since   3.2
  138.      */
  139.     protected function loadForm($name, $source = null, $options = array(), $clear = false, $xpath = false)
  140.     {
  141.         // Handle the optional arguments.
  142.         $options['control'] = JArrayHelper::getValue($options, 'control', false);
  143.  
  144.         // Create a signature hash.
  145.         $hash = sha1($source . serialize($options));
  146.  
  147.         // Check if we can use a previously loaded form.
  148.         if (isset($this->_forms[$hash]) && !$clear)
  149.         {
  150.             return $this->_forms[$hash];
  151.         }
  152.  
  153.         // Get the form.
  154.         // Register the paths for the form -- failing here
  155.         $paths = new SplPriorityQueue;
  156.         $paths->insert(JPATH_COMPONENT . '/model/form', 'normal');
  157.         $paths->insert(JPATH_COMPONENT . '/model/field', 'normal');
  158.         $paths->insert(JPATH_COMPONENT . '/model/rule', 'normal');
  159.  
  160.         //Legacy support to be removed in 4.0.  -- failing here
  161.         $paths->insert(JPATH_COMPONENT . '/models/forms', 'normal');
  162.         $paths->insert(JPATH_COMPONENT . '/models/fields', 'normal');
  163.         $paths->insert(JPATH_COMPONENT . '/models/rules', 'normal');
  164.  
  165.         // Solution until JForm supports splqueue
  166.         JForm::addFormPath(JPATH_COMPONENT . '/models/forms');
  167.         JForm::addFieldPath(JPATH_COMPONENT . '/models/fields');
  168.         JForm::addFormPath(JPATH_COMPONENT . '/model/form');
  169.         JForm::addFieldPath(JPATH_COMPONENT . '/model/field');
  170.  
  171.         try
  172.         {
  173.             $form = JForm::getInstance($name, $source, $options, false, $xpath);
  174.  
  175.             if (isset($options['load_data']) && $options['load_data'])
  176.             {
  177.                 // Get the data for the form.
  178.                 $data = $this->loadFormData();
  179.             }
  180.             else
  181.             {
  182.                 $data = array();
  183.             }
  184.  
  185.             // Allow for additional modification of the form, and events to be triggered.
  186.             // We pass the data because plugins may require it.
  187.             $this->preprocessForm($form, $data);
  188.  
  189.             // Load the data into the form after the plugins have operated.
  190.             $form->bind($data);
  191.  
  192.         }
  193.         catch (Exception $e)
  194.         {
  195.             JFactory::getApplication()->enqueueMessage($e->getMessage());
  196.  
  197.             return false;
  198.         }
  199.  
  200.         // Store the form for later.
  201.         $this->_forms[$hash] = $form;
  202.  
  203.         return $form;
  204.     }
  205.  
  206.     /**
  207.      * Method to get the data that should be injected in the form.
  208.      *
  209.      * @return  array    The default data is an empty array.
  210.      *
  211.      * @since   3.2
  212.      */
  213.     protected function loadFormData()
  214.     {
  215.         return array();
  216.     }
  217.  
  218.     /**
  219.      * Method to allow derived classes to preprocess the data.
  220.      *
  221.      * @param   string  $context  The context identifier.
  222.      * @param   mixed   &$data    The data to be processed. It gets altered directly.
  223.      *
  224.      * @return  void 
  225.      *
  226.      * @since   3.2
  227.      */
  228.     protected function preprocessData($context, &$data)
  229.     {
  230.         // Get the dispatcher and load the users plugins.
  231.         $dispatcher = JEventDispatcher::getInstance();
  232.         JPluginHelper::importPlugin('content');
  233.  
  234.         // Trigger the data preparation event.
  235.         $results = $dispatcher->trigger('onContentPrepareData', array($context, $data));
  236.  
  237.         // Check for errors encountered while preparing the data.
  238.         if (count($results) > 0 && in_array(false, $results, true))
  239.         {
  240.             JFactory::getApplication()->enqueueMessage($dispatcher->getError(), 'error');
  241.         }
  242.     }
  243.  
  244.     /**
  245.      * Method to allow derived classes to preprocess the form.
  246.      *
  247.      * @param   JForm   $form   A JForm object.
  248.      * @param   mixed   $data   The data expected for the form.
  249.      * @param   string  $group  The name of the plugin group to import (defaults to "content").
  250.      *
  251.      * @return  void 
  252.      *
  253.      * @see     JFormField
  254.      * @since   3.2
  255.      * @throws  Exception if there is an error in the form event.
  256.      */
  257.     protected function preprocessForm(JForm $form, $data, $group = 'content')
  258.     {
  259.         // Import the appropriate plugin group.
  260.         JPluginHelper::importPlugin($group);
  261.  
  262.         // Get the dispatcher.
  263.         $dispatcher = JEventDispatcher::getInstance();
  264.  
  265.         // Trigger the form preparation event.
  266.         $results = $dispatcher->trigger('onContentPrepareForm', array($form, $data));
  267.  
  268.         // Check for errors encountered while preparing the form.
  269.         if (count($results) && in_array(false, $results, true))
  270.         {
  271.             // Get the last error.
  272.             $error = $dispatcher->getError();
  273.  
  274.             if (!($error instanceof Exception))
  275.             {
  276.                 throw new Exception($error);
  277.             }
  278.         }
  279.     }
  280.  
  281.     /**
  282.      * Method to validate the form data.
  283.      *
  284.      * @param   JForm   $form   The form to validate against.
  285.      * @param   array   $data   The data to validate.
  286.      * @param   string  $group  The name of the field group to validate.
  287.      *
  288.      * @return  mixed  Array of filtered data if valid, false otherwise.
  289.      *
  290.      * @see     JFormRule
  291.      * @see     JFilterInput
  292.      * @since   3.2
  293.      */
  294.     public function validate($form, $data, $group = null)
  295.     {
  296.         // Filter and validate the form data.
  297.         $data   = $form->filter($data);
  298.         $return = $form->validate($data, $group);
  299.  
  300.         // Check for an error.
  301.         if ($return instanceof Exception)
  302.         {
  303.             JFactory::getApplication()->enqueueMessage($return->getMessage(), 'error');
  304.  
  305.             return false;
  306.         }
  307.  
  308.         // Check the validation results.
  309.         if ($return === false)
  310.         {
  311.             // Get the validation messages from the form.
  312.             foreach ($form->getErrors() as $message)
  313.             {
  314.                 JFactory::getApplication()->enqueueMessage($message, 'error');
  315.             }
  316.  
  317.             return false;
  318.         }
  319.  
  320.         return $data;
  321.     }
  322. }

Documentation generated on Tue, 19 Nov 2013 15:03:39 +0100 by phpDocumentor 1.4.3