Skip to content

Commit

Permalink
Merge pull request #12 from lsgs/dev
Browse files Browse the repository at this point in the history 
Dev from CTSI
  • Loading branch information
@lsgs
lsgs authored May 7, 2021
2 parents edc55a8 + 71356de commit 3e404b7
Show file tree
Hide file tree
Showing 5 changed files with 145 additions and 58 deletions.
36 changes: 36 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Change Log
All notable changes to the Record Autonumbering module will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).


## [0.0.503] - 2021-04-20
### Added
- Add Taryn Stoff's user guide to README (Kyle Chesney)


## [0.0.502] - 2021-03-22
### Added
- Revise module description in config.json to align with README (Philip Chase)
- Update README based on Taryn Stoff's user guide (Kyle Chesney, Taryn Stoffs)
- Fix DAG form-save bug (mbentz)
- Fix crash of module when using "padded integer increment with prefix" caused by abstract method getRequiredDataEntryFields needing declaration (Kyle Chesney)
- Ensure module is enabled before initializing to prevent REDCap core's autonumbering enabling in *every* project (Kyle Chesney)


## [0.0.501] - 2020-12-09
### Added
- Redirect with js (Luke)


## [0.0.301] - 2019-05-23
### Added
- Update our repository with luke's 0.0.3 changes, namely, record_autonumber_v0.0.3 (Luke)


## [0.0.101] - 2019-04-19
### Summary
- This is the first release.

### Added
- Remove default value for project-setup-dialog-text (Philip Chase)
- Initial commit (Luke)
44 changes: 35 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,39 @@
********************************************************************************
# Record Autonumber
# Custom Record Auto-Numbering

Luke Stevens, Murdoch Children's Research Institute https://www.mcri.edu.au
This module allows users to create a custom record auto-numbering schema for their REDCap project. This works during data entry but not in public surveys or API/CSV data import.

********************************************************************************
## Summary
## Motivation

Various configurable and extensible options for record auto-numbering.
Applies to records created by a logged in user, i.e. not via a public survey or
API/CSV data import.
Normal REDCap behavior dictates that having auto-numbering enabled in a project makes the first record created have a record ID of 1, the second record created have an ID of 2, the third record created have a record ID of 3, and so on. If the project is using DAGs (Data Entry Groups), having auto-numbering enabled will automatically have its record name prepended with the Group ID (DAG ID) number and a dash/hyphen. For example, the first three records IDs created for DAG ID 98 will get automatically named 98-1, 98-2, and 98-3.

********************************************************************************
This module introduces a range of additional options, such as having the first record ID created start at 1000 or 001 instead of 1, append all record IDs with a prefix (ABC-1, ABC-2, ABC-3, etc.), or having the DAG name appear in the record ID (UF-1, UF-2, UF-3) instead of the DAG ID (98-1, 98-2, 98-3, etc.) when utilizing DAGs in a project.

## Limitations

- The custom record auto-numbering system only applies to records *created* by a logged-in user, i.e. not via a public survey or API/CSV data import.

- The module works best when enabled and configured *before* the first record has been created in the project, especially when using options 1, 2 or 3 listed below.

- This module will *not* automatically convert existing records to the project's newly defined record ID schema; it only applies to *new* records that are created, by a logged-in user, once the module is enabled.

## Project Configuration

1. **Integer increment from a specified start value**: This option allows users to specify the first numerical record ID. Subsequent record IDs will increment from this project-wide (even for users in a DAG).
- This is useful when you want your first record ID to start with any integer besides 1, including padding the 1 to become 001.

1. **Padded integer increment with prefix**: This option allows users to specify a prefix to the project's record IDs and configure the padding length, prepending the ID with zeros to achieve the desired length. Subsequent record IDs will increment from this project-wide (even for users in a DAG).
- This is useful when you want you need to create study-specific record IDs, such as ABC-001, ABC-002, ABC-003, etc.

1. **Increment within DAG using part of the DAG name**: This option lets users create a DAG-specific prefix to the record IDs in the project, when DAGs are used in a project. This option gives users the ability to use 1-5 characters from the beginning or the end of the DAG as part of the record ID.
- This is useful when you need to create DAG-specific record IDs, such as UFL-1, UFL-2, UW-1, UW-2, USF-1, USF-2, etc.
- _Useful tip_: if you want the prefixed DAG ID to be "UFL" you can name the DAG "University of Florida UFL" and specify you want the last 3 letters of the DAG name to be used in the prefix.

1. **Date/time in selected format**: This option will create a record ID based upon the date and time a record was created.
- _Note_: Since dates are PHI, do not use this option if all data is supposed to be de-identified.

1. **Unix timestamp (16 digits)**: This option will create a record ID based upon a Unix timestamp. A Unix timestamp is the number of seconds since January 1st, 1970 (UTC).
- See: <https://www.unixtimestamp.com/> for more information about Unix timestamps.

1. **A project-specific custom auto-numbering schema**: The module design supports the addition of novel auto-numbering schemes via custom code. This is an advanced feature for module developers.

For a more detailed explanation, see the [Custom Record Auto-numbering User Guide](https://www.ctsi.ufl.edu/wordpress/files/2021/04/Custom-Record-Auto-numbering-External-Module-User-Guide.pdf) created by Taryn Stoffs.
107 changes: 65 additions & 42 deletions RecordAutonumber.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,48 +54,51 @@ public function __construct() {
$this->autonumberGenerator = null;

if ($this->project_id > 0) {
// Do not attempt any configuration unless the module is enabled
if (!$this->getProjectSettings()['enabled']['value']) return;
// read all the config options
$settingsArray = $this->getProjectSettings($this->project_id);

// only create object when module is actually enabled for project!
if (!$settingsArray['enabled']['value']) return;

try {
// read all the config options
$settingsArray = $this->getProjectSettings($this->project_id);

if ($settingsArray['enabled']['value']) { // only create object when module is actually enabled for project!
$autonumberClassName = '';
foreach ($settingsArray as $settingKey => $settingValues) {
if ($settingKey==='autonumber-option') {
$autonumberClassName = $settingValues['value'];
} else if (strpos($settingKey, 'option-setting-')===0) {
$autonumberSettings[$settingKey] = $settingValues['value'];
}
}

if ($autonumberClassName==='Custom') {
$autonumberClassName = $autonumberSettings['option-setting-custom-class-name'];
unset($autonumberSettings['option-setting-custom-class-name']);
$autonumberClassName = '';
foreach ($settingsArray as $settingKey => $settingValues) {
if ($settingKey==='autonumber-option') {
$autonumberClassName = $settingValues['value'];
} else if (strpos($settingKey, 'option-setting-')===0) {
$autonumberSettings[$settingKey] = $settingValues['value'];
}
}

if ($autonumberClassName!=='') { // ... and is configured
$this->autonumberGenerator = AutonumberGeneratorFactory::make(
$autonumberClassName,
$autonumberSettings
);
}
} else {
// not enabled - currently enabling so ensure project setting is autonumbering
$sql = "update redcap_projects set auto_inc_set=1 where auto_inc_set=0 and project_id=".db_escape($this->project_id);
$q = db_query($sql);
// if (db_affected_rows()==1) {
$nrows = db_affected_rows();
if ($nrows==1) {
\Logging::logEvent($sql,"redcap_projects","MANAGE",$this->project_id,"project_id = $this->project_id","Modify project settings");
}
if ($autonumberClassName==='Custom') {
$autonumberClassName = $autonumberSettings['option-setting-custom-class-name'];
unset($autonumberSettings['option-setting-custom-class-name']);
}

if ($autonumberClassName!=='') { // ... and is configured
$this->autonumberGenerator = AutonumberGeneratorFactory::make(
$autonumberClassName,
$autonumberSettings
);
}
} catch (AutonumberConfigException $e) {
$this->setCrossPageMessage($e->getMessage());
}
}
}

function redcap_module_project_enable($version, $project_id) {
// Turn record autonumbering on if it is not already on
if (!$Proj->project['auto_inc_set']) {
$sql = "update redcap_projects set auto_inc_set=1 where auto_inc_set=0 and project_id=".db_escape($project_id);
$q = db_query($sql);
$nrows = db_affected_rows();
if ($nrows==1) {
\Logging::logEvent($sql,"redcap_projects","MANAGE",$project_id,"project_id = $project_id","Modify project settings");
}
}
}

/**
* redcap_every_page_top
Expand Down Expand Up @@ -168,6 +171,19 @@ public function redcap_every_page_before_render($project_id) {
}

}
else if ($this->page==='DataEntry/record_home.php' && isset($_GET['id']) && isset($_GET['auto'])) {

if (isset($_GET['arm']) && array_key_exists($_GET['arm'], $this->Proj->events)) {
$armFirstEventId = key($this->Proj->events[$_GET['arm']]['events']);
$armFirstForm = $this->Proj->eventsForms[$armFirstEventId][0];
} else {
$armFirstEventId = $this->Proj->firstEventId;
$armFirstForm = $this->Proj->firstForm;
}
$tempRecId = $_GET['id'];
$gotoUrl = APP_PATH_WEBROOT."DataEntry/index.php?pid={$this->project_id}&id=$tempRecId&event_id=$armFirstEventId&page=$armFirstForm";
redirect( $gotoUrl);
}
}

protected function handleAutonumberException($postRec, $msg) {
Expand Down Expand Up @@ -342,6 +358,7 @@ protected function includeRequiredFieldsCheck($requiredFieldList) {
<script type='text/javascript'>
(function() {
var requiredFields = JSON.parse('<?php echo json_encode($requiredFields);?>');
var attachedListeners = false;

// Check required fields are set (alert and stop if not) before saving
var customSaveForm = function (sendOb) {
Expand Down Expand Up @@ -370,16 +387,22 @@ protected function includeRequiredFieldsCheck($requiredFieldList) {


$(window).on('load', function() {
// Adjust the Save button click events
var saveBtns = $('#__SUBMITBUTTONS__-div [id^=submit-btn-save], #formSaveTip [id^=submit-btn-save]');
$.each(saveBtns, function ( btnIndex, thisBtn ) {
// Alter the onclick event of the button to our custom save function
$(thisBtn).onclick = null;
$(thisBtn).removeAttr('onclick').prop('onclick', null).off('click'); // make sure!
$(thisBtn).click(function() {
customSaveForm(thisBtn);
return false;
});
$('#center').on('mousemove', function() {
// Adjust the Save button click events
if (!attachedListeners) {
attachedListeners = true;
var saveBtns = $('#__SUBMITBUTTONS__-div [id^=submit-btn-save], #formSaveTip [id^=submit-btn-save]');
$.each(saveBtns, function ( btnIndex, thisBtn ) {
// Alter the onclick event of the button to our custom save function
$(thisBtn).onclick = null;
// .off disables any click event listeners
$(thisBtn).removeAttr('onclick').prop('onclick', null).off('click');
$(thisBtn).click(function() {
customSaveForm(thisBtn);
return false;
});
});
}
});
});
}());
Expand Down
1 change: 1 addition & 0 deletions VERSION
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0.0.503
15 changes: 8 additions & 7 deletions config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,18 @@
}
],

"description": "Various configurable and extensible options for record auto-numbering. Applies to records created by a logged in user, i.e. not via a public survey or API/CSV data import.",
"description": "Allows users to create a custom record auto-numbering schema for their REDCap project. This works during data entry but not in public surveys or API/CSV data import.",

"permissions": [
"redcap_add_edit_records_page",
"redcap_data_entry_form_top",
"redcap_every_page_before_render",
"redcap_every_page_top",
"redcap_save_record"
"redcap_add_edit_records_page",
"redcap_data_entry_form_top",
"redcap_every_page_before_render",
"redcap_every_page_top",
"redcap_save_record",
"redcap_module_project_enable"
],

"enable-every-page-hooks-on-system-pages": false,
"enable-every-page-hooks-on-system-pages": false,

"links": {
},
Expand Down

0 comments on commit 3e404b7

Please sign in to comment.