PageRenderTime 49ms CodeModel.GetById 16ms RepoModel.GetById 1ms app.codeStats 0ms

/CC_Window.php

https://github.com/coverall/N2O
PHP | 1555 lines | 540 code | 321 blank | 694 comment | 79 complexity | 7ec440fbac75a72ea0a7385004f88c6a MD5 | raw file
  1. <?php
  2. // $Id: CC_Window.php,v 1.125 2009/09/10 02:10:20 patrick Exp $
  3. //=======================================================================
  4. // CLASS: CC_Window
  5. //=======================================================================
  6. /**
  7. * This class defines an application's window object.
  8. *
  9. * @package N2O
  10. * @access public
  11. * @author The Crew <N2O@coverallcrew.com>
  12. * @copyright Copyright &copy; 2003, Coverall Crew
  13. */
  14. class CC_Window
  15. {
  16. /**
  17. * The id (filename) of the window taken from the action.
  18. *
  19. * @var string $id
  20. * @access private
  21. * @see CC_Application::getAction()
  22. */
  23. var $id;
  24. /**
  25. * An array of CC_Button objects registered with the window.
  26. *
  27. * @var array $buttons
  28. * @access private
  29. * @see registerComponent()
  30. * @see getButton()
  31. * @see getButtonById()
  32. * @see buttonExists()
  33. */
  34. var $buttons = array();
  35. /**
  36. * An array of CC_Fields objects registered with the window.
  37. *
  38. * @var array $fields
  39. * @access private
  40. * @see registerComponent()
  41. * @see getField()
  42. */
  43. var $fields = array();
  44. /**
  45. * An array of CC_Record objects registered with the window.
  46. *
  47. * @var array $records
  48. * @access private
  49. * @see registerComponent()
  50. * @see getRecord()
  51. */
  52. var $records = array();
  53. /**
  54. * An array of CC_Summary objects registered with the window.
  55. *
  56. * @var array $summaries
  57. * @access private
  58. * @see registerComponent()
  59. * @see getSummary()
  60. */
  61. var $summaries = array();
  62. /**
  63. * An array of miscellaneous CC_Component objects registered with the window.
  64. *
  65. * @var array $components
  66. * @access private
  67. * @see registerComponent()
  68. * @see getComponent()
  69. */
  70. var $components = array();
  71. /**
  72. * Whether or not the window has invalid fields.
  73. *
  74. * @var bool $_error
  75. * @access private
  76. * @deprecated
  77. */
  78. var $_error = false;
  79. /**
  80. * The window's error message.
  81. *
  82. * @var string $_errorMessage
  83. * @access private
  84. * @see getErrorMessage()
  85. */
  86. var $_errorMessage;
  87. /**
  88. * The window's status message.
  89. *
  90. * @var string $_statusMessage
  91. * @access private
  92. * @see getStatusMessage()
  93. */
  94. var $_statusMessage;
  95. /**
  96. * Whether or not the window should display verbose 'field' errors.
  97. *
  98. * @var bool $_verboseErrors
  99. * @access private
  100. * @see setVerboseErrors()
  101. */
  102. var $_verboseErrors = false; // give details about each field's error
  103. /**
  104. * Whether or not a window's components are updateable (usually true unless a cancel event occurs).
  105. *
  106. * @var bool $updateable
  107. * @access private
  108. * @see setUpdateable()
  109. * @see isUpdateable()
  110. */
  111. var $updateable = true;
  112. /**
  113. * This is the default button which will be used if a user hits enter in a field.
  114. *
  115. * @var CC_Button $defaultButton
  116. * @access private
  117. * @see setDefaultButton()
  118. */
  119. var $defaultButton;
  120. /**
  121. * An array of objects stored for access in this window.
  122. *
  123. * @var array $objects
  124. * @access private
  125. * @see registerObject()
  126. * @see getObject()
  127. * @see objectExists()
  128. */
  129. var $objects = array();
  130. /**
  131. * An array of name-value pairs to keep data between subsequent window accesses.
  132. *
  133. * @var array $arguments
  134. * @access private
  135. * @see getArgument()
  136. * @see setArgument()
  137. */
  138. var $arguments = array();
  139. /**
  140. * This flag tells CC_Application to unregister the window when it is left for another window.
  141. *
  142. * @var boolean $_unregisterOnLeave
  143. * @access private
  144. */
  145. var $_unregisterOnLeave = false;
  146. //-------------------------------------------------------------------
  147. // CONSTRUCTOR: CC_Window
  148. //-------------------------------------------------------------------
  149. /**
  150. * The CC_Window constructor creates the window's id based on the application's current action.
  151. *
  152. * @access public
  153. * @see CC_Application::getAction()
  154. * @author The Crew <N2O@coverallcrew.com>
  155. * @copyright Copyright &copy; 2003, Coverall Crew
  156. * @todo Why do we unset the application object here?
  157. */
  158. function CC_Window($id = null)
  159. {
  160. global $application;
  161. if ($id == null)
  162. {
  163. $this->id = $application->getAction();
  164. }
  165. else
  166. {
  167. $this->id = $id;
  168. }
  169. unset($application);
  170. }
  171. //-------------------------------------------------------------------
  172. // METHOD: registerButton()
  173. //-------------------------------------------------------------------
  174. /**
  175. * This method registers a button with the window. Each button on a window must be registered for its handlers to be processsed by N2O.
  176. *
  177. * @access public
  178. * @param CC_Button The button object to register.
  179. */
  180. function registerButton(&$aButton)
  181. {
  182. //echo "Registering Button with id " . $aButton->id . "...<br>";
  183. $aButton->windowId = $this->id;
  184. $this->buttons[] = &$aButton;
  185. return sizeof($this->buttons) - 1;
  186. }
  187. //-------------------------------------------------------------------
  188. // METHOD: updateFieldsFromPage
  189. //-------------------------------------------------------------------
  190. /**
  191. * This method is called by CC_Index when a button click triggers fields to be updated and/or validated. It updates and/or validates the fields based on the user's input in the window. updateFieldsFromDatabase updates fields from database values.
  192. *
  193. * @access private
  194. * @param bool $validateFields Whether or not fields should be validated as well as updated.
  195. * @param array $fieldArray The fields to be updated. If empty, all the window's fields (all standalone fields as well as all records' fields) are updated from the page data entered.
  196. * @see CC_Index
  197. * @see updateFieldsFromDatabase()
  198. */
  199. function updateFieldsFromPage($validateFields, $fieldArray = null)
  200. {
  201. $fieldArraySize = ($fieldArray == null ? 0 : sizeof($fieldArray));
  202. $size = sizeof($this->fields);
  203. $keys = array_keys($this->fields);
  204. $deferred = array();
  205. // search through all stray fields first
  206. for ($i = 0; $i < $size; $i++)
  207. {
  208. if (!$this->fields[$keys[$i]]->isReadOnly())
  209. {
  210. $this->fields[$keys[$i]]->clearAllErrors();
  211. if (($this->fields[$keys[$i]] instanceof CC_Multiple_Choice_Field) && sizeof($this->fields[$keys[$i]]->_associatedFields))
  212. {
  213. $deferred[] = $keys[$i];
  214. }
  215. else if (($this->fields[$keys[$i]] instanceof CC_Checkbox_Field) && sizeof($this->fields[$keys[$i]]->_associatedFields))
  216. {
  217. $deferred[] = $keys[$i];
  218. }
  219. else
  220. {
  221. $this->updateFieldFromPage($this->fields[$keys[$i]], $validateFields && (($fieldArraySize == 0) || array_key_exists($this->fields[$keys[$i]]->getRequestArrayName(), $fieldArray)));
  222. }
  223. }
  224. }
  225. $size = sizeof($deferred);
  226. for ($i = $size -1; $i >= 0; $i--)
  227. {
  228. $this->updateFieldFromPage($this->fields[$deferred[$i]], $validateFields && (($fieldArraySize == 0) || array_key_exists($this->fields[$deferred[$i]]->getRequestArrayName(), $fieldArray)));
  229. }
  230. unset($size, $keys, $fieldArraySize, $deferred);
  231. }
  232. //-------------------------------------------------------------------
  233. // METHOD: updateFieldsFromDatabase
  234. //-------------------------------------------------------------------
  235. /**
  236. * This method is called by CC_Index when a button click triggers fields to be updated and/or validated. It updates and/or validates the fields based on the field's value in the database. updateFieldsFromPage updates fields from page values.
  237. *
  238. * @access private
  239. * @param array $fieldArray The fields to be updated. If empty, all the window's fields (all standalone fields as well as all records' fields) are updated from the database.
  240. * @see CC_Index
  241. * @see updateFieldsFromPage()
  242. */
  243. function updateFieldsFromDatabase($fieldArray = null)
  244. {
  245. $fieldArraySize = ($fieldArray == null ? 0 : sizeof($fieldArray));
  246. $keys = array_keys($this->records);
  247. $size = sizeof($keys);
  248. for ($i = 0; $i < $size; $i++)
  249. {
  250. $fieldKeys = array_keys($this->records[$keys[$i]]->fields);
  251. $rSize = sizeof($fieldKeys);
  252. for ($j = 0; $j < $rSize; $j++)
  253. {
  254. if (isset($this->records[$keys[$i]]->fields[$fieldKeys[$j]]))
  255. {
  256. if ((($fieldArraySize == 0) || array_key_exists($this->records[$keys[$i]]->fields[$fieldKeys[$j]]->name, $fieldArray)) && $this->records[$keys[$i]]->fields[$fieldKeys[$j]]->getUpdateFromDatabase() === true)
  257. {
  258. $this->updateFieldFromDatabase($this->records[$keys[$i]]->fields[$fieldKeys[$j]], $this->records[$keys[$i]]);
  259. }
  260. }
  261. }
  262. unset($rSize);
  263. unset($fieldKeys);
  264. unset($record);
  265. }
  266. unset($size, $fieldArraySize);
  267. }
  268. //-------------------------------------------------------------------
  269. // METHOD: updateFieldFromDatabase
  270. //-------------------------------------------------------------------
  271. /**
  272. * This method is called by updateFieldsFromDatabase() to update an individual field from the database.
  273. *
  274. * @access private
  275. * @param CC_Field $field The field to update.
  276. * @param CC_Record $record The record to update.
  277. * @see updateFieldsFromDatabase()
  278. */
  279. function updateFieldFromDatabase(&$field, &$record)
  280. {
  281. global $application;
  282. $query = 'select ' . $field->name . ' from ' . $record->table . ' where ID = \'' . $record->id . '\'';
  283. $results = $application->db->doSelect($query);
  284. if (!PEAR::isError($results))
  285. {
  286. if ($row = cc_fetch_array($results))
  287. {
  288. $field->setValue($row[$field->name]);
  289. }
  290. $results->free();
  291. }
  292. unset($results, $query);
  293. }
  294. //-------------------------------------------------------------------
  295. // METHOD: updateFieldFromPage
  296. //-------------------------------------------------------------------
  297. /**
  298. * This method is called by updateFieldsFromPage() to update an individual field from the page.
  299. *
  300. * @access private
  301. * @param CC_Field $field The field to update.
  302. * @param bool $validateFields Whether or not fields should be validated as well as updated.
  303. * @see updateFieldsFromDatabase()
  304. */
  305. function updateFieldFromPage(&$field, $validateFields)
  306. {
  307. global $application;
  308. $field->handleUpdateFromRequest();
  309. //trigger_error("$key : $fieldType : " . $field->getValue(), E_USER_WARNING);
  310. $hasValue = $field->hasValue();
  311. if ($field->required && !$hasValue && $validateFields)
  312. {
  313. // the field is required but the user didn't enter any data
  314. $field->setErrorMessage($field->label . ' is required.', CC_FIELD_ERROR_MISSING);
  315. $application->errorManager->addFieldError('000000', $field->getErrorMessage(CC_FIELD_ERROR_MISSING), $this->_verboseErrors);
  316. }
  317. else if (($field->required || ($field->validateIfNotRequired && $hasValue)) && $validateFields && !$field->validate())
  318. {
  319. // the field is invalid, check if there is already an invalid message set
  320. if ($field->getErrorMessage(CC_FIELD_ERROR_INVALID) == '')
  321. {
  322. $field->setErrorMessage($field->label . ' is invalid.', CC_FIELD_ERROR_INVALID);
  323. }
  324. $application->errorManager->addFieldError('000001', $field->getErrorMessage(CC_FIELD_ERROR_INVALID), $this->_verboseErrors);
  325. }
  326. else
  327. {
  328. $field->clearAllErrors();
  329. }
  330. unset($hasValue);
  331. }
  332. //-------------------------------------------------------------------
  333. // METHOD: registerComponent()
  334. //-------------------------------------------------------------------
  335. /**
  336. * This method registers a component with the window. This method should be called to register any type of component as the method will determine what type of component it is and call the appropriate method for the specific type.
  337. *
  338. * @access public
  339. * @param CC_Component $aComponent The object to register.
  340. */
  341. function registerComponent(&$aComponent)
  342. {
  343. if ($aComponent == NULL)
  344. {
  345. trigger_error('CC_Window->registerComponent(): received an undefined component. (' . $this->id . ')');
  346. }
  347. else if ($aComponent instanceof CC_Component)
  348. {
  349. $aComponent->register($this);
  350. }
  351. else
  352. {
  353. trigger_error('CC_Window->registerComponent(): did not expect the following type: ' . get_class($aComponent) . '. Make sure it extends CC_Component. (' . $this->id . ')');
  354. }
  355. }
  356. //-------------------------------------------------------------------
  357. // METHOD: registerField()
  358. //-------------------------------------------------------------------
  359. /**
  360. * This method registers a field object with the window. Each field on a window must be registered for it to be properly updated and/or validated. This private method is called by the public registerComponent().
  361. *
  362. * @access private
  363. * @param CC_Field $aField The field object to register.
  364. * @see registerComponent
  365. */
  366. function registerField(&$field)
  367. {
  368. if (!$field)
  369. {
  370. trigger_error('Attempt to register a null field bypassed...', E_USER_WARNING);
  371. trigger_error(getStackTrace(), E_USER_WARNING);
  372. return;
  373. }
  374. else if (!strlen($field->getName()))
  375. {
  376. trigger_error('Attempt to register an unnamed field bypassed...', E_USER_WARNING);
  377. trigger_error(getStackTrace(), E_USER_WARNING);
  378. return;
  379. }
  380. $this->fields[$field->getRequestArrayName()] = &$field;
  381. }
  382. //-------------------------------------------------------------------
  383. // METHOD: registerRecord()
  384. //-------------------------------------------------------------------
  385. /**
  386. * This method registers a record object with the window. Each record on a window must be registered for its fields to be properly updated and/or validated. This private method is called by the public registerComponent().
  387. *
  388. * @access private
  389. * @param CC_Record $aRecord The record object to register.
  390. * @see registerComponent
  391. */
  392. function registerRecord(&$record)
  393. {
  394. $this->records[] = &$record;
  395. }
  396. //-------------------------------------------------------------------
  397. // METHOD: registerSummary()
  398. //-------------------------------------------------------------------
  399. /**
  400. * This method registers a summary object with the window. Each summary on a window must be registered for its fields to be properly updated and/or validated. This private method is called by the public registerComponent().
  401. *
  402. * @access private
  403. * @param CC_Summary $summary The summary object to register.
  404. * @see registerComponent
  405. */
  406. function registerSummary(&$summary)
  407. {
  408. $this->summaries[$summary->getName()] = &$summary;
  409. }
  410. //-------------------------------------------------------------------
  411. // METHOD: registerOtherComponent()
  412. //-------------------------------------------------------------------
  413. /**
  414. * This method registers an object with the window that is not a field, record, summary or button. This private method is called by the public registerComponent().
  415. *
  416. * @access private
  417. * @param CC_Component $component The component object to register.
  418. * @see registerComponent
  419. */
  420. function registerCustomComponent(&$component)
  421. {
  422. $this->components[$component->getName()] = &$component;
  423. }
  424. //-------------------------------------------------------------------
  425. // METHOD: registerObject
  426. //-------------------------------------------------------------------
  427. /**
  428. * This method stores objects in the window for access.
  429. *
  430. * @access public
  431. * @param string $key The name by which to indentify the object for later access.
  432. * @param mixed $aObject The object to register.
  433. * @see getObject()
  434. */
  435. function registerObject($key, &$aObject)
  436. {
  437. $this->objects[$key] = &$aObject;
  438. }
  439. //-------------------------------------------------------------------
  440. // METHOD: getComponent()
  441. //-------------------------------------------------------------------
  442. /**
  443. * This method retrieves a component from the window's components array.
  444. *
  445. * @access public
  446. * @param string $name The name of the component to retrieve.
  447. * @return mixed The CC_Component object of the given name.
  448. * @see registerComponent()
  449. */
  450. function &getComponent($name)
  451. {
  452. if (isset($this->components[$name]))
  453. {
  454. $this->components[$name]->get($this);
  455. return $this->components[$name];
  456. }
  457. else
  458. {
  459. trigger_error("The CC_Component named '$name' was not found in the window $this->id. Perhaps you forgot to register it?");
  460. }
  461. }
  462. //-------------------------------------------------------------------
  463. // METHOD: getSummary()
  464. //-------------------------------------------------------------------
  465. /**
  466. * This method retrieves a CC_Summary object from the window's summaries array.
  467. *
  468. * @access public
  469. * @param string $name The name of the CC_Summary to retrieve.
  470. * @param bool $update Whether or not we should update the summary upon retrival.
  471. * @return CC_Summary The CC_Summary object of the given name.
  472. */
  473. function &getSummary($name, $update = false)
  474. {
  475. if (isset($this->summaries[$name]))
  476. {
  477. if ($update)
  478. {
  479. $this->summaries[$name]->update();
  480. }
  481. return $this->summaries[$name];
  482. }
  483. else
  484. {
  485. trigger_error("The CC_Summary named '$name' was not found in the window $this->id. Perhaps you forgot to register it?");
  486. }
  487. }
  488. //-------------------------------------------------------------------
  489. // METHOD: getRecord()
  490. //-------------------------------------------------------------------
  491. /**
  492. * This method retrieves a CC_Record object from the window's records array.
  493. *
  494. * @access public
  495. * @param string $key The key of the CC_Record to retrieve.
  496. * @param bool $updateForeignKeys Whether or not we should update the record's foreign keys upon retrieval.
  497. * @return CC_Record The CC_Record object with the given key.
  498. */
  499. function &getRecord($key = NULL, $updateForeignKeys = false, $recordIndex = 0)
  500. {
  501. if ($key == NULL)
  502. {
  503. $record = &$this->records[$recordIndex];
  504. if ($updateForeignKeys)
  505. {
  506. $record->updateForeignKeys();
  507. }
  508. return $record;
  509. }
  510. else if (strlen($key) > 0)
  511. {
  512. trigger_error('getRecord(): Getting the record via a "key" is no longer supported. Use getRecordAtIndex() instead. (key: ' . $key . ')');
  513. $record = &$this->records[$recordIndex];
  514. if ($updateForeignKeys)
  515. {
  516. $record->updateForeignKeys();
  517. }
  518. return $record;
  519. }
  520. else
  521. {
  522. trigger_error("The CC_Record with the key '$key' was not found in the window $this->id. Perhaps you forgot to register it, or maybe you didn't unregister a window when you should have?");
  523. }
  524. }
  525. //-------------------------------------------------------------------
  526. // METHOD: getRecordAtIndex()
  527. //-------------------------------------------------------------------
  528. /**
  529. * This method retrieves a CC_Record object from the window's records array from a particular index.
  530. *
  531. * @access public
  532. * @param int $recordIndex The index of the CC_Record to retrieve.
  533. * @param bool $updateForeignKeys Whether or not we should update the record's foreign keys upon retrieval.
  534. * @return CC_Record The CC_Record object with the given index.
  535. */
  536. function &getRecordAtIndex($recordIndex = 0, $updateForeignKeys = false)
  537. {
  538. $size = sizeof($this->records);
  539. if ($size <= $recordIndex)
  540. {
  541. trigger_error('The CC_Record index is out of bounds. (index: ' . $recordIndex . ', # of records: ' . $size . ')');
  542. }
  543. else
  544. {
  545. return $this->getRecord(NULL, $updateForeignKeys, $recordIndex);
  546. }
  547. }
  548. //-------------------------------------------------------------------
  549. // METHOD: isRecordRegisteredAtIndex()
  550. //-------------------------------------------------------------------
  551. /**
  552. * This method checks to see if a CC_Record object of a given index is registered with the window.
  553. *
  554. * @access public
  555. * @param int $index The index of the CC_Record to check.
  556. * @return bool Whether or not the CC_Record of given key is registered with the window.
  557. */
  558. function isRecordRegisteredAtIndex($index)
  559. {
  560. return isset($this->records[$index]);
  561. }
  562. //-------------------------------------------------------------------
  563. // METHOD: isRecordRegistered()
  564. //-------------------------------------------------------------------
  565. /**
  566. * This method checks to see if a CC_Record object of a given key is registered with the window.
  567. *
  568. * @access public
  569. * @param string $key The key of the CC_Record to check.
  570. * @deprecated
  571. * @return bool Whether or not the CC_Record of given key is registered with the window.
  572. */
  573. function isRecordRegistered($key)
  574. {
  575. return isset($this->records[$key]);
  576. }
  577. //-------------------------------------------------------------------
  578. // METHOD: isComponentRegistered()
  579. //-------------------------------------------------------------------
  580. /**
  581. * This method checks to see if a CC_Component object of a given key is registered with the window.
  582. *
  583. * @access public
  584. * @param string $key The key of the CC_Component to check.
  585. * @deprecated
  586. * @return bool Whether or not the CC_Component of given key is registered with the window.
  587. */
  588. function isComponentRegistered($key)
  589. {
  590. return isset($this->components[$key]);
  591. }
  592. //-------------------------------------------------------------------
  593. // METHOD: isFieldRegistered()
  594. //-------------------------------------------------------------------
  595. /**
  596. * This method checks to see if a CC_Field object of a given name is registered with the window.
  597. *
  598. * @access public
  599. * @param string $fieldName The name of the CC_Field to check.
  600. * @return bool Whether or not the CC_Field of given name is registered with the window.
  601. * @see registerComponent()
  602. */
  603. function isFieldRegistered($fieldName)
  604. {
  605. return isset($this->fields[$fieldName]);
  606. }
  607. //-------------------------------------------------------------------
  608. // METHOD: isSummaryRegistered()
  609. //-------------------------------------------------------------------
  610. /**
  611. * This method checks to see if a CC_Summary object of a given name is registered with the window.
  612. *
  613. * @access public
  614. * @param string $name The name of the CC_Summary to check.
  615. * @return bool Whether or not the CC_Summary of given name is registered with the window.
  616. * @see registerComponent()
  617. */
  618. function isSummaryRegistered($name)
  619. {
  620. return isset($this->summaries[$name]);
  621. }
  622. //-------------------------------------------------------------------
  623. // METHOD: isUpdateable()
  624. //-------------------------------------------------------------------
  625. /**
  626. * This method checks to see if the window is updateable (ie. components thereon). Usually true unless we have are are processing a cancel button.
  627. *
  628. * @access public
  629. * @return bool Whether or not the window is updateable.
  630. * @see setUpdateable()
  631. * @todo Who uses this?
  632. */
  633. function isUpdateable()
  634. {
  635. return $this->updateable;
  636. }
  637. //-------------------------------------------------------------------
  638. // METHOD: setUpdateable()
  639. //-------------------------------------------------------------------
  640. /**
  641. * This method sets whether or not the window is updateable (ie. components thereon). Usually set to true unless we have are are processing a cancel button.
  642. *
  643. * @access public
  644. * @param bool $updateable Whether or not the window is updateable.
  645. * @see isUpdateable()
  646. * @todo Who uses this?
  647. */
  648. function setUpdateable($updateable)
  649. {
  650. $this->updateable = $updateable;
  651. }
  652. //-------------------------------------------------------------------
  653. // METHOD: getButton()
  654. //-------------------------------------------------------------------
  655. /**
  656. * This method retrieves a CC_Button object from the window's buttons array.
  657. *
  658. * @access public
  659. * @param string $aLabel The label of the CC_Button to retrieve.
  660. * @return CC_Button The CC_Button object of the given label.
  661. * @see registerComponent()
  662. */
  663. function &getButton($aLabel)
  664. {
  665. $size = sizeof($this->buttons);
  666. for ($i = 0; $i < $size; $i++)
  667. {
  668. // (!) for some reason, ($button->label == $aLabel) was
  669. // returning true for comparisons that weren't the same!!
  670. // we should investigate why this is one day...
  671. if (strcmp($this->buttons[$i]->label, $aLabel) == 0)
  672. {
  673. unset($size);
  674. return $this->buttons[$i];
  675. }
  676. }
  677. unset($size);
  678. //trigger_error("The Button with the following label was not found: " . $aLabel);
  679. }
  680. //-------------------------------------------------------------------
  681. // METHOD: getButtonAtIndex()
  682. //-------------------------------------------------------------------
  683. /**
  684. * This method retrieves a CC_Button object from the window's buttons array.
  685. *
  686. * @access public
  687. * @param string $index The label of the CC_Button to retrieve.
  688. * @return CC_Button The CC_Button object of the given label.
  689. * @see registerComponent()
  690. */
  691. function &getButtonAtIndex($index)
  692. {
  693. if (isset($this->buttons[$index]))
  694. {
  695. return $this->buttons[$index];
  696. }
  697. else
  698. {
  699. trigger_error('No button at index ' . $index . ' found.', E_USER_WARNING);
  700. return false;
  701. }
  702. }
  703. //-------------------------------------------------------------------
  704. // METHOD: buttonExists()
  705. //-------------------------------------------------------------------
  706. /**
  707. * This method checks to see if a CC_Button object of a given label is registered with the window.
  708. *
  709. * @access public
  710. * @param string $aLabel The name of the CC_Button to check.
  711. * @return bool Whether or not the CC_Button of given label is registered with the window.
  712. * @see registerComponent()
  713. */
  714. function buttonExists($aLabel)
  715. {
  716. $size = sizeof($this->buttons);
  717. for ($i = 0; $i < $size; $i++)
  718. {
  719. if ($this->buttons[$i]->label == $aLabel)
  720. {
  721. unset($size);
  722. return true;
  723. }
  724. }
  725. unset($size);
  726. return false;
  727. }
  728. //-------------------------------------------------------------------
  729. // METHOD: getButtonById()
  730. //-------------------------------------------------------------------
  731. /**
  732. * This method retrieves a CC_Button object from the window's buttons array.
  733. *
  734. * @access public
  735. * @param string $aButtonId The id of the CC_Button to retrieve.
  736. * @return CC_Button The CC_Button object of the given id.
  737. * @see registerComponent()
  738. */
  739. function &getButtonById($aButtonId)
  740. {
  741. $size = sizeof($this->buttons);
  742. for ($i = 0; $i < $size; $i++)
  743. {
  744. $button = &$this->buttons[$i];
  745. if ($button->id == $aButtonId)
  746. {
  747. unset($size);
  748. return $button;
  749. }
  750. unset($button);
  751. }
  752. unset($size);
  753. trigger_error('[' . $this->id . '] The Button with the following id was not found: ' . $aButtonId);
  754. return false;
  755. }
  756. //-------------------------------------------------------------------
  757. // METHOD: getField()
  758. //-------------------------------------------------------------------
  759. /**
  760. * This method retrieves a CC_Field object from the window's fields array.
  761. *
  762. * @access public
  763. * @param string $fieldName The name of the CC_Field to retrieve.
  764. * @return CC_Field The CC_Field object of the given name.
  765. * @see registerComponent()
  766. */
  767. function &getField($fieldName)
  768. {
  769. if (isset($this->fields[$fieldName]))
  770. {
  771. $this->fields[$fieldName]->get($this);
  772. return $this->fields[$fieldName];
  773. }
  774. else
  775. {
  776. trigger_error("The CC_Field named '$fieldName' was not found in the window $this->id. Perhaps you forgot to register it?");
  777. }
  778. }
  779. //-------------------------------------------------------------------
  780. // METHOD: getObject()
  781. //-------------------------------------------------------------------
  782. /**
  783. * This method retrieves an object from the window's objects array.
  784. *
  785. * @access public
  786. * @param string $key The key of the object to retrieve.
  787. * @return mixed The object of the given key.
  788. * @see registerObject()
  789. */
  790. function &getObject($key)
  791. {
  792. return $this->objects[$key];
  793. }
  794. //-------------------------------------------------------------------
  795. // METHOD: objectExists()
  796. //-------------------------------------------------------------------
  797. /**
  798. * This method checks to see if an object of a given key is registered with the window.
  799. *
  800. * @access public
  801. * @param string $key The key of the object to check.
  802. * @return bool Whether or not the object of given key is registered with the window.
  803. * @see registerObject()
  804. * @deprecated
  805. */
  806. function objectExists($key)
  807. {
  808. trigger_error('objectExists() is deprecated. Use hasObject() instead.', E_USER_WARNING);
  809. return hasObject($key);
  810. }
  811. //-------------------------------------------------------------------
  812. // METHOD: hasObject()
  813. //-------------------------------------------------------------------
  814. /**
  815. * This method checks to see if an object of a given key is registered with the window.
  816. *
  817. * @access public
  818. * @param string $key The key of the object to check.
  819. * @return bool Whether or not the object of given key is registered with the window.
  820. * @see registerObject()
  821. */
  822. function hasObject($key)
  823. {
  824. return isset($this->objects[$key]);
  825. }
  826. //-------------------------------------------------------------------
  827. // METHOD: hasSummary()
  828. //-------------------------------------------------------------------
  829. /**
  830. * This method checks to see if a CC_Summary of a given name is registered with the window.
  831. *
  832. * @access public
  833. * @param string $name The name of the CC_Summary to check.
  834. * @return bool Whether or not the CC_Summary of given name is registered with the window.
  835. * @see registerSummary()
  836. */
  837. function hasSummary($name)
  838. {
  839. return isset($this->summaries[$name]);
  840. }
  841. //-------------------------------------------------------------------
  842. // METHOD: _setError
  843. //-------------------------------------------------------------------
  844. /**
  845. * sets the _error boolean indicating that the window contains an error.
  846. *
  847. * @access public
  848. * @param bool $error Whether or not the window has an error.
  849. * @deprecated
  850. */
  851. function _setError($error)
  852. {
  853. $this->_error = $error;
  854. }
  855. //-------------------------------------------------------------------
  856. // METHOD: setVerboseErrors
  857. //-------------------------------------------------------------------
  858. /**
  859. * Indicates whether or not the 'field' errors should be displayed verbosely.
  860. *
  861. * @access public
  862. * @param bool $verboseErrors
  863. */
  864. function setVerboseErrors($verboseErrors)
  865. {
  866. $this->_verboseErrors = $verboseErrors;
  867. }
  868. //-------------------------------------------------------------------
  869. // METHOD: addError
  870. //-------------------------------------------------------------------
  871. /**
  872. * Sets an error in the window.
  873. *
  874. * @access public
  875. * @deprecated
  876. * @todo Anyone using this method any more?
  877. */
  878. function addError()
  879. {
  880. $this->_setError(true);
  881. }
  882. //-------------------------------------------------------------------
  883. // METHOD: clearError
  884. //-------------------------------------------------------------------
  885. /**
  886. * @access public
  887. * @deprecated See clearErrorMessage().
  888. * Clears the error and the error message.
  889. * @see clearErrorMessage()
  890. */
  891. function clearError()
  892. {
  893. $this->clearErrorMessage();
  894. }
  895. //-------------------------------------------------------------------
  896. // METHOD: clearErrorMessage
  897. //-------------------------------------------------------------------
  898. /**
  899. * Clears the window's error message.
  900. *
  901. * @access public
  902. */
  903. function clearErrorMessage()
  904. {
  905. $this->_errorMessage = '';
  906. }
  907. //-------------------------------------------------------------------
  908. // METHOD: hasError
  909. //-------------------------------------------------------------------
  910. /**
  911. * Returns whether or not the window contains errors. A window is defined as having errors if there are either field or user errors associated with it.
  912. *
  913. * @access public
  914. * @return bool Whether or not the window has errors.
  915. */
  916. function hasError()
  917. {
  918. global $application;
  919. return ($application->errorManager->hasFieldErrors() || $application->errorManager->hasUserErrors());
  920. }
  921. //-------------------------------------------------------------------
  922. // METHOD: setStatusMessage
  923. //-------------------------------------------------------------------
  924. /**
  925. * This method sets a status message for the window.
  926. *
  927. * @access public
  928. * @see getStatusMessage().
  929. */
  930. function setStatusMessage($statusMessage)
  931. {
  932. $this->_statusMessage = $statusMessage;
  933. }
  934. //-------------------------------------------------------------------
  935. // METHOD: getStatusMessage
  936. //-------------------------------------------------------------------
  937. /**
  938. * This method sets a status message for the window.
  939. *
  940. * @access public
  941. * @param bool $clearAfterDisplay If true, the status message will be cleared after it is returned.
  942. * @see getStatusMessage().
  943. */
  944. function getStatusMessage($clearAfterDisplay = false)
  945. {
  946. if (strlen($this->_statusMessage))
  947. {
  948. $status = '<span class="ccStatus">' . $this->_statusMessage . '</span>';
  949. if ($clearAfterDisplay)
  950. {
  951. $this->clearStatusMessage();
  952. }
  953. return $status;
  954. }
  955. else
  956. {
  957. return;
  958. }
  959. }
  960. //-------------------------------------------------------------------
  961. // METHOD: clearStatusMessage
  962. //-------------------------------------------------------------------
  963. /**
  964. * This method clears the status message.
  965. *
  966. * @access public
  967. * @see getStatusMessage().
  968. * @see setStatusMessage().
  969. */
  970. function clearStatusMessage()
  971. {
  972. $this->setStatusMessage('');
  973. }
  974. //-------------------------------------------------------------------
  975. // METHOD: hasStatus
  976. //-------------------------------------------------------------------
  977. /**
  978. * This method returns a boolean to indicate if there is a status message for the window.
  979. *
  980. * @access public
  981. * @return bool Whether or not the window has a status message.
  982. * @see getStatusMessage().
  983. * @see setStatusMessage().
  984. */
  985. function hasStatus()
  986. {
  987. return (strlen($this->_statusMessage) > 0);
  988. }
  989. //-------------------------------------------------------------------
  990. // METHOD: setErrorMessage
  991. //-------------------------------------------------------------------
  992. /**
  993. * This method constructs sets 'user' error messages by simply trigger error.
  994. *
  995. * @access public
  996. * @see CC_ErrorManager
  997. */
  998. function setErrorMessage($errorMessage)
  999. {
  1000. trigger_error($errorMessage, E_USER_NOTICE);
  1001. }
  1002. //-------------------------------------------------------------------
  1003. // METHOD: getErrorMessage
  1004. //-------------------------------------------------------------------
  1005. /**
  1006. * This method constructs error messages based on the 'user' and 'field' error arrays in CC_Error_Manager. 'user' errors are displayed regardless of getVerboseErrors. 'field' errors are listed verbosely for each field if getVerboseErrors is true, otherwise a general message is displayed to check coloured fields for errors.
  1007. *
  1008. * @access public
  1009. * @return string The error message.
  1010. */
  1011. function getErrorMessage()
  1012. {
  1013. if ($this->hasError())
  1014. {
  1015. global $application;
  1016. $this->_errorMessage = '';
  1017. // user errors get displayed regardless of _verboseErrors
  1018. if ($application->errorManager->hasUserErrors())
  1019. {
  1020. // cycle through the user errors
  1021. $userErrors = $application->errorManager->getUserErrors();
  1022. $size = sizeof($userErrors);
  1023. for ($i = 0; $i < $size; $i++)
  1024. {
  1025. $userError = $userErrors[$i];
  1026. $this->_errorMessage .= '<span class="ccError">' . $userError->getMessage() . '</span>';
  1027. }
  1028. unset($size);
  1029. }
  1030. if ($application->errorManager->hasFieldErrors())
  1031. {
  1032. if ($this->_verboseErrors)
  1033. {
  1034. $this->_errorMessage .= '<span class="ccError">Please check the following fields and try again:</span><ul>';
  1035. // cycle through the field errors
  1036. $fieldErrors = $application->errorManager->getFieldErrors();
  1037. $size = sizeof($fieldErrors);
  1038. for ($j = 0; $j < $size; $j++)
  1039. {
  1040. $fieldError = $fieldErrors[$j];
  1041. $this->_errorMessage .= '<li class="ccError">' . $fieldError->getMessage();
  1042. }
  1043. unset($size);
  1044. $this->_errorMessage .= '</ul>';
  1045. }
  1046. else
  1047. {
  1048. $this->_errorMessage .= '<span class="ccError">There were problems with fields marked with this colour. Please check these and try again.</span>';
  1049. }
  1050. }
  1051. return $this->_errorMessage;
  1052. }
  1053. }
  1054. //-------------------------------------------------------------------
  1055. // METHOD: setDefaultButton
  1056. //-------------------------------------------------------------------
  1057. /**
  1058. * This method sets a default button with the window that is called if a user hits enter while in a field on the page. This method should always be called *after* the button has been registered.
  1059. *
  1060. * @access public
  1061. * @param CC_Button The button to set as the default.
  1062. */
  1063. function setDefaultButton(&$defaultButton)
  1064. {
  1065. $this->defaultButton = &$defaultButton;
  1066. }
  1067. //-------------------------------------------------------------------
  1068. // METHOD: clearArgument
  1069. //-------------------------------------------------------------------
  1070. /**
  1071. * This method clears a window argument of a given name.
  1072. *
  1073. * @access public
  1074. * @param string $name The name of the argument to clear.
  1075. * @see setArgument()
  1076. */
  1077. function clearArgument($name)
  1078. {
  1079. unset($this->arguments[$name]);
  1080. }
  1081. //-------------------------------------------------------------------
  1082. // METHOD: argumentExists
  1083. //-------------------------------------------------------------------
  1084. /**
  1085. * This method checks to see if an argument of a given name is registered with the window.
  1086. *
  1087. * @access public
  1088. * @param string $name The key of the argument to check.
  1089. * @return bool Whether or not the argument of given name is registered with the window.
  1090. * @see registerArgument()
  1091. * @deprecated Use hasArgument() instead...
  1092. * @see hasArgument()
  1093. */
  1094. function argumentExists($name)
  1095. {
  1096. trigger_error('argumentExists() is deprecated. Use hasArgument() instead.', E_USER_WARNING);
  1097. return $this->hasArgument($name);
  1098. }
  1099. //-------------------------------------------------------------------
  1100. // METHOD: hasArgument
  1101. //-------------------------------------------------------------------
  1102. /**
  1103. * This method checks to see if an argument of a given name is registered with the window.
  1104. *
  1105. * @access public
  1106. * @param string $name The key of the argument to check.
  1107. * @return bool Whether or not the argument of given name is registered with the window.
  1108. * @see registerArgument()
  1109. */
  1110. function hasArgument($name)
  1111. {
  1112. return isset($this->arguments[$name]);
  1113. }
  1114. //-------------------------------------------------------------------
  1115. // METHOD: getArgument
  1116. //-------------------------------------------------------------------
  1117. /**
  1118. * This method retrieves a window argument of a given name.
  1119. *
  1120. * @access public
  1121. * @param string $name The name of the argument to retrieve.
  1122. * @return mixed The argument of the given name.
  1123. * @see setArgument()
  1124. * @see argumentExists()
  1125. */
  1126. function getArgument($name)
  1127. {
  1128. if (!isset($name) || $name == NULL)
  1129. {
  1130. trigger_error('CC_Window::getArgument() was passed an unset or NULL object.');
  1131. }
  1132. if (isset($this->arguments[$name]))
  1133. {
  1134. return $this->arguments[$name];
  1135. }
  1136. else
  1137. {
  1138. trigger_error('The following argument doesn\'t exist: ' . $name . '. If you don\'t want this error message, use CC_Window::argumentExists() before calling this method.');
  1139. }
  1140. }
  1141. //-------------------------------------------------------------------
  1142. // METHOD: setArgument
  1143. //-------------------------------------------------------------------
  1144. /**
  1145. * This method registers a window argument of a given name. If you want to set an object in a window, use registerObject().
  1146. *
  1147. * @access public
  1148. * @param string $name The name of the argument to set.
  1149. * @param mixed $value The argument to register.
  1150. * @see getArgument()
  1151. * @see argumentExists()
  1152. * @see registerObject()
  1153. */
  1154. function setArgument($name, $value)
  1155. {
  1156. $this->arguments[$name] = $value;
  1157. }
  1158. //-------------------------------------------------------------------
  1159. // METHOD: getHeader()
  1160. //-------------------------------------------------------------------
  1161. /**
  1162. * This method is primarly for the default window classes, but you can (and should) use it for your own windows too. This should get called above all of your window display.
  1163. *
  1164. * @access public
  1165. * @return string The window header.
  1166. */
  1167. function getHeader()
  1168. {
  1169. return;
  1170. }
  1171. //-------------------------------------------------------------------
  1172. // METHOD: getFooter()
  1173. //-------------------------------------------------------------------
  1174. /**
  1175. * This method is primarly for the default window classes, but you can (and should) use it for your own windows too. This should get called below all of your window display.
  1176. *
  1177. * @access public
  1178. * @return string The window footer.
  1179. */
  1180. function getFooter()
  1181. {
  1182. return;
  1183. }
  1184. //-------------------------------------------------------------------
  1185. // METHOD: setUnregisterOnLeave()
  1186. //-------------------------------------------------------------------
  1187. /**
  1188. * By calling this method, you are instructing the application to
  1189. * unregister this window when the user goes to another window.
  1190. * This helps reduce clutter in the session and frees up memory
  1191. * unnecessarily used by windows you don't need anymore.
  1192. *
  1193. * @access public
  1194. */
  1195. function setUnregisterOnLeave($unregister = true)
  1196. {
  1197. $this->_unregisterOnLeave = $unregister;
  1198. }
  1199. //-------------------------------------------------------------------
  1200. // METHOD: cleanup()
  1201. //-------------------------------------------------------------------
  1202. /**
  1203. * This method is called when a window is unregistered. It is used
  1204. * to nullify and unset() instance variables to help with memory
  1205. * reduction.
  1206. *
  1207. * @access public
  1208. */
  1209. function cleanup()
  1210. {
  1211. $this->buttons = null;
  1212. $this->fields = null;
  1213. $this->records = null;
  1214. $this->summaries = null;
  1215. $this->components = null;
  1216. $this->defaultButton = null;
  1217. $this->objects = null;
  1218. $this->arguments = null;
  1219. unset($this->buttons);
  1220. unset($this->fields);
  1221. unset($this->records);
  1222. unset($this->summaries);
  1223. unset($this->components);
  1224. unset($this->defaultButton);
  1225. unset($this->objects);
  1226. unset($this->arguments);
  1227. }
  1228. }
  1229. ?>