AutocompleteExternalModule.php

<?php
/// A sample piece of code.
/**
 * AutocompleteExternalModule
 *  - CLASS for some features.
 *  
 *  
 *  - MGB - Mass General Brigham DRO. 
 * @author David L. Heskett
 * @version1.0.0
 * @date20250710
 * @copyright &copy; 2025 Mass General Brigham, DRA, Digital Research Applications <a href="https://rc.partners.org//">MGB DRA\</a>  <a href="https://redcap.partners.org/redcap/">redcap.partners.org</a> 
 */
 
namespace MGB\AutocompleteExternalModule;

use ExternalModules\AbstractExternalModule;
use ExternalModules\ExternalModules;

use \HtmlPage;
use \Logging;
use \REDCap;

class AutocompleteExternalModule extends AbstractExternalModule
{
    public $debug_mode_log_system;
    public $debug_mode_log_project;

    private $projectId;

    const NAME_IDENTIFIER = 'Autocomplete';

    const TAG_NAME_IDENTIFIER = '@AUTOCOMPLETE';
    
    // **********************************************************************   
    // **********************************************************************   
    // **********************************************************************   


    /**
     * loadSystemConfig - System configuration settings here.
     */
    public function loadSystemConfig() 
    {
        $this->debug_mode_log_system = $this->getSystemSetting('debug_mode_log_system');
        
        // put some of your other config settings here

    }

    /**
     * loadProjectConfig - Project configuration settings here.
     */
    public function loadProjectConfig($projectId = 0) 
    {        
        if ($projectId == 0) {
            global $Proj;
            $projectId = $Proj->project_id;
        }
        
        if ($projectId > 0) {
            $this->debug_mode_log_project = $this->getProjectSetting('debug_mode_log_project');

            // put some of your other config settings here
        }
    }

    /**
     * loadProjectConfigDefaults - set up our defaults.
     */
    public function loadProjectConfigDefaults()
    {
        $this->debug_mode_log_system   = false;
        $this->debug_mode_log_project   = false;
    }
 
    // **********************************************************************   
    // **********************************************************************   
    // **********************************************************************

    /**
    * redcap_survey_page - redcap survey page will show our autocomplete data in a field.
    */
    public function redcap_survey_page($project_id, $record, $instrument, $event_id, $group_id, $survey_hash, $response_id, $repeat_instance)
    {        
        echo $this->buildJs($project_id, $instrument);
    }

    /**
    * redcap_data_entry_form - redcap data entry form will show our autocomplete data in a field.
    */
    public function redcap_data_entry_form($project_id, $record, $instrument, $event_id, $group_id, $repeat_instance)
    {
        echo $this->buildJs($project_id, $instrument);
    }

    // getProjectTagFields() returns an array of all project instrument fields in which some tag appears.
    //   Each array contains the variable Name of the field,
    //   and an array of elements_index and params
    //
    // getProjectTagFields()  replaces hooks init_tags()
    //
    // **OLD**
    // init_tags() returns an array of all project instrument fields in which some tag
    // appears. Each array contains the variable Name of the field, and an array of
    // elements_index and params        
    //
    // $tag_functions = init_tags(__FILE__);
    //
    // see hooks_common.php and some Luke Stevens variant
    // see: hooks/redcap_hooks/framework/hooks_common.php

    /**
    * getProjectActionTagFields - find targetTag in the project metadata, we are hunting down the action tags here.
    */
    public function getProjectActionTagFields($targetTag = '')
    {
        global $Proj;
        
        // Get project metadata
        $metadata = $Proj->metadata;
        
        // Initialize array to store matching fields
        $matchingFields = [];
        
        foreach ($metadata as $field_name => $field_info) {
            if(stripos($field_info['misc'], $targetTag) !== false){
                $matchingFields[$field_name] = $field_name;
            }
        }

        return $matchingFields;
    }    

    /**
    * buildJs - gets fields with specified Action Tag, build the JS code using data from the fields list, returns the JS as a string.
    */
    public function buildJs($project_id = '', $instrument = '')
    {
        $this->debug_mode_log_project = $this->getProjectSetting('debug_mode_log_project');
        
        $tag = AutocompleteExternalModule::TAG_NAME_IDENTIFIER;
        
        $msg = 'Running Autocomplete - ' . $tag . ' for PID: ' . $project_id . ', INSTR: [' . $instrument . ']';
        $this->emlogging($msg);
                
        $tag_functions = $this->getProjectActionTagFields($tag);
        
        if (empty($tag_functions)) {
            return;
        }
        
        // If this particular tag is not used on this survey/form, no need to load
        if (!isset($tag_functions)) {
            return;
        }
        
        // Ok, tag is used in this project - process it
        $msg = 'Running ' . $tag . ' for PID: ' . $project_id . ', INSTR: [' . $instrument . ']';
        $this->emlogging($msg);
        
        // Step 1 - Create array of fields containing the tag, by variable name
        $startup_vars = $tag_functions;//[$tag];
        
        $msg = 'vars = ' . var_export($startup_vars,true);
        $this->emlogging($msg);
        
        // Step 2 - include the file that actually puts the JS in there
        $jsString = $this->makeJs($startup_vars);
        
        return $jsString;   
    }

    /**
    * makeJS - using a list of fields given, do a SQL lookup to get data from previous records to build a dropdown list to select from in the field for a record.
    */
    public function makeJS($startup_vars = '')
    {
        global $Proj;

        $nl = "\n";
        $html = '';
        
        // find the correct data table for the project
        $dataTable = method_exists('\REDCap', 'getDataTable') ? REDCap::getDataTable($Proj->project_id) : 'redcap_data';
        
        $html .=  "<script type='text/javascript'>";
        
        foreach($startup_vars as $field => $details) {        
            $field_tags = '';
        
            $field_type = $Proj->metadata[$field]['element_type'];
            
            if (strtolower(trim($field_type)) == 'text') {

                $sqlParams[] = db_escape($Proj->project_id); // PROJECT ID
                $sqlParams[] = strip_tags($field);

                // select value as value from redcap_data2 where project_id=? and field_name='?' group by value order by value;
                //                
                $recordSql = 'SELECT value AS value FROM ' . $dataTable . ' WHERE project_id = ? AND field_name = ? GROUP BY VALUE ORDER BY VALUE;';
                
                $queryResult = $this->sqlQueryAndExecute($recordSql, $sqlParams);
                                
                while ($row = $queryResult->fetch_assoc()) {                    
                    if (strlen(trim(strip_tags($row['value']))) > 0) {
                        $field_tags .= ',"' . $row['value'] . '"';
                    }
                }
                
                unset($sqlParams); // clear the params
            }
            
            if (strlen($field_tags) > 0) {
                
                $field_tags = substr($field_tags, 1);
                
                // Only do this if there is some data in the field
                $html .=  "$(document).ready(function() {
                        var tags$field = [$field_tags];
                        $( $(\"[name = '$field']\") ).autocomplete({
                                autoFocus: true,
                                source: tags$field,
                        });
                        
                        // Handle TAB key to select the first item
                        $( $(\"[name = '$field']\") ).keydown( function(e) {
                                if( e.keyCode != $.ui.keyCode.TAB) return; 
                                  
                                 e.keyCode = $.ui.keyCode.DOWN;
                                 $(this).trigger(e);
                              
                                 e.keyCode = $.ui.keyCode.ENTER;
                                 $(this).trigger(e);
                                  
                                 $(this).siblings(\"input\").select();
                        });
                });";
            }
        }  // end foreach startup_vars
        
        $html .= '</script>';
        $html .= $nl;         
        
        $html .= '';
        
        return $html;
    }

    /**
    * emlogging - logging.
    */
    public function emlogging($msg)
    {
        if ($this->debug_mode_log_project) {
            if ($msg) {
                $this->log($msg);
            }
        }
    }

    /**
     * sqlQueryAndExecute - encapsulate some of the repeative details.  pass one param or many params.
     */
    private function sqlQueryAndExecute($sql, $params = null)
    {
        $queryResult = null;
        
        try {
            $query = ExternalModules::createQuery();
            
            $this->queryHandle = $query;
            
            if ($params == null) {
                $this->emlogging('ERROR: NO Params: ' . $sql);
                return null;
            }
            
            $query->add($sql, $params);
            
            $queryResult = $query->execute();
        } 
        catch (Throwable $e) {
            $this->emlogging('ERROR: ' . $sql . ' err:' . $e->__toString());
        }

        return $queryResult;
    }
        
    /**
    * testMethod - USE ONLY IN DEVELOPMENT and retained for any future DEV effort. A simple test method to show the JS code produced.
    */
    public function testMethod($pid, $inst)
    {
        $this->debug_mode_log_project = $this->getProjectSetting('debug_mode_log_project');
        
        $msg = 'TEST: Pid = [' . $pid . ']' . ' Form = [' . $inst . ']';
        $this->emlogging($msg);
        
        $js = $this->buildJs($pid, $inst);
        
        echo $js;    
    }


    // **********************************************************************   
    // **********************************************************************   
    // **********************************************************************
    
} // *** end class

?>