ENH: refs #231. Respond to QA feedback

Removed trailing spaces; fixed the wrong URL to config.agreementtab.css
Use $ instead of jQuery; Added block documentation for php and js function
and classes

Author: yuzhengZ

modules/communityagreement/AppController.php

@@ -10,7 +10,12 @@
 PURPOSE.  See the above copyright notices for more information.
 =========================================================================*/
 
-
+/**
+ * Communityagreement_AppController
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ */
 class Communityagreement_AppController extends MIDAS_GlobalModule
   {
   public $moduleName='communityagreement';
@@ -21,5 +26,4 @@ class Communityagreement_AppController extends MIDAS_GlobalModule
    */
   var $Communityagreement_Agreement;
   } //end class
-?>
-
+?>

modules/communityagreement/Notification.php

@@ -1,34 +1,55 @@
 <?php
-/** notification manager*/
+/**
+ * Communityagreement_Notification
+ *
+ * notification manager
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ */
 class Communityagreement_Notification extends MIDAS_Notification
   {
   public $_models = array('Community');
-  
-  /** init notification process*/
+
+  /**
+   * init notification process
+   */
   public function init()
     {
     $this->addCallBack('CALLBACK_CORE_GET_COMMUNITY_MANAGE_TABS', 'getCommunityManageTabs');
     $this->addCallBack('CALLBACK_CORE_GET_COMMUNITY_VIEW_JSS', 'getCommunityViewJSs');
     $this->addCallBack('CALLBACK_CORE_GET_COMMUNITY_VIEW_CSSS', 'getCommunityViewCSSs');
     }//end init
-    
-  /** get tabs */
+
+  /**
+   * callback function to get 'community agreement' tab
+   *
+   * @return array
+   */
   public function getCommunityManageTabs()
     {
     $fc = Zend_Controller_Front::getInstance();
     $moduleWebroot = $fc->getBaseUrl().'/communityagreement';
     return array('Community Agreement' => $moduleWebroot.'/config/agreementtab');
     }
-  
-  /** get Java scripts */  
+
+  /**
+   * callback function to get java script
+   *
+   * @return array
+   */
   public function getCommunityViewJSs()
     {
     $fc = Zend_Controller_Front::getInstance();
     $moduleUriroot = $fc->getBaseUrl().'/modules/communityagreement';
     return array($moduleUriroot.'/public/js/config/config.agreementcheckbox.js');
     }
-  
-  /** get CSS */
+
+  /**
+   * callback function to get CSS
+   *
+   * @return array
+   */
   public function getCommunityViewCSSs()
     {
     $fc = Zend_Controller_Front::getInstance();
@@ -38,4 +59,3 @@ public function getCommunityViewCSSs()
 
   } //end class
 ?>
-

modules/communityagreement/configs/module.ini

@@ -6,5 +6,4 @@ fullname= Community Agreement
 ; description
 description= "Enables community agreement"
 ;Category
-category= Core
-
+category= Core

modules/communityagreement/constant/module.php

@@ -12,4 +12,4 @@
 
 define("MIDAS_COMMUNITYAGREEMENT_AGREEMENT_IS_EMPTY", 0);
 define("MIDAS_COMMUNITYAGREEMENT_AGREEMENT_NOT_EMPTY", 1);
-?>
+?>

modules/communityagreement/controllers/ConfigController.php

@@ -9,58 +9,70 @@
 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.  See the above copyright notices for more information.
 =========================================================================*/
-/** community agreement config controller*/
+/**
+ * Communityagreement_ConfigController
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ */
 class Communityagreement_ConfigController extends Communityagreement_AppController
 {
   public $_models = array('Community');
   public $_moduleModels = array('Agreement');
   public $_moduleForms = array('Config');
-  
-  /** index */
+
+  /**
+   * @method indexAction()
+   * @throws Zend_Exception on invalid userSession
+   */
   function indexAction()
     {
     if(!$this->logged || !$this->userSession->Dao->getAdmin() == 1)
       {
       throw new Zend_Exception("You should be an administrator");
       }
-    } 
-    
-  /** 
-  *  @method agreementtabAction() 
-  *  community agreement tab. It is shown in the community manage page when the 'community agreement' module is enabled
-  */   
+    }
+
+  /** community agreement tab
+   * 
+   * Shown in the community manage page when the 'community agreement' module is enabled
+   * 
+   * @method agreementtabAction()
+   * @throws Zend_Exception on invalid communityId 
+  */
   function agreementtabAction()
     {
-   
-    if(!$this->logged)  
+
+    if(!$this->logged)
       {
       $this->haveToBeLogged();
       return false;
       }
-    if($this->_helper->hasHelper('layout')) 
+    if($this->_helper->hasHelper('layout'))
       {
       $this->_helper->layout->disableLayout();
       }
-      
+
     $communityId = $this->_getParam("communityId");
     if(!isset($communityId) || (!is_numeric($communityId) && strlen($communityId) != 32)) // This is tricky! and for Cassandra for now
       {
       throw new Zend_Exception("Community ID should be a number");
       }
-      
+
     $agreementDao = $this->Communityagreement_Agreement->getByCommunityId($communityId);
-    
-    // If community agreement does not exist, show an emtpy string to the cummunity administrator
+
+    // If cannot find any community agreement using the given communityID, 
+    // initilize the community agreement using an empty string and then create an agreementDao 
     if($agreementDao == false)
       {
       $agreement = '';
       $agreementDao = $this->Communityagreement_Agreement->createAgreement($communityId, $agreement);
       }
-    
-    $formAgreement = $this->ModuleForm->Config->createCreateAgreementForm($communityId);  
-    if($this->_request->isPost() && $formAgreement->isValid($this->getRequest()->getPost())) 
+
+    $formAgreement = $this->ModuleForm->Config->createCreateAgreementForm($communityId);
+    if($this->_request->isPost() && $formAgreement->isValid($this->getRequest()->getPost()))
       {
-      if($this->_helper->hasHelper('layout')) 
+      if($this->_helper->hasHelper('layout'))
         {
         $this->_helper->layout->disableLayout();
         }
@@ -75,32 +87,38 @@ function agreementtabAction()
         echo JsonComponent::encode(array(false, $this->t('Error')));
         }
       }
-    
-    // if agreement only contains white spaces, delete it from the database.
+
+    // If a community agreement only contains white spaces, it is treated as an empty agreement
+    // and will be deleted from the database if it exists
     $chopped_agreement = chop($agreementDao->getAgreement());
-    if($chopped_agreement != '' ) 
+    if($chopped_agreement != '' )
       {
       $this->Communityagreement_Agreement->save($agreementDao);
       } 
     else if($this->Communityagreement_Agreement->getByCommunityId($communityId) != false)
       {
       $this->Communityagreement_Agreement->delete($agreementDao);
       }  
-      
-    //init form
+
+    // init form
     $agreement = $formAgreement->getElement('agreement');
     $agreement->setValue($agreementDao->getAgreement());
-    $this->view->agreementForm = $this->getFormAsArray($formAgreement); 
-    $this->view->agreementDao = $agreementDao;         
+    $this->view->agreementForm = $this->getFormAsArray($formAgreement);
+    $this->view->agreementDao = $agreementDao;
     }
-   
-  /** 
-  *  @method agreementdialogAction() 
-  *  community agreement dialog, show the community agreements to peaple who want to join the community
-    */
+
+  /**
+   * community agreement dialog
+   * 
+   * When a user wants to read the community agreement before joining the community, the "agreement" link will be clicked
+   * and this dialog will be shown
+   * 
+   * @method agreementdialogAction()
+   * @throws Zend_Exception on invalid communityId
+  */
   function agreementdialogAction()
     {
-    if($this->_helper->hasHelper('layout')) 
+    if($this->_helper->hasHelper('layout'))
       {
       $this->_helper->layout->disableLayout();
       }
@@ -110,21 +128,22 @@ function agreementdialogAction()
       {
       throw new Zend_Exception("Community ID should be a number");
       }
-    
-    $agreementDao = $this->Communityagreement_Agreement->getByCommunityId($communityId);  
+
+    $agreementDao = $this->Communityagreement_Agreement->getByCommunityId($communityId);
     if($agreementDao == false)
       {
       $agreement = '';
       $agreementDao = $this->Communityagreement_Agreement->createAgreement($communityId, $agreement);
       }
-    $this->view->agreementDao = $agreementDao;          
+    $this->view->agreementDao = $agreementDao;
     }
-   
- 
+
   /**
-  * @method checkIfAgreementEmptyAction()
-   * ajax function which checks if the community agreement has been set 
-   */
+   * ajax function which checks if the community agreement has been set
+   * 
+   * @method checkagreementAction()
+   * @throws Zend_Exception on invalid request
+  */
   public function checkagreementAction()
     {
     if(!$this->getRequest()->isXmlHttpRequest())
@@ -135,15 +154,15 @@ public function checkagreementAction()
     $this->_helper->viewRenderer->setNoRender();
 
     $communityId = $this->_getParam("communityId");
-    $agreementDao = $this->Communityagreement_Agreement->getByCommunityId($communityId);  
+    $agreementDao = $this->Communityagreement_Agreement->getByCommunityId($communityId);
     if($agreementDao != false)
       {
       echo JsonComponent::encode(MIDAS_COMMUNITYAGREEMENT_AGREEMENT_NOT_EMPTY);
       }
     else
       {
       echo JsonComponent::encode(MIDAS_COMMUNITYAGREEMENT_AGREEMENT_IS_EMPTY);
-      }  
+      }
     }
- 
+
 }//end class

modules/communityagreement/controllers/forms/ConfigForm.php

@@ -10,24 +10,35 @@
 PURPOSE.  See the above copyright notices for more information.
 =========================================================================*/
 
-/** Community Agreement forms*/
+/**
+ * Communityagreement_ConfigForm
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ * @copyright  Copyright (c) Kitware SAS. See Copyright.txt for details.
+ */
 
 class Communityagreement_ConfigForm extends AppForm
 {
-  /** create create agreement form */
+  /**
+   * Create create_agreement form
+   *
+   * @param string $community_id
+   * @return Zend_Form
+   */
   public function createCreateAgreementForm($community_id)
     {
     $form = new Zend_Form;
     $form->setAction($this->webroot.'/communityagreement/config/agreementtab?communityId='.$community_id)
          ->setMethod('post');
     $agreement = new Zend_Form_Element_Textarea('agreement');
-   
+
     $submit = new  Zend_Form_Element_Submit('submit');
     $submit->setLabel($this->t("Save"));
-    
+
     $form->addElements(array($agreement, $submit));
     return $form;
     }
-    
+
 } // end class
 ?>

modules/communityagreement/database/mysql/1.0.0.sql

@@ -1,12 +1,11 @@
-
--- `communityagreement_agreement` table
-ALTER TABLE `community` ENGINE = InnoDB;
-
 # DROP TABLE IF EXISTS communityagreement_agreement;
-CREATE TABLE communityagreement_agreement (
+--
+-- Structure of table `communityagreement_agreement`
+--
+CREATE TABLE IF NOT EXISTS communityagreement_agreement (
   `agreement_id` bigint(20) NOT NULL AUTO_INCREMENT,
   `community_id` bigint(20) NOT NULL REFERENCES community.community_id,
   `agreement` text NOT NULL,
   PRIMARY KEY (`agreement_id`),
   KEY `community_id` (`community_id`)
-) ENGINE=InnoDB AUTO_INCREMENT=200;
+) AUTO_INCREMENT=200;

modules/communityagreement/models/AppDao.php

@@ -1,8 +1,13 @@
 <?php
-
+/**
+ * Communityagreement_AppDao
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ */
 class Communityagreement_AppDao extends MIDAS_GlobalDao
   {
     public $moduleName='communityagreement';
   } //end class
 
-?>
+?>

modules/communityagreement/models/AppModel.php

@@ -10,8 +10,14 @@
 PURPOSE.  See the above copyright notices for more information.
 =========================================================================*/
 
+/**
+ * Communityagreement_AppModel
+ *
+ * @category   Midas modules
+ * @package    communityagreement
+ */
 class Communityagreement_AppModel extends MIDASModel
 {
   public $moduleName='communityagreement';
 }
-?>
+?>