#3871# Added referral tracking. Needs testing.

plugins/generic/referral/Referral.inc.php

+<?php
+
+/**
+ * @file plugins/generic/referral/Referral.inc.php
+ *
+ * Copyright (c) 2003-2008 John Willinsky
+ * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
+ *
+ * @class Referral
+ * @ingroup plugins_generic_referral
+ * @see ReferralDAO
+ *
+ * @brief Basic class describing a referral.
+ */
+
+// $Id$
+
+
+define('REFERRAL_STATUS_NEW',		0x00000001);
+define('REFERRAL_STATUS_ACCEPT',	0x00000002);
+define('REFERRAL_STATUS_DECLINE',	0x00000003);
+
+class Referral extends DataObject {
+	//
+	// Get/set methods
+	//
+
+	/**
+	 * Get the ID of the referral.
+	 * @return int
+	 */
+	function getReferralId() {
+		return $this->getData('referralId');
+	}
+
+	/**
+	 * Set the ID of the referral.
+	 * @param $referralId int
+	 */
+	function setReferralId($referralId) {
+		return $this->setData('referralId', $referralId);
+	}
+
+	/**
+	 * Get the article ID of the referral.
+	 * @return int
+	 */
+	function getArticleId() {
+		return $this->getData('articleId');
+	}
+
+	/**
+	 * Set the article ID of the referral.
+	 * @param $articleId int
+	 */
+	function setArticleId($articleId) {
+		return $this->setData('articleId', $articleId);
+	}
+
+	/**
+	 * Get the URL of the referral.
+	 * @return string
+	 */
+	function getURL() {
+		return $this->getData('url');
+	}
+
+	/**
+	 * Set the URL of the referral.
+	 * @param $url string
+	 */
+	function setURL($url) {
+		return $this->setData('url', $url);
+	}
+
+	/**
+	 * Get the status flag of the referral (REFERRAL_STATUS_...).
+	 * @return int
+	 */
+	function getStatus() {
+		return $this->getData('status');
+	}
+
+	/**
+	 * Get the locale key corresponding to this referral's status
+	 */
+	function getStatusKey() {
+		switch ($this->getStatus()) {
+			case REFERRAL_STATUS_NEW: return 'plugins.generic.referral.status.new';
+			case REFERRAL_STATUS_ACCEPT: return 'plugins.generic.referral.status.accept';
+			case REFERRAL_STATUS_DECLINE: return 'plugins.generic.referral.status.decline';
+		}
+	}
+
+	/**
+	 * Set the status flag of the referral.
+	 * @param $status int REFERRAL_STATUS_...
+	 */
+	function setStatus($status) {
+		return $this->setData('status', $status);
+	}
+
+	/**
+	 * Get the date added of the referral.
+	 * @return boolean
+	 */
+	function getDateAdded() {
+		return $this->getData('dateAdded');
+	}
+
+	/**
+	 * Set the date added of the referral.
+	 * @param $dateAdded date
+	 */
+	function setDateAdded($dateAdded) {
+		return $this->setData('dateAdded', $dateAdded);
+	}
+
+	/**
+	 * Get the name of the referral.
+	 * @return string
+	 */
+	function getReferralName() {
+		return $this->getLocalizedData('name');
+	}
+
+	/**
+	 * Get the name of the referral.
+	 * @param $locale string
+	 * @return string
+	 */
+	function getName($locale) {
+		return $this->getData('name', $locale);
+	}
+
+	/**
+	 * Set the name of the referral.
+	 * @param $name string
+	 * @param $locale string
+	 */
+	function setName($name, $locale) {
+		return $this->setData('name', $name, $locale);
+	}
+
+	/**
+	 * Get the link count of the referral.
+	 * @return int
+	 */
+	function getLinkCount() {
+		return $this->getData('linkCount');
+	}
+
+	/**
+	 * Set the link count of the referral.
+	 * @param $linkCount int
+	 */
+	function setLinkCount($linkCount) {
+		return $this->setData('linkCount', $linkCount);
+	}
+}
+
+?>

plugins/generic/referral/ReferralDAO.inc.php

+<?php
+
+/**
+ * @file plugins/generic/referral/ReferralDAO.inc.php
+ *
+ * Copyright (c) 2003-2008 John Willinsky
+ * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
+ *
+ * @class ReferralDAO
+ * @ingroup plugins_generic_referral
+ * @see Referral
+ *
+ * @brief Operations for retrieving and modifying Referral objects.
+ */
+
+// $Id$
+
+
+class ReferralDAO extends DAO {
+	/**
+	 * Retrieve an referral by referral ID.
+	 * @param $referralId int
+	 * @return Referral
+	 */
+	function &getReferral($referralId) {
+		$result =& $this->retrieve(
+			'SELECT * FROM referrals WHERE referral_id = ?', $referralId
+		);
+
+		$returner = null;
+		if ($result->RecordCount() != 0) {
+			$returner =& $this->_returnReferralFromRow($result->GetRowAssoc(false));
+		}
+		$result->Close();
+		return $returner;
+	}
+
+	/**
+	 * Get a list of localized field names
+	 * @return array
+	 */
+	function getLocaleFieldNames() {
+		return array('name');
+	}
+
+	/**
+	 * Internal function to return a Referral object from a row.
+	 * @param $row array
+	 * @return Referral
+	 */
+	function &_returnReferralFromRow(&$row) {
+		$referral = new Referral();
+		$referral->setReferralId($row['referral_id']);
+		$referral->setArticleId($row['article_id']);
+		$referral->setStatus($row['status']);
+		$referral->setUrl($row['url']);
+		$referral->setDateAdded($this->datetimeFromDB($row['date_added']));
+		$referral->setLinkCount($row['link_count']);
+
+		$this->getDataObjectSettings('referral_settings', 'referral_id', $row['referral_id'], $referral);
+
+		return $referral;
+	}
+
+	/**
+	 * Check if a referrer exists with the given article and URL.
+	 * @param $articleId int
+	 * @param $url string
+	 * @return boolean
+	 */
+	function referralExistsByUrl($articleId, $url) {
+		$result =& $this->retrieve(
+			'SELECT	COUNT(*)
+			FROM	referrals
+			WHERE	article_id = ? AND
+				url = ?',
+			array(
+				(int) $articleId,
+				$url
+			)
+		);
+		$returner = isset($result->fields[0]) && $result->fields[0] != 0 ? true : false;
+
+		$result->Close();
+		unset($result);
+
+		return $returner;
+	}
+
+	/**
+	 * Increment the referral count.
+	 * @param $articleId int
+	 * @param $url string
+	 * @return int 1 iff the referral exists
+	 */
+	function incrementReferralCount($articleId, $url) {
+		return $this->update(
+			'UPDATE referrals SET link_count = link_count + 1 WHERE article_id = ? AND url = ?',
+			array((int) $articleId, $url)
+		);
+	}
+
+	/**
+	 * Update the localized settings for this object
+	 * @param $referral object
+	 */
+	function updateLocaleFields(&$referral) {
+		$this->updateDataObjectSettings('referral_settings', $referral, array(
+			'referral_id' => $referral->getReferralId()
+		));
+	}
+
+	/**
+	 * Insert a new Referral.
+	 * @param $referral Referral
+	 * @return int 
+	 */
+	function insertReferral(&$referral) {
+		$this->update(
+			sprintf(
+				'INSERT INTO referrals
+					(status, article_id, url, date_added, link_count)
+				VALUES
+					(?, ?, ?, %s, ?)',
+				$this->datetimeToDB($referral->getDateAdded())
+			),
+			array(
+				(int) $referral->getStatus(),
+				(int) $referral->getArticleId(),
+				$referral->getUrl(),
+				(int) $referral->getLinkCount()
+			)
+		);
+		$referral->setReferralId($this->getInsertReferralId());
+		$this->updateLocaleFields($referral);
+		return $referral->getReferralId();
+	}
+
+	/**
+	 * Update an existing referral.
+	 * @param $referral Referral
+	 * @return boolean
+	 */
+	function updateReferral(&$referral) {
+		$returner = $this->update(
+			sprintf('UPDATE	referrals
+				SET	status = ?,
+					article_id = ?,
+					url = ?,
+					date_added = %s,
+					link_count = ?
+				WHERE	referral_id = ?',
+				$this->datetimeToDB($referral->getDateAdded())
+			),
+			array(
+				(int) $referral->getStatus(),
+				(int) $referral->getArticleId(),
+				$referral->getUrl(),
+				(int) $referral->getLinkCount(),
+				(int) $referral->getReferralId()
+			)
+		);
+		$this->updateLocaleFields($referral);
+		return $returner;
+	}
+
+	/**
+	 * Delete a referral.
+	 * deleted.
+	 * @param $referral Referral 
+	 * @return boolean
+	 */
+	function deleteReferral($referral) {
+		return $this->deleteReferralById($referral->getTypeId());
+	}
+
+	/**
+	 * Delete a referral by referral ID.
+	 * @param $referralId int
+	 * @return boolean
+	 */
+	function deleteReferralById($referralId) {
+		$this->update('DELETE FROM referral_settings WHERE referral_id = ?', $referralId);
+		return $this->update('DELETE FROM referrals WHERE referral_id = ?', $referralId);
+	}
+
+	/**
+	 * Retrieve an iterator of referrals for a particular user ID,
+	 * optionally filtering by status.
+	 * @param $userId int
+	 * $param $status int
+	 * @return object DAOResultFactory containing matching Referrals
+	 */
+	function &getReferralsByUserId($userId, $status = null, $rangeInfo = null) {
+		$params = array((int) $userId);
+		if ($status !== null) $params[] = (int) $status;
+		$result =& $this->retrieveRange(
+			'SELECT	r.*
+			FROM	referrals r,
+				articles a
+			WHERE	r.article_id = a.article_id AND
+				a.user_id = ?' .
+				($status !== null?' AND r.status = ?':'') . '
+			ORDER BY r.date_added',
+			$params
+		);
+
+		$returner = new DAOResultFactory($result, $this, '_returnReferralFromRow');
+		return $returner;
+	}
+
+	/**
+	 * Retrieve an iterator of published referrals for a particular user article
+	 * @param $articleId int
+	 * $param $rangeInfo RangeInfo
+	 * @return object DAOResultFactory containing matching Referrals
+	 */
+	function &getPublishedReferralsForArticle($articleId, $rangeInfo = null) {
+		$result =& $this->retrieveRange(
+			'SELECT	r.*
+			FROM	referrals r
+			WHERE	r.article_id = ? AND
+				r.status = ?',
+			array((int) $articleId, REFERRAL_STATUS_ACCEPT),
+			$rangeInfo
+		);
+
+		$returner = new DAOResultFactory($result, $this, '_returnReferralFromRow');
+		return $returner;
+	}
+
+	/**
+	 * Get the ID of the last inserted referral.
+	 * @return int
+	 */
+	function getInsertReferralId() {
+		return $this->getInsertId('referrals', 'referral_id');
+	}
+}
+
+?>

plugins/generic/referral/ReferralForm.inc.php

+<?php
+
+/**
+ * @file classes/manager/form/ReferralForm.inc.php
+ *
+ * Copyright (c) 2003-2008 John Willinsky
+ * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
+ *
+ * @class ReferralForm
+ * @ingroup manager_form
+ * @see AnnouncementForm
+ *
+ * @brief Form for authors to create/edit referrals.
+ */
+
+// $Id$
+
+
+import('form.Form');
+
+class ReferralForm extends Form {
+	/** @var referralId int the ID of the referral being edited */
+	var $referralId;
+
+	/** @var $article object the article this referral refers to */
+	var $article;
+
+	/**
+	 * Constructor
+	 * @param referralId int leave as default for new referral
+	 */
+	function ReferralForm(&$plugin, &$article, $referralId = null) {
+		$this->referralId = isset($referralId) ? (int) $referralId : null;
+		$this->article =& $article;
+
+		parent::Form($plugin->getTemplatePath() . 'referralForm.tpl');
+
+		// Name is provided
+		$this->addCheck(new FormValidatorLocale($this, 'name', 'required', 'plugins.generic.referral.nameRequired'));
+		$this->addCheck(new FormValidatorURL($this, 'url', 'required', 'plugins.generic.referral.urlRequired'));
+
+		$this->addCheck(new FormValidatorPost($this));
+	}
+
+	/**
+	 * Get a list of localized field names for this form
+	 * @return array
+	 */
+	function getLocaleFieldNames() {
+		$referralDao =& DAORegistry::getDAO('ReferralDAO');
+		return $referralDao->getLocaleFieldNames();
+	}
+
+	/**
+	 * Display the form.
+	 */
+	function display() {
+		$templateMgr =& TemplateManager::getManager();
+		$templateMgr->assign('referralId', $this->referralId);
+		$templateMgr->assign_by_ref('article', $this->article);
+		// $templateMgr->assign('helpTopicId', 'FIXME');
+
+		parent::display();
+	}
+
+	/**
+	 * Initialize form data from current referral.
+	 */
+	function initData() {
+		if (isset($this->referralId)) {
+			$referralDao =& DAORegistry::getDAO('ReferralDAO');
+			$referral =& $referralDao->getReferral($this->referralId);
+
+			if ($referral != null) {
+				$this->_data = array(
+					'name' => $referral->getName(null), // Localized
+					'status' => $referral->getStatus(),
+					'url' => $referral->getUrl()
+				);
+
+			} else {
+				$this->referralId = null;
+			}
+		}
+	}
+
+	/**
+	 * Assign form data to user-submitted data.
+	 */
+	function readInputData() {
+		$this->readUserVars(array('name', 'url', 'status'));
+	}
+
+	/**
+	 * Save referral. 
+	 */
+	function execute() {
+		$referralDao =& DAORegistry::getDAO('ReferralDAO');
+
+		if (isset($this->referralId)) {
+			$referral =& $referralDao->getReferral($this->referralId);
+		}
+
+		if (!isset($referral)) {
+			$referral = new Referral();
+			$referral->setDateAdded(Core::getCurrentDate());
+			$referral->setLinkCount(0);
+		}
+
+		$referral->setArticleId($this->article->getArticleId());
+		$referral->setName($this->getData('name'), null); // Localized
+		$referral->setUrl($this->getData('url'));
+		$referral->setStatus($this->getData('status'));
+
+		// Update or insert referral
+		if ($referral->getReferralId() != null) {
+			$referralDao->updateReferral($referral);
+		} else {
+			$referralDao->insertReferral($referral);
+		}
+	}
+}
+
+?>

plugins/generic/referral/ReferralHandler.inc.php

+<?php
+
+/**
+ * @file ReferralHandler.inc.php
+ *
+ * Copyright (c) 2003-2008 John Willinsky
+ * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
+ *
+ * @class ReferralHandler
+ * @ingroup plugins_generic_referral
+ *
+ * @brief This handles requests for the referral plugin.
+ */
+
+// $Id$
+
+
+import('core.PKPHandler');
+
+class ReferralHandler extends PKPHandler {
+	function setupTemplate() {
+		parent::setupTemplate();
+		$templateMgr =& TemplateManager::getManager();
+		$pageHierarchy = array(array(Request::url(null, 'referral', 'index'), 'plugins.generic.referral.referrals'));
+		$templateMgr->assign('pageHierarchy', $pageHierarchy);
+	}
+
+	function editReferral($args) {
+		$referralId = (int) array_shift($args);
+		if ($referralId === 0) $referralId = null;
+
+		list($plugin, $referral, $article) = ReferralHandler::validate($referralId);
+		ReferralHandler::setupTemplate();
+
+		$plugin->import('ReferralForm');
+		$templateMgr =& TemplateManager::getManager();
+
+		if ($referralId == null) {
+			$templateMgr->assign('referralTitle', 'plugins.generic.referral.createReferral');
+		} else {
+			$templateMgr->assign('referralTitle', 'plugins.generic.referral.editReferral');	
+		}
+
+		$referralForm = new ReferralForm($plugin, $article, $referralId);
+		if ($referralForm->isLocaleResubmit()) {
+			$referralForm->readInputData();
+		} else {
+			$referralForm->initData();
+		}
+		$referralForm->display();
+	}
+
+	/**
+	 * Save changes to an announcement type.
+	 */
+	function updateReferral() {
+		$referralId = (int) Request::getUserVar('referralId');
+		if ($referralId === 0) $referralId = null;
+
+		list($plugin, $referral, $article) = ReferralHandler::validate($referralId);
+		// If it's an insert, ensure that it's allowed for this article
+		if (!isset($referral)) {
+			$publishedArticleDao =& DAORegistry::getDAO('PublishedArticleDAO');
+			$journal =& Request::getJournal();
+			$article =& $publishedArticleDao->getPublishedArticleByArticleId((int) Request::getUserVar('articleId'));
+			if (!$article || ($article->getUserId() != $user->getUserId() && !Validation::isSectionEditor($journal->getJournalId()) && !Validation::isEditor($journal->getJournalId()))) {
+				Request::redirect(null, 'author');
+			}
+		}
+		ReferralHandler::setupTemplate();
+
+		$plugin->import('ReferralForm');
+
+		$referralForm = new ReferralForm($plugin, $article, $referralId);
+		$referralForm->readInputData();
+
+		if ($referralForm->validate()) {
+			$referralForm->execute();
+			Request::redirect(null, 'author');
+		} else {
+			$templateMgr =& TemplateManager::getManager();
+
+			if ($referralId == null) {
+				$templateMgr->assign('referralTitle', 'plugins.generic.referral.createReferral');
+			} else {
+				$templateMgr->assign('referralTitle', 'plugins.generic.referral.editReferral');	
+			}