PageRenderTime 71ms CodeModel.GetById 36ms RepoModel.GetById 0ms app.codeStats 0ms

/CC_Field.php

https://github.com/coverall/N2O
PHP | 1654 lines | 469 code | 355 blank | 830 comment | 32 complexity | 52761b7e20bb6d496d2467bc139d72f1 MD5 | raw file
  1. <?php
  2. // $Id: CC_Field.php,v 1.68 2010/11/11 04:28:32 patrick Exp $
  3. //=======================================================================
  4. // CLASS: CC_Field
  5. //=======================================================================
  6. define('CC_FIELD_ERROR_MISSING', 1);
  7. define('CC_FIELD_ERROR_INVALID', 2);
  8. define('CC_FIELD_ERROR_CUSTOM', 4);
  9. define('CC_FIELD_ERROR_ALL', 7);
  10. /**
  11. * This is the superclass for N2O fields. Fields provide applications with an interface to accept user input. Subclasses build on HTML form fields for display.
  12. *
  13. * When you define your fields for use with CC_Records using the CC_FieldManager's addField() method, you can use the fourth [optional] argument to pass the following initialization arguments:
  14. *
  15. * required=[0/1] - whether or not the field is required.
  16. * value=xxx - the default value of the field; only used if the field in the record has no existing value.
  17. *
  18. * Example: $application->fieldManager->addField('NAME', 'CC_Text_Field', 'Name', 'required=1&value=eg. Joe Smith');
  19. *
  20. * @package CC_Fields
  21. * @access public
  22. * @author The Crew <N2O@coverallcrew.com>
  23. * @copyright Copyright &copy; 2003, Coverall Crew
  24. * @todo Should getValue() return "[value]" or '[value]'? In PHP, single quoted strings are literal -- that is no variables are expanding, and only few escaped characters will actually work. Double-quoted strings will more heavily processed -- embedded variables are expanded, and there are many special characters you can use by escaping characters. (eg. \n, \r, \t, etc.) For more information on how PHP handles strings, see the following URLs: http://www.php.net/manual/en/language.types.string.php http://www.zend.com/zend/tut/using-strings.php
  25. */
  26. class CC_Field extends CC_Component
  27. {
  28. /**
  29. * Whether or not the field is required (ie. the user *must* provide a value in order to continue).
  30. *
  31. * @var bool $required
  32. * @access private
  33. * @see setRequired()
  34. */
  35. var $required;
  36. /**
  37. * The input component's optional CSS style.
  38. *
  39. * @var string $inputStyle
  40. * @see setInputStyle()
  41. * @access private
  42. */
  43. var $inputStyle;
  44. /**
  45. * The text label for the item.
  46. *
  47. * @var string $label
  48. * @access private
  49. * @see getLabel()
  50. * @see setLabel()
  51. */
  52. var $label;
  53. /**
  54. * The example text for the item.
  55. *
  56. * @var string $label
  57. * @access private
  58. * @see getExample()
  59. * @see setExample()
  60. */
  61. var $_example = '';
  62. /**
  63. * A field label that is unique across all application windows which is mainly used for CC_Summary spreadsheet downloads (instead of the $label variable which is not necessarily unique across all application windows).
  64. *
  65. * @var string $_summaryLabel
  66. * @access private
  67. * @see getSummaryLabel()
  68. * @see setSummaryLabel()
  69. */
  70. var $_summaryLabel;
  71. /**
  72. * Indicates whether or not to display an asterisk near the field label when the field is required.
  73. *
  74. * @var string $showAsterisk
  75. * @access private
  76. * @see setShowAsterisk()
  77. */
  78. var $showAsterisk = true;
  79. /**
  80. * The value of the field (stored only after the form is processed and data is updated).
  81. *
  82. * @var mixed $value
  83. * @see getValue()
  84. * @access private
  85. */
  86. var $value;
  87. /**
  88. * Indicates whether or not the field is to be added to the database when a record is added.
  89. *
  90. * @var bool $addToDatabase
  91. * @see setAddToDatabase()
  92. * @see CC_Record::buildUpdateQuery()
  93. * @see CC_Record::buildInsertQuery()
  94. * @access private
  95. */
  96. var $addToDatabase;
  97. /**
  98. * Indicated whether or not the current field has an error. Generally only true if the field is missing input or is invalid in some way.
  99. *
  100. * @var bool $_error
  101. * @see setError()
  102. * @access private
  103. */
  104. var $_error;
  105. /**
  106. * The error mask indicates which error messages are to be displayed to the user. Values to check for are CC_FIELD_ERROR_MISSING, CC_FIELD_ERROR_INVALID, CC_FIELD_ERROR_CUSTOM and CC_FIELD_ERROR_ALL
  107. *
  108. * @var int $_errorMask
  109. * @see setErrorMask()
  110. * @access private
  111. */
  112. var $_errorMask = CC_FIELD_ERROR_ALL;
  113. /**
  114. * The error message if a field's input is missing.
  115. *
  116. * @var string $_missingError
  117. * @see setErrorMessage()
  118. * @access private
  119. */
  120. var $_missingError = '';
  121. /**
  122. * The error message if a field's input is invalid.
  123. *
  124. * @var string $_invalidError
  125. * @see setErrorMessage()
  126. * @access private
  127. */
  128. var $_invalidError = '';
  129. /**
  130. * The custom error message for miscellaneous field errors.
  131. *
  132. * @var string $_customError
  133. * @see setErrorMessage()
  134. * @access private
  135. */
  136. var $_customError = '';
  137. /**
  138. * Indicates whether or not the field is encoded when added to the database.
  139. *
  140. * @var bool $encode
  141. * @see setEncode()
  142. * @see getEncode()
  143. * @access private
  144. */
  145. var $encode = false;
  146. /**
  147. * Indicates whether or not the field is read-only.
  148. *
  149. * @var bool $readonly
  150. * @see setReadOnly()
  151. * @see isReadOnly()
  152. * @access private
  153. */
  154. var $readonly = false;
  155. /**
  156. * Indicates whether or not this field is a foreign key.
  157. *
  158. * @var bool $foreignkey
  159. * @access public
  160. */
  161. var $foreignKey = false;
  162. /**
  163. * Indicates whether or not this field uses the database's password() function when it is added to the database.
  164. *
  165. * @var bool $password
  166. * @see setPassword()
  167. * @see getPassword()
  168. * @access private
  169. */
  170. var $password = false;
  171. /**
  172. * Set this to true for fields like LAST_MODIFIED that always needs its values updated direct from the database (as opposed to from the page via user input).
  173. *
  174. * @var bool $updateFromDatabase
  175. * @see setUpdateFromDatabase()
  176. * @see getUpdateFromDatabase()
  177. * @access private
  178. */
  179. var $updateFromDatabase = false;
  180. /**
  181. * A reference to the parent record, if there is one.
  182. *
  183. * @var CC_Record $record
  184. * @see setRecord()
  185. * @see getRecord()
  186. * @access private
  187. */
  188. var $record;
  189. /**
  190. * Set this to false if you don't want required fields to execute their validate handlers.
  191. *
  192. * @var bool $validateIfNotRequired
  193. * @see setValidateIfNotRequired()
  194. * @access private
  195. */
  196. var $validateIfNotRequired = true;
  197. /**
  198. * Set this to true if you want the field disabled
  199. *
  200. * @var bool $disabled
  201. * @see setDisabled()
  202. * @access private
  203. */
  204. var $disabled = false;
  205. /**
  206. * Use this for an optional id entity.
  207. *
  208. * @var string $id
  209. * @see setId()
  210. * @access private
  211. */
  212. var $id = '';
  213. /**
  214. * Keeps track of when a field has been updated but not saved to the database.
  215. *
  216. * @var string $updated
  217. * @see isUpdated()
  218. * @access private
  219. */
  220. var $updated = false;
  221. //-------------------------------------------------------------------
  222. // CONSTRUCTOR: CC_Field
  223. //-------------------------------------------------------------------
  224. /**
  225. * The CC_Field constructor should be called by each field subclass.
  226. *
  227. * @access public
  228. * @param string $name The unique name of the field. Names must be unique so that N2O knows which fields to update when users submit data.
  229. * @param string $label A text label to accompany the field to describe which input is either expected or displayed.
  230. * @param bool $required Whether or not this field must contain data from the user before proceeding. Fields are not required by default.
  231. * @param mixed $defaultValue The value the field should contain before user's submit input. Fields are initially blank by default.
  232. */
  233. function CC_Field($name, $label, $required = false, $defaultValue = '')
  234. {
  235. $this->setName($name);
  236. $this->label = $label;
  237. $this->setRequired($required);
  238. $this->_error = false;
  239. $this->setValue($defaultValue);
  240. $this->updated = false;
  241. $this->addToDatabase = true;
  242. }
  243. //-------------------------------------------------------------------
  244. // METHOD: setStyle
  245. //-------------------------------------------------------------------
  246. /**
  247. * This method sets the component's CSS style for the input and the label. The styles are described in cc_styles.css but can overriden for each application provided the appropriate CSS file is referenced in the application's header file(s).
  248. *
  249. * @access public
  250. * @param string $style The CSS style to set.
  251. */
  252. function setStyle($style)
  253. {
  254. $this->setLabelStyle($style);
  255. $this->setInputStyle($style);
  256. }
  257. //-------------------------------------------------------------------
  258. // METHOD: setInputStyle
  259. //-------------------------------------------------------------------
  260. /**
  261. * This method sets the input component's CSS style. The styles are described in cc_styles.css but can overriden for each application provided the appropriate CSS file is referenced in the application's header file(s).
  262. *
  263. * @access public
  264. * @param string $style The CSS style to set.
  265. */
  266. function setInputStyle($style)
  267. {
  268. $this->inputStyle = $style;
  269. }
  270. //-------------------------------------------------------------------
  271. // METHOD: getInputStyle
  272. //-------------------------------------------------------------------
  273. /**
  274. * This method gets the input component's CSS style.
  275. *
  276. * @access public
  277. * @return string The component's CSS style.
  278. * @see setStyle()
  279. */
  280. function getInputStyle()
  281. {
  282. return $this->inputStyle;
  283. }
  284. //-------------------------------------------------------------------
  285. // METHOD: setLabelStyle
  286. //-------------------------------------------------------------------
  287. /**
  288. * This method sets the label's CSS style. The styles are described in cc_styles.css but can overriden for each application provided the appropriate CSS file is referenced in the application's header file(s).
  289. *
  290. * @access public
  291. * @param string $style The CSS style to set for the label.
  292. */
  293. function setLabelStyle($style)
  294. {
  295. $this->labelStyle = $style;
  296. }
  297. //-------------------------------------------------------------------
  298. // METHOD: getLabelStyle
  299. //-------------------------------------------------------------------
  300. /**
  301. * This method gets the label's CSS style.
  302. *
  303. * @access public
  304. * @return string The label's CSS style.
  305. * @see setStyle()
  306. */
  307. function getLabelStyle()
  308. {
  309. return $this->labelStyle;
  310. }
  311. //-------------------------------------------------------------------
  312. // METHOD: setShowAsterisk
  313. //-------------------------------------------------------------------
  314. /**
  315. * This method sets whether or not to display an asterisk for required fields. If set to true it is common to provide a user with a message saying 'required fields are marked with an asterisk'.
  316. *
  317. * @access public
  318. * @param bool $show Whether or not to show the asterisk.
  319. */
  320. function setShowAsterisk($show)
  321. {
  322. $this->showAsterisk = $show;
  323. }
  324. //-------------------------------------------------------------------
  325. // METHOD: getLabelText
  326. //-------------------------------------------------------------------
  327. /**
  328. * This method gets the field's text label as text.
  329. *
  330. * @access public
  331. * @return string Text of the field's label.
  332. * @see setLabel()
  333. */
  334. function getLabelText()
  335. {
  336. return $this->label;
  337. }
  338. //-------------------------------------------------------------------
  339. // METHOD: getLabel
  340. //-------------------------------------------------------------------
  341. /**
  342. * This method gets the field's text label as HTML. If an error is encountered, the ccError styles is used, otherwise the field's current style is selected.
  343. *
  344. * @access public
  345. * @return string HTML of the field's label.
  346. * @see setLabel()
  347. */
  348. function getLabel()
  349. {
  350. $style = ($this->_error ? 'ccLabelError' : $this->labelStyle);
  351. if ($style)
  352. {
  353. $labelText = '<span class="' . $style . '">';
  354. }
  355. else
  356. {
  357. $labelText = '';
  358. }
  359. $labelText .= $this->label;
  360. if ($this->required && $this->showAsterisk)
  361. {
  362. $labelText .= '<sup>*</sup>';
  363. }
  364. if ($style)
  365. {
  366. $labelText .= '</span>';
  367. }
  368. unset($style);
  369. return $labelText;
  370. }
  371. //-------------------------------------------------------------------
  372. // METHOD: setLabel
  373. //-------------------------------------------------------------------
  374. /**
  375. * This method sets the field's text label.
  376. *
  377. * @access public
  378. * @param string $labelToSet The field's label.
  379. * @see getLabel()
  380. */
  381. function setLabel($labelToSet)
  382. {
  383. $this->label = $labelToSet;
  384. }
  385. //-------------------------------------------------------------------
  386. // METHOD: hasExample
  387. //-------------------------------------------------------------------
  388. /**
  389. * This method sets the field's example text.
  390. *
  391. * @access public
  392. * @return bool Whether or not the field has example text.
  393. * @see getExample()
  394. * @see setExample()
  395. */
  396. function hasExample()
  397. {
  398. return ($this->_example != '');
  399. }
  400. //-------------------------------------------------------------------
  401. // METHOD: setExample
  402. //-------------------------------------------------------------------
  403. /**
  404. * This method sets the field's example text.
  405. *
  406. * @access public
  407. * @param string $exampleToSet The field's example text.
  408. * @see getExample()
  409. */
  410. function setExample($exampleToSet)
  411. {
  412. $this->_example = $exampleToSet;
  413. }
  414. //-------------------------------------------------------------------
  415. // METHOD: getExample
  416. //-------------------------------------------------------------------
  417. /**
  418. * This method gets the field's example text.
  419. *
  420. * @access public
  421. * @return string The field's example text.
  422. * @see setExample()
  423. */
  424. function getExample()
  425. {
  426. return $this->_example;
  427. }
  428. //-------------------------------------------------------------------
  429. // METHOD: setSummaryLabel
  430. //-------------------------------------------------------------------
  431. /**
  432. * This method sets the field's summary text label. This is the label used to differentiate fields when downloading field data from a CC_Summary since fields may have the same labels in the application.
  433. *
  434. * @access public
  435. * @param string $labelToSet The field's summary label.
  436. * @see getSummaryLabel()
  437. */
  438. function setSummaryLabel($labelToSet)
  439. {
  440. $this->_summaryLabel = $labelToSet;
  441. }
  442. //-------------------------------------------------------------------
  443. // METHOD: getSummaryLabel
  444. //-------------------------------------------------------------------
  445. /**
  446. * This method gets the field's summary text label. This is the label used to differentiate fields when downloading field data from a CC_Summary since fields may have the same labels in the application.
  447. *
  448. * @access public
  449. * @param string $labelToSet The field's summary label.
  450. * @see setSummaryLabel()
  451. */
  452. function getSummaryLabel($labelToSet)
  453. {
  454. return $this->_summaryLabel;
  455. }
  456. //-------------------------------------------------------------------
  457. // METHOD: getHTML
  458. //-------------------------------------------------------------------
  459. /**
  460. * This method gets the HTML of the field for display in the window. Subclasses will want to override getViewHTML and getEditHTML.
  461. *
  462. * @access public
  463. * @return string The HTML for the field.
  464. * @see getEditHTML()
  465. * @see getViewHTML()
  466. */
  467. function getHTML()
  468. {
  469. if ($this->readonly)
  470. {
  471. return $this->getViewHTML();
  472. }
  473. else
  474. {
  475. return $this->getEditHTML();
  476. }
  477. }
  478. //-------------------------------------------------------------------
  479. // METHOD: getEditHTML
  480. //-------------------------------------------------------------------
  481. /**
  482. * This method gets the HTML of the field for editable fields (ie. not read-only).
  483. *
  484. * @access private
  485. * @return string The HTML for the editable field.
  486. * @see getViewHTML()
  487. * @see getHTML()
  488. * @see isReadOnly()
  489. */
  490. function getEditHTML()
  491. {
  492. return;
  493. }
  494. //-------------------------------------------------------------------
  495. // METHOD: getViewHTML
  496. //-------------------------------------------------------------------
  497. /**
  498. * This method gets the HTML of the field for non-editable fields (ie. read-only).
  499. *
  500. * @access private
  501. * @return string The HTML for the non-editable field.
  502. * @see getEditHTML()
  503. * @see getHTML()
  504. * @see isReadOnly()
  505. */
  506. function getViewHTML()
  507. {
  508. if ($this->inputStyle)
  509. {
  510. return '<span class="' . $this->inputStyle . '">' . $this->getValue() . '</span>';
  511. }
  512. else
  513. {
  514. return $this->getValue();
  515. }
  516. }
  517. //-------------------------------------------------------------------
  518. // METHOD: getEncode
  519. //-------------------------------------------------------------------
  520. /**
  521. * Gets whether or not the field is encoded when added to the database.
  522. *
  523. * @access public
  524. * @return bool Whether or not the field should be encoded in the database.
  525. * @see setEncode()
  526. */
  527. function getEncode()
  528. {
  529. return $this->encode;
  530. }
  531. //-------------------------------------------------------------------
  532. // METHOD: setEncode
  533. //-------------------------------------------------------------------
  534. /**
  535. * Sets whether or not the field is encoded when added to the database.
  536. *
  537. * @access public
  538. * @param bool $encode Whether or not the field should be encoded in the database.
  539. * @see getEncode()
  540. */
  541. function setEncode($encode)
  542. {
  543. $this->encode = $encode;
  544. }
  545. //-------------------------------------------------------------------
  546. // METHOD: getPassword
  547. //-------------------------------------------------------------------
  548. /**
  549. * Gets whether or not the field is encoded using the password() function when added to the database.
  550. *
  551. * @access public
  552. * @return bool Whether or not the field should be encoded with the password() function in the database.
  553. * @see setPassword()
  554. * @todo is this only for MYSQL?
  555. */
  556. function getPassword()
  557. {
  558. return $this->password;
  559. }
  560. //-------------------------------------------------------------------
  561. // METHOD: setPassword
  562. //-------------------------------------------------------------------
  563. /**
  564. * Sets whether or not the field is encoded using the password() function when added to the database.
  565. *
  566. * @access public
  567. * @param bool $password Whether or not the field should be encoded with the password() function in the database.
  568. * @see getPassword()
  569. */
  570. function setPassword($password)
  571. {
  572. $this->password = $password;
  573. }
  574. //-------------------------------------------------------------------
  575. // METHOD: setValue
  576. //-------------------------------------------------------------------
  577. /**
  578. * Sets the field's value.
  579. *
  580. * @access public
  581. * @param mixed $fieldValue The value to set the field to.
  582. * @see getValue()
  583. */
  584. function setValue($value = '')
  585. {
  586. if ($this->value != $value)
  587. {
  588. $this->updated = true;
  589. }
  590. $this->value = $value;
  591. }
  592. //-------------------------------------------------------------------
  593. // METHOD: isUpdated
  594. //-------------------------------------------------------------------
  595. /**
  596. * Has the field been updated?
  597. *
  598. * @access public
  599. */
  600. function isUpdated()
  601. {
  602. return $this->updated;
  603. }
  604. //-------------------------------------------------------------------
  605. // METHOD: handleUpdateFromRequest
  606. //-------------------------------------------------------------------
  607. /**
  608. * This method gets called by CC_Window when it's time to update the field from the $_REQUEST array. Most fields are straight forward, but some have additional fields in the request that need to be handled specially. Such fields should override this method, and update the field's value in their own special way.
  609. *
  610. * @access public
  611. * @param mixed $fieldValue The value to set the field to.
  612. * @see getValue()
  613. */
  614. function handleUpdateFromRequest()
  615. {
  616. $key = $this->getRequestArrayName();
  617. if (array_key_exists($key, $_REQUEST))
  618. {
  619. $this->setValue(stripslashes($_REQUEST[$key]));
  620. }
  621. unset($key);
  622. }
  623. //-------------------------------------------------------------------
  624. // METHOD: isReadOnly
  625. //-------------------------------------------------------------------
  626. /**
  627. * Gets whether or not the field is read-only, or uneditable.
  628. *
  629. * @access public
  630. * @return bool Whether or not the field is editable.
  631. * @see setReadOnly()
  632. */
  633. function isReadOnly()
  634. {
  635. return $this->readonly;
  636. }
  637. //-------------------------------------------------------------------
  638. // METHOD: setReadOnly
  639. //-------------------------------------------------------------------
  640. /**
  641. * Sets whether or not the field is read-only, or uneditable.
  642. *
  643. * @access public
  644. * @param bool $fieldReadOnly Whether or not the field is editable.
  645. * @see isReadOnly()
  646. */
  647. function setReadOnly($fieldReadOnly)
  648. {
  649. $this->readonly = $fieldReadOnly;
  650. }
  651. //-------------------------------------------------------------------
  652. // METHOD: setAddToDatabase
  653. //-------------------------------------------------------------------
  654. /**
  655. * Sets whether or not the field should be added to the database when the record is inserted or updated.
  656. *
  657. * @access public
  658. * @param bool $addToDatabase Whether or not the field should be added to the database.
  659. * @see CC_Record::buildUpdateQuery()
  660. * @see CC_Record::buildInsertQuery()
  661. */
  662. function setAddToDatabase($addToDatabase)
  663. {
  664. $this->addToDatabase = $addToDatabase;
  665. }
  666. //-------------------------------------------------------------------
  667. // METHOD: setUpdateFromDatabase
  668. //-------------------------------------------------------------------
  669. /**
  670. * Sets whether or not the field should be updated from its database value when the field is updated by N2O (as opposed to its page value). LAST_MODIFIED is the most popular field that gets updated from the database.
  671. *
  672. * @access public
  673. * @param bool $updateFromDatabase Whether or not the field should be update from the database.
  674. */
  675. function setUpdateFromDatabase($updateFromDatabase)
  676. {
  677. $this->updateFromDatabase = $updateFromDatabase;
  678. }
  679. //-------------------------------------------------------------------
  680. // METHOD: getUpdateFromDatabase
  681. //-------------------------------------------------------------------
  682. /**
  683. * Gets whether or not the field should be updated from its database value when the field is updated by N2O (as opposed to its page value. LAST_MODIFIED is the most popular field that gets updated from the database.
  684. *
  685. * @access public
  686. * @return bool Whether or not the field should be update from the database.
  687. */
  688. function getUpdateFromDatabase()
  689. {
  690. return $this->updateFromDatabase;
  691. }
  692. //-------------------------------------------------------------------
  693. // METHOD: addToDatabase
  694. //-------------------------------------------------------------------
  695. /**
  696. * Gets whether or not the field should be added to the database when the record is inserted or updated.
  697. *
  698. * @access public
  699. * @return bool Whether or not the field should be added to the database.
  700. * @see CC_Record::buildUpdateQuery()
  701. * @see CC_Record::buildInsertQuery()
  702. */
  703. function addToDatabase()
  704. {
  705. return $this->addToDatabase;
  706. }
  707. //-------------------------------------------------------------------
  708. // METHOD: getValue
  709. //-------------------------------------------------------------------
  710. /**
  711. * Gets the value of the field. This method should return a value that is suitable for insertion into a [MySQL] database.
  712. *
  713. * @access public
  714. * @return mixed The field's value.
  715. * @see setValue()
  716. */
  717. function getValue()
  718. {
  719. return $this->value;
  720. }
  721. //-------------------------------------------------------------------
  722. // METHOD: getEscapedValue
  723. //-------------------------------------------------------------------
  724. /**
  725. * Gets the escaped value of the field, suitable for insertion into a database.
  726. *
  727. * @access public
  728. * @return mixed The field's escaped value.
  729. */
  730. function getEscapedValue()
  731. {
  732. return addslashes($this->getValue());
  733. }
  734. //-------------------------------------------------------------------
  735. // METHOD: hasValue
  736. //-------------------------------------------------------------------
  737. /**
  738. * Gets whether or not the field has a value.
  739. *
  740. * @access public
  741. * @return bool Whether or not the field has a value.
  742. * @see setValue()
  743. * @see getValue()
  744. */
  745. function hasValue()
  746. {
  747. return !(strlen($this->getValue()) == 0);
  748. }
  749. //-------------------------------------------------------------------
  750. // METHOD: validate
  751. //-------------------------------------------------------------------
  752. /**
  753. * This method should be overriden in subclasses to validate field input. Subclasses should use setErrorMessage('', CC_FIELD_ERROR_INVALID) to set the validation error message if the user input is found to be invalid.
  754. *
  755. * @access protected
  756. * @return bool Whether or not the field is valid.
  757. */
  758. function validate()
  759. {
  760. $this->clearErrorMessage(CC_FIELD_ERROR_INVALID);
  761. return true;
  762. }
  763. //-------------------------------------------------------------------
  764. // METHOD: setInvalidMessage()
  765. //-------------------------------------------------------------------
  766. /**
  767. * This method sets the validation message in CC_Field
  768. *
  769. * @access public
  770. * @param string $message The invalidity message to set subclasses' validate() method.
  771. * @deprecated
  772. */
  773. function setInvalidMessage($message)
  774. {
  775. trigger_error('setInvalidMessage is a deprecated method', E_USER_WARNING);
  776. $this->setErrorMessage('');
  777. }
  778. //-------------------------------------------------------------------
  779. // METHOD: getInvalidMessage()
  780. //-------------------------------------------------------------------
  781. /**
  782. * This method gets the validation message set in CC_Field subclasses' validate() method
  783. *
  784. * @access public
  785. * @return string The invalidity message.
  786. * @deprecated
  787. */
  788. function getInvalidMessage()
  789. {
  790. trigger_error('getInvalidMessage is a deprecated method', E_USER_WARNING);
  791. return $this->getErrorMessage(CC_FIELD_ERROR_INVALID);
  792. }
  793. //-------------------------------------------------------------------
  794. // METHOD: deleteCleanup
  795. //-------------------------------------------------------------------
  796. /**
  797. * Subclasses should override this method if any cleanup needs to be done upon their deletion (eg. deleting associated files).
  798. *
  799. * @access public
  800. */
  801. function deleteCleanup()
  802. {
  803. }
  804. //-------------------------------------------------------------------
  805. // METHOD: cancelCleanup
  806. //-------------------------------------------------------------------
  807. /**
  808. * Fields should override this method if any cleanup needs to be done upon cancellation (eg. CC_File_Upload_To_Path_Field is one case).
  809. *
  810. * @access public
  811. */
  812. function cancelCleanup()
  813. {
  814. }
  815. //-------------------------------------------------------------------
  816. // METHOD: setError
  817. //-------------------------------------------------------------------
  818. /**
  819. * This function sets whether or not this field has an error
  820. *
  821. * @access public
  822. * @param bool $error Whether or not the field has an error.
  823. */
  824. function setError($error = true)
  825. {
  826. $this->_error = $error;
  827. }
  828. //-------------------------------------------------------------------
  829. // METHOD: _addError
  830. //-------------------------------------------------------------------
  831. /**
  832. * This function adds an error to the field
  833. *
  834. * @access private
  835. * @param string $errorMessage the error message to set, resets if nothing is passed
  836. * @deprecated
  837. */
  838. function _addError($errorMessage = '')
  839. {
  840. trigger_error('_addError() is a deprecated method. Use setErrorMessage($message, CC_FIELD_ERROR_CUSTOM) instead.', E_USER_WARNING);
  841. $this->setErrorMessage($errorMessage, CC_FIELD_ERROR_CUSTOM);
  842. }
  843. //-------------------------------------------------------------------
  844. // METHOD: addMissingError
  845. //-------------------------------------------------------------------
  846. /**
  847. * @access public
  848. * @deprecated
  849. */
  850. function addMissingError()
  851. {
  852. trigger_error('addMissingError() is a deprecated method. Use setErrorMessage($message, CC_FIELD_ERROR_MISSING) instead.', E_USER_WARNING);
  853. $this->setErrorMessage($this->label . ' is required', CC_FIELD_ERROR_MISSING);
  854. }
  855. //-------------------------------------------------------------------
  856. // METHOD: addInvalidError
  857. //-------------------------------------------------------------------
  858. /**
  859. * @access public
  860. * @deprecated
  861. *
  862. */
  863. function addInvalidError()
  864. {
  865. trigger_error('addInvalidError() is a deprecated method. Use setErrorMessage($message, CC_FIELD_ERROR_INVALID) instead.', E_USER_WARNING);
  866. $this->setErrorMessage($this->label . ' is invalid.', CC_FIELD_ERROR_INVALID);
  867. }
  868. //-------------------------------------------------------------------
  869. // METHOD: setMissingError
  870. //-------------------------------------------------------------------
  871. /**
  872. * This function sets an error for missing data.
  873. *
  874. * @access public
  875. * @deprecated
  876. */
  877. function setMissingError()
  878. {
  879. trigger_error('setMissingError() is a deprecated method. Use setErrorMessage($message, CC_FIELD_ERROR_MISSING) instead.', E_USER_WARNING);
  880. $this->setErrorMessage($this->label . ' is required', CC_FIELD_ERROR_MISSING);
  881. }
  882. //-------------------------------------------------------------------
  883. // METHOD: setInvalidError
  884. //-------------------------------------------------------------------
  885. /**
  886. * This function sets an error for invalid data. _errorMessage here comes from the field's validate() handler or other error-checking methods
  887. *
  888. * @access public
  889. * @deprecated
  890. */
  891. function setInvalidError()
  892. {
  893. trigger_error('setInvalidError() is a deprecated method. Use setErrorMessage($message, CC_FIELD_ERROR_INVALID) instead.', E_USER_WARNING);
  894. $this->setErrorMessage($this->label . ' is invalid.', CC_FIELD_ERROR_INVALID);
  895. }
  896. //-------------------------------------------------------------------
  897. // METHOD: hasError
  898. //-------------------------------------------------------------------
  899. /**
  900. * This function returns whether or not this field has an error associated with it.
  901. *
  902. * @access public
  903. * @return bool Whether this field has an error.
  904. * @see setErrorMessage()
  905. *
  906. */
  907. function hasError()
  908. {
  909. return $this->_error;
  910. }
  911. //-------------------------------------------------------------------
  912. // METHOD: setErrorMask
  913. //-------------------------------------------------------------------
  914. /**
  915. * This function sets this field's error mask, describing which error messages are to be displayed
  916. *
  917. * @access public
  918. * @param int $mask The mask to set.
  919. */
  920. function setErrorMask($mask = CC_FIELD_ERROR_ALL)
  921. {
  922. $this->_errorMask = $mask;
  923. }
  924. //-------------------------------------------------------------------
  925. // METHOD: setErrorMessage
  926. //-------------------------------------------------------------------
  927. /**
  928. * This function sets an error message in the field. The type of error message will depends on the error level passed. Choices are CC_FIELD_ERROR_MISSING, CC_FIELD_ERROR_INVALID or CC_FIELD_ERROR_CUSTOM.
  929. *
  930. * @access public
  931. * @param string $message The error message to add.
  932. * @param int $errorlevel The error type being added.
  933. */
  934. function setErrorMessage($message, $errorLevel = CC_FIELD_ERROR_CUSTOM)
  935. {
  936. switch ($errorLevel)
  937. {
  938. case CC_FIELD_ERROR_MISSING:
  939. {
  940. $this->setError();
  941. $this->_missingError = $message;
  942. }
  943. break;
  944. case CC_FIELD_ERROR_INVALID:
  945. {
  946. $this->setError();
  947. $this->_invalidError = $message;
  948. }
  949. break;
  950. case CC_FIELD_ERROR_CUSTOM:
  951. {
  952. $this->setError();
  953. $this->_customError = $message;
  954. }
  955. break;
  956. default:
  957. {
  958. trigger_error('An invalid error type was passed', E_USER_WARNING);
  959. }
  960. break;
  961. }
  962. }
  963. //-------------------------------------------------------------------
  964. // METHOD: getErrorMessage
  965. //-------------------------------------------------------------------
  966. /**
  967. * This function gets an error message based on the error level passed. Choices are CC_FIELD_ERROR_MISSING, CC_FIELD_ERROR_INVALID or CC_FIELD_ERROR_CUSTOM.
  968. *
  969. * @access public
  970. * @param int $errorlevel The error type being added.
  971. * @return string The error message of the given level.
  972. */
  973. function getErrorMessage($errorLevel = CC_FIELD_ERROR_CUSTOM)
  974. {
  975. if ($this->_errorMask & $errorLevel)
  976. {
  977. switch ($errorLevel)
  978. {
  979. case CC_FIELD_ERROR_MISSING:
  980. return $this->_missingError;
  981. break;
  982. case CC_FIELD_ERROR_INVALID:
  983. return $this->_invalidError;
  984. break;
  985. case CC_FIELD_ERROR_CUSTOM:
  986. return $this->_customError;
  987. break;
  988. default:
  989. trigger_error('An invalid error type was passed.', E_USER_WARNING);
  990. return '';
  991. break;
  992. }
  993. }
  994. else
  995. {
  996. trigger_error('An error message of the given error level was not found.', E_USER_WARNING);
  997. return '';
  998. }
  999. }
  1000. //-------------------------------------------------------------------
  1001. // METHOD: getErrorMessageDisplay
  1002. //-------------------------------------------------------------------
  1003. /**
  1004. * This function gets this field's error message as HTML. The error returned depends on the error level passed.
  1005. *
  1006. * @access public
  1007. * @param int errorLevel The level of error message to retrieve.
  1008. * @return string The error message of given level.
  1009. */
  1010. function getErrorMessageDisplay($errorLevel = CC_FIELD_ERROR_CUSTOM)
  1011. {
  1012. if ($this->hasError())
  1013. {
  1014. if ($this->_errorMask & $errorLevel)
  1015. {
  1016. switch ($errorLevel)
  1017. {
  1018. case CC_FIELD_ERROR_MISSING:
  1019. return '<span class="ccError">' . $this->_missingError . '</span>';
  1020. break;
  1021. case CC_FIELD_ERROR_INVALID:
  1022. return '<span class="ccError">' . $this->_invalidError . '</span>';
  1023. break;
  1024. case CC_FIELD_ERROR_CUSTOM:
  1025. return '<span class="ccError">' . $this->_customError . '</span>';
  1026. break;
  1027. default:
  1028. trigger_error('An invalid error type was passed', E_USER_WARNING);
  1029. return '';
  1030. break;
  1031. }
  1032. }
  1033. else
  1034. {
  1035. trigger_error('An error message of the given error level was not found.', E_USER_WARNING);
  1036. return '';
  1037. }
  1038. }
  1039. }
  1040. //-------------------------------------------------------------------
  1041. // METHOD: clearErrorMessage
  1042. //-------------------------------------------------------------------
  1043. /**
  1044. * This function clears the field error of the given error level.
  1045. *
  1046. * @access public
  1047. * @param int $errorLevel The level of errors to clear.
  1048. */
  1049. function clearErrorMessage($errorLevel = CC_FIELD_ERROR_CUSTOM)
  1050. {
  1051. switch ($errorLevel)
  1052. {
  1053. case CC_FIELD_ERROR_MISSING:
  1054. $this->_missingError = '';
  1055. if (($this->_invalidError == '') && ($this->_customError == ''))
  1056. {
  1057. $this->setError(false);
  1058. }
  1059. break;
  1060. case CC_FIELD_ERROR_INVALID:
  1061. $this->_invalidError = '';
  1062. if (($this->_missingError == '') && ($this->_customError == ''))
  1063. {
  1064. $this->setError(false);
  1065. }
  1066. break;
  1067. case CC_FIELD_ERROR_CUSTOM:
  1068. $this->_customError = '';
  1069. if (($this->_missingError == '') && ($this->_invalidError == ''))
  1070. {
  1071. $this->setError(false);
  1072. }
  1073. break;
  1074. case CC_FIELD_ERROR_ALL:
  1075. $this->clearAllErrors();
  1076. break;
  1077. default:
  1078. trigger_error('An invalid error type was passed', E_USER_WARNING);
  1079. break;
  1080. }
  1081. }
  1082. //-------------------------------------------------------------------
  1083. // METHOD: clearAllErrors
  1084. //-------------------------------------------------------------------
  1085. /**
  1086. * This function clears all levels of field errors.
  1087. *
  1088. * @access public
  1089. * @see setErrorMessage()
  1090. */
  1091. function clearAllErrors()
  1092. {
  1093. $this->setError(false);
  1094. $this->_missingError = '';
  1095. $this->_invalidError = '';
  1096. $this->_customError = '';
  1097. }
  1098. //-------------------------------------------------------------------
  1099. // METHOD: setRequired
  1100. //-------------------------------------------------------------------
  1101. /**
  1102. * Sets whether or not the field is required.
  1103. *
  1104. * @access public
  1105. * @param bool $required Whether or not the field is required.
  1106. * @see isRequired()
  1107. */
  1108. function setRequired($required)
  1109. {
  1110. $this->required = $required;
  1111. if ($required)
  1112. {
  1113. $this->setLabelStyle('ccRequiredField');
  1114. }
  1115. else
  1116. {
  1117. $this->setLabelStyle('ccNotRequiredField');
  1118. }
  1119. }
  1120. //-------------------------------------------------------------------
  1121. // METHOD: isRequired
  1122. //-------------------------------------------------------------------
  1123. /**
  1124. * Returns whether or not the field is required.
  1125. *
  1126. * @access public
  1127. * @see setRequired()
  1128. */
  1129. function isRequired()
  1130. {
  1131. return $this->required;
  1132. }
  1133. //-------------------------------------------------------------------
  1134. // METHOD: setRecord
  1135. //-------------------------------------------------------------------
  1136. /**
  1137. * Sets the record that the field belongs to. It is used by CC_Record when creating field objects in the constructor. Subclasses can extend this method if they are built up of more than one field (ie. CC_Date_Field, CC_Time_Field etc...).
  1138. *
  1139. * @access private
  1140. * @see getRecord()
  1141. * @see CC_Record::CC_Record()
  1142. */
  1143. function setRecord(&$record)
  1144. {
  1145. $this->record = &$record;
  1146. }
  1147. //-------------------------------------------------------------------
  1148. // METHOD: getRecord
  1149. //-------------------------------------------------------------------
  1150. /**
  1151. * Gets the record that the field belongs to.
  1152. *
  1153. * @access public
  1154. * @return CC_Record The record that this field belongs to.
  1155. * @see setRecord()
  1156. */
  1157. function &getRecord()
  1158. {
  1159. return $this->record;
  1160. }
  1161. //-------------------------------------------------------------------
  1162. // METHOD: isInRecord
  1163. //-------------------------------------------------------------------
  1164. /**
  1165. * Returns whether or not this field is part of a record or a standalone field.
  1166. *
  1167. * @access public
  1168. * @return bool Whether or not this field belongs to a record.
  1169. * @see getRecord()
  1170. */
  1171. function isInRecord()
  1172. {
  1173. return isset($this->record);
  1174. }
  1175. //-------------------------------------------------------------------
  1176. // METHOD: getRecordKey
  1177. //-------------------------------------------------------------------
  1178. /**
  1179. * Gets the record key of the parent record or false if it is a standalone field.
  1180. *
  1181. * @access public
  1182. * @return mixed A string representing the owner record's key or false if it is a standalone field (ie. not part of a record).
  1183. * @see isInRecord()
  1184. */
  1185. function getRecordKey()
  1186. {
  1187. if ($this->isInRecord())
  1188. {
  1189. return ($this->record->getKeyID($this->record->table, $this->record->id)) . '|';
  1190. }
  1191. else
  1192. {
  1193. //trigger_error('The field ' . $this->name . ' did not belong to a record.', E_USER_WARNING);
  1194. return false;
  1195. }
  1196. }
  1197. //-------------------------------------------------------------------
  1198. // METHOD: getRequestArrayName()
  1199. //-------------------------------------------------------------------
  1200. /**
  1201. * Gets the name of the field as it appears in the request array.
  1202. *
  1203. * @access public
  1204. * @return string A string representing the field's request array name or false if it is a standalone field (ie. not part of a record).
  1205. * @see isInRecord()
  1206. * @see getRecordKey()
  1207. * @see getName()
  1208. */
  1209. function getRequestArrayName()
  1210. {
  1211. return $this->getRecordKey() . $this->getName();
  1212. }
  1213. //-------------------------------------------------------------------
  1214. // METHOD: setValidateIfNotRequired()
  1215. //-------------------------------------------------------------------
  1216. /**
  1217. * Sets whether or not the field should be validated even if it is not a required field.
  1218. *
  1219. * @access public
  1220. * @param bool $validate Whether or not the field should be validated even if it isn't required.
  1221. */
  1222. function setValidateIfNotRequired($validate)
  1223. {
  1224. $this->validateIfNotRequired = $validate;
  1225. }
  1226. //-------------------------------------------------------------------
  1227. // METHOD: setDisabled()
  1228. //-------------------------------------------------------------------
  1229. /**
  1230. * Sets whether or not the field should be disabled. Note that this
  1231. * may not work in all fields (yet).
  1232. *
  1233. * @access public
  1234. * @param bool $disable Whether to disable the field or not (true or false)
  1235. */
  1236. function setDisabled($disable)
  1237. {
  1238. $this->disabled = $disable;
  1239. }
  1240. //-------------------------------------------------------------------
  1241. // METHOD: isDisabled()
  1242. //-------------------------------------------------------------------
  1243. /**
  1244. * Sets whether or not the field should be disabled. Note that this
  1245. * may not work in all fields (yet).
  1246. *
  1247. * @access public
  1248. * @return bool Whether the field is disabled or not
  1249. */
  1250. function isDisabled()
  1251. {
  1252. return $this->disabled;
  1253. }
  1254. //-------------------------------------------------------------------
  1255. // METHOD: setId()
  1256. //-------------------------------------------------------------------
  1257. /**
  1258. * Sets the id entity for the field
  1259. *
  1260. * @access public
  1261. * @param bool $disable Whether to disable the field or not (true or false)
  1262. */
  1263. function setId($id)
  1264. {
  1265. $this->id = $id;
  1266. }
  1267. //-------------------------------------------------------------------
  1268. // METHOD: register
  1269. //-------------------------------------------------------------------
  1270. /**
  1271. * This is a callback method that gets called by the window when the
  1272. * component is registered. It's up to the component to decide which
  1273. * registerXXX() method it should call on the window. Should your
  1274. * custom component consist of multiple components, you may need to
  1275. * make multiple calls.
  1276. *
  1277. * @access public
  1278. */
  1279. function register(&$window)
  1280. {
  1281. $window->registerField($this);
  1282. }
  1283. //-------------------------------------------------------------------
  1284. // STATIC METHOD: getInstance
  1285. //-------------------------------------------------------------------
  1286. /**
  1287. * This is a static method called by CC_Record when it needs an instance
  1288. * of a field. The implementing field needs to return a constructed
  1289. * instance of itself.
  1290. *
  1291. * @access public
  1292. */
  1293. static function &getInstance($className, $name, $label, $value, $args, $required)
  1294. {
  1295. $field = new $className($name, $label, $required, $value);
  1296. return $field;
  1297. }
  1298. }
  1299. ?>