Source for file helper.php

Documentation is available at helper.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Form
  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. jimport('joomla.filesystem.path');
  13.  
  14. /**
  15.  * JForm's helper class.
  16.  * Provides a storage for filesystem's paths where JForm's entities reside and methods for creating those entities.
  17.  * Also stores objects with entities' prototypes for further reusing.
  18.  *
  19.  * @package     Joomla.Platform
  20.  * @subpackage  Form
  21.  * @since       11.1
  22.  */
  23. class JFormHelper
  24. {
  25.     /**
  26.      * Array with paths where entities(field, rule, form) can be found.
  27.      *
  28.      * Array's structure:
  29.      * <code>
  30.      * paths:
  31.      * {ENTITY_NAME}:
  32.      * - /path/1
  33.      * - /path/2
  34.      * </code>
  35.      *
  36.      * @var    array 
  37.      * @since  11.1
  38.      *
  39.      */
  40.     protected static $paths;
  41.  
  42.     /**
  43.      * Static array of JForm's entity objects for re-use.
  44.      * Prototypes for all fields and rules are here.
  45.      *
  46.      * Array's structure:
  47.      * <code>
  48.      * entities:
  49.      * {ENTITY_NAME}:
  50.      * {KEY}: {OBJECT}
  51.      * </code>
  52.      *
  53.      * @var    array 
  54.      * @since  11.1
  55.      */
  56.     protected static $entities = array();
  57.  
  58.     /**
  59.      * Method to load a form field object given a type.
  60.      *
  61.      * @param   string   $type  The field type.
  62.      * @param   boolean  $new   Flag to toggle whether we should get a new instance of the object.
  63.      *
  64.      * @return  mixed  JFormField object on success, false otherwise.
  65.      *
  66.      * @since   11.1
  67.      */
  68.     public static function loadFieldType($type, $new = true)
  69.     {
  70.         return self::loadType('field', $type, $new);
  71.     }
  72.  
  73.     /**
  74.      * Method to load a form rule object given a type.
  75.      *
  76.      * @param   string   $type  The rule type.
  77.      * @param   boolean  $new   Flag to toggle whether we should get a new instance of the object.
  78.      *
  79.      * @return  mixed  JFormRule object on success, false otherwise.
  80.      *
  81.      * @since   11.1
  82.      */
  83.     public static function loadRuleType($type, $new = true)
  84.     {
  85.         return self::loadType('rule', $type, $new);
  86.     }
  87.  
  88.     /**
  89.      * Method to load a form entity object given a type.
  90.      * Each type is loaded only once and then used as a prototype for other objects of same type.
  91.      * Please, use this method only with those entities which support types (forms don't support them).
  92.      *
  93.      * @param   string   $entity  The entity.
  94.      * @param   string   $type    The entity type.
  95.      * @param   boolean  $new     Flag to toggle whether we should get a new instance of the object.
  96.      *
  97.      * @return  mixed  Entity object on success, false otherwise.
  98.      *
  99.      * @since   11.1
  100.      */
  101.     protected static function loadType($entity, $type, $new = true)
  102.     {
  103.         // Reference to an array with current entity's type instances
  104.         $types = &self::$entities[$entity];
  105.  
  106.         $key = md5($type);
  107.  
  108.         // Return an entity object if it already exists and we don't need a new one.
  109.         if (isset($types[$key]) && $new === false)
  110.         {
  111.             return $types[$key];
  112.         }
  113.  
  114.         $class = self::loadClass($entity, $type);
  115.         if ($class !== false)
  116.         {
  117.             // Instantiate a new type object.
  118.             $types[$key] = new $class;
  119.             return $types[$key];
  120.         }
  121.         else
  122.         {
  123.             return false;
  124.         }
  125.     }
  126.  
  127.     /**
  128.      * Attempt to import the JFormField class file if it isn't already imported.
  129.      * You can use this method outside of JForm for loading a field for inheritance or composition.
  130.      *
  131.      * @param   string  $type  Type of a field whose class should be loaded.
  132.      *
  133.      * @return  mixed  Class name on success or false otherwise.
  134.      *
  135.      * @since   11.1
  136.      */
  137.     public static function loadFieldClass($type)
  138.     {
  139.         return self::loadClass('field', $type);
  140.     }
  141.  
  142.     /**
  143.      * Attempt to import the JFormRule class file if it isn't already imported.
  144.      * You can use this method outside of JForm for loading a rule for inheritance or composition.
  145.      *
  146.      * @param   string  $type  Type of a rule whose class should be loaded.
  147.      *
  148.      * @return  mixed  Class name on success or false otherwise.
  149.      *
  150.      * @since   11.1
  151.      */
  152.     public static function loadRuleClass($type)
  153.     {
  154.         return self::loadClass('rule', $type);
  155.     }
  156.  
  157.     /**
  158.      * Load a class for one of the form's entities of a particular type.
  159.      * Currently, it makes sense to use this method for the "field" and "rule" entities
  160.      * (but you can support more entities in your subclass).
  161.      *
  162.      * @param   string  $entity  One of the form entities (field or rule).
  163.      * @param   string  $type    Type of an entity.
  164.      *
  165.      * @return  mixed  Class name on success or false otherwise.
  166.      *
  167.      * @since   11.1
  168.      */
  169.     protected static function loadClass($entity, $type)
  170.     {
  171.         if (strpos($type, '.'))
  172.         {
  173.             list($prefix, $type) = explode('.', $type);
  174.         }
  175.         else
  176.         {
  177.             $prefix = 'J';
  178.         }
  179.  
  180.         $class = JString::ucfirst($prefix, '_') . 'Form' . JString::ucfirst($entity, '_') . JString::ucfirst($type, '_');
  181.  
  182.         if (class_exists($class))
  183.         {
  184.             return $class;
  185.         }
  186.  
  187.         // Get the field search path array.
  188.         $paths = self::addPath($entity);
  189.  
  190.         // If the type is complex, add the base type to the paths.
  191.         if ($pos = strpos($type, '_'))
  192.         {
  193.  
  194.             // Add the complex type prefix to the paths.
  195.             for ($i = 0, $n = count($paths); $i < $n; $i++)
  196.             {
  197.                 // Derive the new path.
  198.                 $path = $paths[$i] . '/' . strtolower(substr($type, 0, $pos));
  199.  
  200.                 // If the path does not exist, add it.
  201.                 if (!in_array($path, $paths))
  202.                 {
  203.                     $paths[] = $path;
  204.                 }
  205.             }
  206.             // Break off the end of the complex type.
  207.             $type = substr($type, $pos + 1);
  208.         }
  209.  
  210.         // Try to find the class file.
  211.         $type = strtolower($type) . '.php';
  212.         foreach ($paths as $path)
  213.         {
  214.             if ($file = JPath::find($path, $type))
  215.             {
  216.                 require_once $file;
  217.                 if (class_exists($class))
  218.                 {
  219.                     break;
  220.                 }
  221.             }
  222.         }
  223.  
  224.         // Check for all if the class exists.
  225.         return class_exists($class) ? $class : false;
  226.     }
  227.  
  228.     /**
  229.      * Method to add a path to the list of field include paths.
  230.      *
  231.      * @param   mixed  $new  A path or array of paths to add.
  232.      *
  233.      * @return  array  The list of paths that have been added.
  234.      *
  235.      * @since   11.1
  236.      */
  237.     public static function addFieldPath($new = null)
  238.     {
  239.         return self::addPath('field', $new);
  240.     }
  241.  
  242.     /**
  243.      * Method to add a path to the list of form include paths.
  244.      *
  245.      * @param   mixed  $new  A path or array of paths to add.
  246.      *
  247.      * @return  array  The list of paths that have been added.
  248.      *
  249.      * @since   11.1
  250.      */
  251.     public static function addFormPath($new = null)
  252.     {
  253.         return self::addPath('form', $new);
  254.     }
  255.  
  256.     /**
  257.      * Method to add a path to the list of rule include paths.
  258.      *
  259.      * @param   mixed  $new  A path or array of paths to add.
  260.      *
  261.      * @return  array  The list of paths that have been added.
  262.      *
  263.      * @since   11.1
  264.      */
  265.     public static function addRulePath($new = null)
  266.     {
  267.         return self::addPath('rule', $new);
  268.     }
  269.  
  270.     /**
  271.      * Method to add a path to the list of include paths for one of the form's entities.
  272.      * Currently supported entities: field, rule and form. You are free to support your own in a subclass.
  273.      *
  274.      * @param   string  $entity  Form's entity name for which paths will be added.
  275.      * @param   mixed   $new     A path or array of paths to add.
  276.      *
  277.      * @return  array  The list of paths that have been added.
  278.      *
  279.      * @since   11.1
  280.      */
  281.     protected static function addPath($entity, $new = null)
  282.     {
  283.         // Reference to an array with paths for current entity
  284.         $paths = &self::$paths[$entity];
  285.  
  286.         // Add the default entity's search path if not set.
  287.         if (empty($paths))
  288.         {
  289.             // While we support limited number of entities (form, field and rule)
  290.             // we can do this simple pluralisation:
  291.             $entity_plural = $entity . 's';
  292.  
  293.             /*
  294.              * But when someday we would want to support more entities, then we should consider adding
  295.              * an inflector class to "libraries/joomla/utilities" and use it here (or somebody can use a real inflector in his subclass).
  296.              * See also: pluralization snippet by Paul Osman in JControllerForm's constructor.
  297.              */
  298.             $paths[] = __DIR__ . '/' . $entity_plural;
  299.         }
  300.  
  301.         // Force the new path(s) to an array.
  302.         settype($new, 'array');
  303.  
  304.         // Add the new paths to the stack if not already there.
  305.         foreach ($new as $path)
  306.         {
  307.             if (!in_array($path, $paths))
  308.             {
  309.                 array_unshift($paths, trim($path));
  310.             }
  311.         }
  312.  
  313.         return $paths;
  314.     }
  315. }

Documentation generated on Tue, 19 Nov 2013 15:04:29 +0100 by phpDocumentor 1.4.3