Differences

This shows you the differences between two versions of the page.

--- devzone:howto:start [2014/02/12 17:53]
Roel [Lay-out, typo
+++ devzone:howto:start [2020/03/12 12:06] (current)
@@ Line 6: / Line 6: @@
 ===== How do I get started =====
 Follow the steps in the [[[[userzone:quickstart|Quickstart guide]].
+===== Getting started using events =====
+[[devzone:howto:getting_started_with_gemstracker_events]]
 ===== How do I debug the code =====
@@ Line 84: / Line 87: @@
 As every project has it's own data to work on, one of the most common actions is to change the display of the columns shown in the Respondents/Patients screen.
-First to explain why we sometimes talk about respondents and sometimes about patients. Of course a respondent is someone who either answers a survey or about whom a survey is answered by someone else. Either way the survey belongs to that respondent. A patient is of course someone who receive health care. As GemsTracker is build for health care institutions in most existing projects respondents are patients, but there is no reason why they could not be truckers, butchers, mail man or just any other group of random respondents. That is why internally GemsTracker revers to respondents (we even hunt down the use of the word patient in the core library) but use a default English translation that does not but translate 'respondent' into 'patient'.
+First to explain why we sometimes talk about respondents and sometimes about patients. Of course a respondent is someone who either answers a survey or about whom a survey is answered by someone else. Either way, the survey belongs to that respondent. A patient is of course someone who receives health care. In most existing projects GemsTracker is build for health care institutions, and so respondents are patients, but there is no reason why they could not be truckers, butchers, mail man or just any other group of respondents. That is why internally GemsTracker refers to respondents (we even hunt down the use of the word patient in the core library) but use a default English translation that does not but translate 'respondent' into 'patient'.
-To change the displayed columns copy library/Gems/controllers/RespondentController.php' to application/controllers/RespondentController.php'. GemsTracker automatically sees the new RespondentController.php file and starts using that controller. RespondentController.php is an empty stub that inherits all functionality from Gems_Default_RespondentAction. This allows you to overrule or extend the default functionality without have to copy the code, with all the maintenance issues this entails.
+To change the displayed columns copy library/Gems/controllers/RespondentController.php' to application/controllers/RespondentController.php'. GemsTracker automatically sees the new RespondentController.php file and starts using that controller. RespondentController.php is an empty stub that inherits all functionality from Gems_Default_RespondentAction. This allows you to overrule or extend the default functionality without having to copy the code, with all the maintenance issues this entails.
 Now your first thought might be that to change the workings of the 'index' action you must overrule the indexAction() function, but the search as you type function returns a result from autofilterAction() and column content is added in the protected _createTable() function that is used by both functions. However, the actual action of specifying what columns have to be displayed is done in the addBrowseTableColumns() function overloaded in RespondentAction. To change the columns you must overload this function again in your copy of RespondentController.
@@ Line 130: / Line 133: @@
 The addMultiSort() functions add a cell to the $bridge (that is used to form a bridge between an HTML table and a model). Add a field name that exists in the model and it will be displayed in that column. Add a MUtil_Html::raw() object to add fixed text. Just experiment with commenting field on or off and you will quickly get the result you want.
+  Hiding fields is accomplished by adding the fields again without a label.
 ===== How do I add a column in the respondent/patient details and overview? =====
-Enough blahdiblah, lets do this as-you-type, hands-on. For example, you want to administer a studycode with every respondent.\\
+Now lets do this hands-on. For example, you want to administer a studycode with every respondent.\\
-This is a field that will have at most 10 string characters, and an index will speed up sorting actions on this field.\\
+This field will have at most 10 string characters, and an index will speed up sorting actions on this field.\\
  In SQL code it looks like this:
 <code sql>
@@ Line 142: / Line 146: @@
   ALTER TABLE `gems__respondents` ADD INDEX `grs_studycode` ( `grs_studycode` );
 </code>
-  - Create a file patches.sql with this code in application\configs\db\tables
+  - Create a file **patches.sql** with this code in **application\configs\db\tables**
-  - run the code in this patch as super in your application (setup - database - execute new - yes) -> your table should be updated.
+  - run the code in this patch as super in your application (setup - database - execute new - yes) -> your table should be updated.\\ Sloppy alternative: you can run the sql code from phpMyAdmin.\\ For a new project installation you can alter the gems_respondents.30.php file in the same directory and use that to create your new tables in Gemstracker.
-  - copy library\Gems\classes\Gems\Default\RespondentAction.php to application\controllers\RespondentController.php
+This is the 'old school' (GemsTracker version < 1.6.0) version: (could still work in newer versions, no guarantees)
+  - copy library\Gems\controllers\RespondentAction.php to **application\controllers\RespondentController.php**
+  - copy the class code in **library\Gems\classes\Gems\Default\RespondentAction.php** to this new RespondentController
+  - change <code php> class RespondentController extends Gems_Default_RespondentNewAction</code> to <code php>class RespondentController extends Gems_Default_RespondentAction</code>
   - In this controller, you need to change 3 functions: createModel, addFormElements and addBrowsetableColumns
-  * In function createModel, after line 2 insert this code in order to add your field to the model (dataset):
+  * In function createModel, after line 2 (just before the 'if ($detailed)' line) insert this code in order to add your field to the model (dataset):
 <code php>        $model = $this->loader->getModels()->getRespondentModel($detailed);
-        $model->setIfExists('grs_studycode', 'label', $this->_('Studycode'));
+        $model->setIfExists('grs_studycode', 'label', $this->_('Studycode')); </code>
-</code> this is just before the 'if ($detailed)' line.
   * in addFormElements, insert the next line at the position where you want your field to appear:<code php>
         $bridge->addText(    'grs_studycode',            'label', $this->_('Studycode'), 'size', 10, 'maxlength', 10);
@@ Line 157: / Line 164: @@
 </code> just before the line with $bridge->addMultiSort('gr2o_patient_nr', $...
-That's it! Don't forget to first clean the cache if you want to see the result of this code.
+This is the __current method__ (1.6.0 and newer, where more is adapted in the model):
+  - Adjust the RespondentModel.php file in **application\classes\[YourProject]\Models**
+  - be sure to have the class name changed as needed for your project
+  - Insert this code to change the browse display:<code php>    /**
+     * Set those settings needed for the browse display
+     *
+     * @return \Gems_Model_RespondentModel
+     */
+    public function applyBrowseSettings()
+    {
+        parent::applyBrowseSettings();
+        $translator = $this->translate->getAdapter();
+        $this->set('grs_studycode', 'label', $translator->_('Studycode'));
+        return $this;
+    }</code>
+  - change the applyDetailsSettings function to this:<code php>    public function applyDetailSettings($locale = null)
+    {
+        parent::applyDetailSettings($locale);
+        $translator = $this->translate->getAdapter();
+        $order = $this->getOrder('grs_last_name') + 1;
+        $this->set('grs_studycode', 'label', $translator->_('Studycode'),
+                'order', $order++,
+                'tab',   $this->get('gr2o_patient_nr', 'tab'));
+        return $this;
+    }
+</code>
+  - Change the applyEditSettings function to this:<code php>    public function applyEditSettings($locale = null)
+    {
+        parent::applyEditSettings($locale);
+        $translator = $this->getTranslateAdapter();
+        $this->set('grs_studycode','required', true);
+        /*
+        $this->set('grs_studycode',
+                'validators[regex]', new Zend_Validate_Regex('/^d+/'),
+                'validators[unique]', $this->createUniqueValidator('grs_studycode') //, array('gr2o_id_organization'))
+                );
+        // */
+        return $this;
+    }
+</code>
+  - in **application/controllers/RespondentController.php** add this code to the RespondentController class:<code:php>    /**
+     * Set column usage to use for the browser.
+     *
+     * Must be an array of arrays containing the input for TableBridge->setMultisort()
+     *
+     * @return array or false
+     */
+    public function getBrowseColumns()
+    {
+        $columns = array(5 => array('grs_studycode', MUtil_Html::create('br'))) + parent::getBrowseColumns();
+        // unset($columns[20]);
+        return $columns;
+    }
+    </code>
+  - add path and file **application/classes/[Yourproject]/Snippets/RespondentDetailsSnippet.php** (copy from library\Gems\snippets)
+  - change the classname to [Yourproject]_Snippets_RespondentDetailsSnippet (keep it extending to...)
+  - in function addTableCells add your field at the appropriate position: <code php>        // ROW 1
+        $bridge->addItem('grs_studycode', null, array('class' => 'strong'));
+        $bridge->addItem('grs_phone_1');
+        // ROW 2
+        $bridge->addItem('grs_birthday');
+        $bridge->addItem($address, $this->_('Address'), array('rowspan' => 2));
+        // ROW 3
+        $bridge->addItem('grs_email');
+        // ROW 4 - example code: note the colspan to have this field use 2 columns
+        // $bridge->addItem('grs_studycode', null, array('colspan' => 2));
+</code>
+  - to use more columns, look at this code: <code php>        $bridge->caption($this->getCaption());
+        //example code to change the number of columns over which the fields will be distributed
+        //$bridge->setColumnCount(2);
+</code>
+That's it! Don't forget to first clean the cache if you don't see the result of this code immediately.\\
+Also don't forget to look at the quick start guide, installation, point 4 (uncomment line 8 in application.ini).
+Please note:
+  * starting at point 3 you can see the use of the translation adapter that will translate your field name
+  * at point 4 the use of get/set the field order attribute is demonstrated
+  * at point 5 the field is set to be a required field
+  * As you can see in the last part, the details snippet can easily be changed to your preferences.
+Icings on the cake:
+  * add the translated fieldname to the appropriate langage files
+  * add a validator (see above point 5 in applyEditSettings for an example)
+  * change the view of this field by adding a class name and changing the css.

GemsTracker

User Tools

Site Tools

Differences

Page Tools