PHPonTrax
[ class tree: PHPonTrax ] [ index: PHPonTrax ] [ all elements ]

Source for file helpers.php

Documentation is available at helpers.php

  1. <?php
  2. /**
  3. * File containing the Helpers class and associated functions
  4. *
  5. * (PHP 5)
  6. *
  7. * @package PHPonTrax
  8. * @version $Id$
  9. * @copyright (c) 2005 John Peterson
  10. *
  11. * Permission is hereby granted, free of charge, to any person obtaining
  12. * a copy of this software and associated documentation files (the
  13. * "Software"), to deal in the Software without restriction, including
  14. * without limitation the rights to use, copy, modify, merge, publish,
  15. * distribute, sublicense, and/or sell copies of the Software, and to
  16. * permit persons to whom the Software is furnished to do so, subject to
  17. * the following conditions:
  18. *
  19. * The above copyright notice and this permission notice shall be
  20. * included in all copies or substantial portions of the Software.
  21. *
  22. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  23. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  24. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  25. * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  26. * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  27. * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  28. * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29. */
  30.  
  31. /**
  32. * Basic helper functions
  33. *
  34. * A collection of methods used to generate basic HTML/XML.
  35. */
  36. class Helpers {
  37.  
  38. /**
  39. * @todo Document this variable
  40. * @var boolean
  41. */
  42. public $auto_index;
  43.  
  44. /**
  45. * @todo Document this variable
  46. * Name of a PHP class(?)
  47. * @var string
  48. */
  49. public $object_name;
  50.  
  51. /**
  52. * @todo Document this variable
  53. */
  54. public $attribute_name;
  55.  
  56. /**
  57. * Current controller object
  58. *
  59. * Local copy of $GLOBALS['current_controller_object']<br />
  60. * <b>NB:</b> {@link object()} faults if this does not contain a
  61. * valid instance of ActionController.
  62. * @var ActionController
  63. */
  64. public $controller_object;
  65.  
  66. /**
  67. * Current controller name
  68. *
  69. * Local copy of $GLOBALS['current_controller_name']
  70. * @var string
  71. */
  72. public $controller_name;
  73.  
  74. /**
  75. * Current controller path
  76. *
  77. * Local copy of $GLOBALS['current_controller_path']
  78. * @var string
  79. */
  80. public $controller_path;
  81.  
  82.  
  83. /**
  84. * Construct a Helpers object
  85. *
  86. * @param string Name of ActiveRecord subclass
  87. * @param string Attribute of ActiveRecord subclass
  88. * @uses auto_index
  89. * @uses object_name
  90. * @uses attribute_name
  91. * @uses controller_name
  92. * @uses controller_path
  93. * @uses controller_object
  94. */
  95. function __construct($object_name = null, $attribute_name = null) {
  96. if(substr($object_name, -2) == "[]") {
  97. $auto_index = true;
  98. } else {
  99. $auto_index = false;
  100. }
  101. $this->auto_index = false;
  102. $this->object_name = str_replace("[]", "", $object_name);
  103. $this->attribute_name = $attribute_name;
  104.  
  105. // Copy controller information from $GLOBALS
  106. $this->controller_name =
  107. (array_key_exists('current_controller_name',$GLOBALS)
  108. && $GLOBALS['current_controller_name'])
  109. ? $GLOBALS['current_controller_name'] : null;
  110. $this->controller_path =
  111. (array_key_exists('current_controller_path', $GLOBALS)
  112. && $GLOBALS['current_controller_path'])
  113. ? $GLOBALS['current_controller_path'] : null;
  114. $this->controller_object =
  115. (array_key_exists('current_controller_object', $GLOBALS)
  116. && $GLOBALS['current_controller_object'])
  117. ? $GLOBALS['current_controller_object'] : null;
  118. if($auto_index) {
  119. $object = $this->object();
  120. if(is_object($object)) {
  121. $index = $object->index_on; # should be primary key (usually id field)
  122. $this->auto_index = $object->$index;
  123. }
  124. }
  125. }
  126.  
  127. /**
  128. * Get value of current attribute in the current ActiveRecord object
  129. *
  130. * If there is a value in $_REQUEST[][], return it.
  131. * Otherwise fetch the value from the database.
  132. * @uses attribute_name
  133. * @uses object()
  134. * @uses object_name
  135. * @uses ActiveRecord::send()
  136. */
  137. protected function value() {
  138. if (array_key_exists($this->object_name, $_REQUEST)
  139. && array_key_exists($this->attribute_name,
  140. $_REQUEST[$this->object_name])) {
  141. $value = $_REQUEST[$this->object_name][$this->attribute_name];
  142. } else {
  143.  
  144. // Attribute value not found in $_REQUEST. Find the
  145. // ActiveRecord subclass instance and query it.
  146. $object = $this->object();
  147. if(is_object($object) && $this->attribute_name) {
  148. $value = $object->send($this->attribute_name);
  149. }
  150. }
  151. return $value;
  152. }
  153.  
  154. /**
  155. * Given the name of an ActiveRecord subclass, find an instance
  156. *
  157. * Finds the AR instance from the ActionController instance.
  158. * Assumes that if a $object_name is defined either as the
  159. * argument or an instance variable, then there must be
  160. * a controller object instance which points to a single instance
  161. * of the ActiveRecord.
  162. * <b>FIXME:</b> Handle errors better.
  163. * @param string Name of an ActiveRecord subclass or null
  164. * @return mixed Instance of the subclass, or null if
  165. * object not available.
  166. * @uses controller_object
  167. * @uses object_name
  168. */
  169. protected function object($object_name = null) {
  170. $object_name = $object_name ? $object_name : $this->object_name;
  171. if($object_name
  172. && isset($this->controller_object)
  173. && isset($this->controller_object->$object_name)) {
  174. return $this->controller_object->$object_name;
  175. }
  176. return null;
  177. }
  178. /**
  179. * Convert array of tag attribute names and values to string
  180. *
  181. * @param string[] $options
  182. * @return string
  183. */
  184. protected function tag_options($options) {
  185. if(count($options)) {
  186. $html = array();
  187. foreach($options as $key => $value) {
  188. $html[] = "$key=\"".@htmlspecialchars($value, ENT_COMPAT)."\"";
  189. }
  190. sort($html);
  191. $html = implode(" ", $html);
  192. return $html;
  193. } else {
  194. return '';
  195. }
  196. }
  197.  
  198. /**
  199. * Convert selected attributes to proper XML boolean form
  200. *
  201. * @uses boolean_attribute()
  202. * @param string[] $options
  203. * @return string[] Input argument with selected attributes converted
  204. * to proper XML boolean form
  205. */
  206. protected function convert_options($options = array()) {
  207. foreach(array('disabled', 'readonly', 'multiple') as $a) {
  208. $this->boolean_attribute($options, $a);
  209. }
  210. return $options;
  211. }
  212.  
  213. /**
  214. * Convert an attribute to proper XML boolean form
  215. *
  216. * @param string[] $options
  217. * @param string $attribute
  218. * @return void Contents of $options have been converted
  219. */
  220. protected function boolean_attribute(&$options, $attribute) {
  221. if(array_key_exists($attribute,$options)
  222. && $options[$attribute]) {
  223. $options[$attribute] = $attribute;
  224. } else {
  225. unset($options[$attribute]);
  226. }
  227. }
  228. /**
  229. * Wrap CDATA begin and end tags around argument
  230. *
  231. * Returns a CDATA section for the given content. CDATA sections
  232. * are used to escape blocks of text containing characters which would
  233. * otherwise be recognized as markup. CDATA sections begin with the string
  234. * <samp><![CDATA[</samp> and end with (and may not contain) the string
  235. * <samp>]]></samp>.
  236. * @param string $content Content to wrap
  237. * @return string Wrapped argument
  238. */
  239. function cdata_section($content) {
  240. return "<![CDATA[".$content."]]>";
  241. }
  242.  
  243. /**
  244. * Generate an HTML or XML tag with optional attributes and self-ending
  245. *
  246. * <ul>
  247. * <li>Example: <samp>tag("br");</samp><br>
  248. * Returns: <samp><br />\n</samp></li>
  249. * <li> Example: <samp>tag("div", array("class" => "warning"), true);</samp><br>
  250. * Returns: <samp><div class="warning">\n</samp></li>
  251. * </ul>
  252. * @param string $name Tag name
  253. * @param string[] $options Tag attributes to apply, specified as
  254. * array('attr1' => 'value1'[, 'attr2' => 'value2']...)
  255. * @param boolean $open
  256. * <ul>
  257. * <li>true => make opening tag (end with '>')</li>
  258. * <li>false => make self-terminating tag (end with ' \>')</li>
  259. * </ul>
  260. * @return string The generated tag, followed by "\n"
  261. * @uses tag_options()
  262. */
  263. function tag($name, $options = array(), $open = false) {
  264. $html = "<$name ";
  265. $html .= $this->tag_options($options);
  266. $html .= $open ? ">" : " />";
  267. return $html."\n";
  268. }
  269.  
  270. /**
  271. * Generate an open/close pair of tags with optional attributes and content between
  272. *
  273. * <ul>
  274. * <li>Example: <samp>content_tag("p", "Hello world!");</samp><br />
  275. * Returns: <samp><p>Hello world!</p>\n</samp><li>
  276. * <li>Example:
  277. * <samp>content_tag("div",
  278. * content_tag("p", "Hello world!"),
  279. * array("class" => "strong"));</samp><br />
  280. * Returns:
  281. * <samp><div class="strong"><p>Hello world!</p></div>\n</samp></li>
  282. * </ul>
  283. * @uses tag_options()
  284. * @param string $name Tag to wrap around $content
  285. * @param string $content Text to put between tags
  286. * @param string[] $options Tag attributes to apply, specified as
  287. * array('attr1' => 'value1'[, 'attr2' => 'value2']...)
  288. * @return string Text wrapped with tag and attributes,
  289. * followed by "\n"
  290. */
  291. function content_tag($name, $content, $options = array()) {
  292. $html = "<$name ";
  293. $html .= $this->tag_options($options);
  294. $html .= ">$content</$name>";
  295. return $html."\n";
  296. }
  297. /**
  298. *
  299. * @uses content_tag()
  300. * @uses value()
  301. */
  302. function to_content_tag($tag_name, $options = array()) {
  303. return $this->content_tag($tag_name, $this->value(), $options);
  304. }
  305.  
  306. }
  307.  
  308. /**
  309. * Create a Helpers object and call its content_tag() method
  310. *
  311. * @see Helpers::content_tag()
  312. * @param string $name Tag to wrap around $content
  313. * @param string $content Text to put between tags
  314. * @param string[] $options Tag attributes to apply
  315. * @return string Text wrapped with tag and attributes,
  316. * followed by "\n"
  317. */
  318. function content_tag() {
  319. $helper = new Helpers();
  320. $args = func_get_args();
  321. return call_user_func_array(array($helper, 'content_tag'), $args);
  322. }
  323.  
  324. /**
  325. * Create a Helpers object and call its tag() method
  326. *
  327. * @see Helpers::tag()
  328. * @param string $name Tag name
  329. * @param string[] $options Tag attributes to apply
  330. * @param boolean $open
  331. * <ul>
  332. * <li>true => make opening tag (end with '>')</li>
  333. * <li>false => make self-terminating tag (end with ' \>')</li>
  334. * </ul>
  335. * @return string The tag, followed by "\n"
  336. */
  337. function tag() {
  338. $helper = new Helpers();
  339. $args = func_get_args();
  340. return call_user_func_array(array($helper, 'tag'), $args);
  341. }
  342.  
  343. /**
  344. * Create a Helpers object and call its cdata_section() method
  345. */
  346. function cdata_section() {
  347. $helper = new Helpers();
  348. $args = func_get_args();
  349. return call_user_func_array(array($helper, 'cdata_section'), $args);
  350. }
  351.  
  352. // -- set Emacs parameters --
  353. // Local variables:
  354. // tab-width: 4
  355. // c-basic-offset: 4
  356. // c-hanging-comment-ender-p: nil
  357. // indent-tabs-mode: nil
  358. // End:
  359. ?>

Documentation generated on Thu, 04 May 2006 19:47:44 -0600 by phpDocumentor 1.3.0RC4