Source for file form.php

Documentation is available at form.php

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

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