{"id":19713359,"url":"https://github.com/ctsit/data_driven_project_banner","last_synced_at":"2025-04-29T18:31:10.038Z","repository":{"id":49628852,"uuid":"190222172","full_name":"ctsit/data_driven_project_banner","owner":"ctsit","description":"A REDCap Module designed to display a data-driven banner at the top of the Project Home and Project Setup tabs","archived":false,"fork":false,"pushed_at":"2024-07-23T18:50:26.000Z","size":81,"stargazers_count":1,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-05T18:53:58.389Z","etag":null,"topics":["redcap","redcap-external-module","redcap-repo"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ctsit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-04T14:51:34.000Z","updated_at":"2024-07-23T18:50:29.000Z","dependencies_parsed_at":"2024-07-23T21:54:41.084Z","dependency_job_id":null,"html_url":"https://github.com/ctsit/data_driven_project_banner","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fdata_driven_project_banner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fdata_driven_project_banner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fdata_driven_project_banner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fdata_driven_project_banner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctsit","download_url":"https://codeload.github.com/ctsit/data_driven_project_banner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251559852,"owners_count":21609088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["redcap","redcap-external-module","redcap-repo"],"created_at":"2024-11-11T22:21:13.738Z","updated_at":"2025-04-29T18:31:09.782Z","avatar_url":"https://github.com/ctsit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Data Driven Project Banner\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3561124.svg)](https://doi.org/10.5281/zenodo.3561124)\n\n\nA REDCap Module designed to display banners at the top of select project pages. Supports the data piping of query results into the banner text.\n\nPlease see the [CHANGELOG](CHANGELOG.md) to learn about changes and bugfixes. Version 3.0.0 introduces **breaking** changes.\n\n\u003e **Important:** Version 3.0.0 introduces a new feature, **Multiple Banners**. This feature allows for the display of multiple banners on a single project. This change is **breaking** and will require reconfiguration of the module if you are upgrading from a previous version (Please see the [Migration Help](#migration-from-2xx-to-300) for more information). If you are new to the module you can ignore the migration help.\n\n## Prerequisites\n- REDCap \u003e= 14.0.2\n\n## Easy Installation\n- Obtain this module from the Consortium [REDCap Repo](https://redcap.vanderbilt.edu/consortium/modules/index.php) from the REDCap Control Center.\n\n## Manual Installation\n- Clone this repo into `\u003credcap-root\u003e/modules/data_driven_project_banner_v0.0.0`.\n\n## Global Configuration\n\n\u003eDue to know [issues](https://redcap.vumc.org/community/post.php?id=90452\u0026comment=90466) in REDCap with use of branchingLogic in system-settings with repeatable items, we have opted not to use the branching logic and provide all configuration options at a time.\n\nYou now have the option to have multiple banners on a single project. To have more than one banner click on the plus sign by the banner settings. This will add a new set of configuration options for a new banner. You can add as many banners as you like.\n\nTypically, this module should be enabled on all projects after it has been configured.  All configuration options are at the system-level.\n\n### Multi Row Response\n\nCheck this option, If you expect your query to return multiple rows. Doing so will add the text from two additional fields: **Banner Top Text** and **Banner Bottom Text** to the banner. These fields will appear before and after the Banner Text, respectively, and do not support data piping.\n\n\u003e *The configuration now will have the Banner Top Text and Banner Bottom Text fields visible at all times, but they will only be used if the Multi Row Response option is checked.*\n\n### Banner Text\n\nProvide the text you would like displayed in the project banner. This field supports HTML formatted text. If you do not configure this value, you will get the default project banner:\n\n```\nThis is the default project banner. Change this in the system level\nmodule configuration for the Data Driven Project Banner module.\n```\n\nThe banner text field also supports data piping akin to REDCap Smart Variables, (i.e. `[project_id]` will return the value stored for project id). That said, this module uses its _own_ set of replacement fields. The variables available for replacement are the column names in the response to the SQL query specified in the [**Custom SQL for data**](#custom-sql-for-data) configuration option. \n\n**Note:** This block will be repeated for _every row returned by the query_. If your [**Custom SQL for data**](#custom-sql-for-data) query is expected to return multiple rows, use the fields provided by **Multi Row Response**.\n\n\n### Banner Colors\n\nYou have the option to customize the banner colors. From a color picker, select a color for the background and border of the banner.\n\n\n### Criteria for display\n\nFrom a dropdown menu, choose how the banner should be displayed. There are three options:\n\n- **Always display**: Always display the banner. \n\n  *Note that if the SQL query in [**Custom SQL for data**](#custom-sql-for-data) fails, the banner may still be displayed, but without the intended data piping. If a query result is _required_ to display the banner, select _Require a non-empty query result_.*\n- **Require a non-empty query result**: Display the banner _only_ if the query from [**Custom SQL for data**](#custom-sql-for-data) returns results. Useful for banners utilizing data piping fields.\n- **Custom query**: This advanced option allows you to create your own query in a new field titled **Custom SQL for criteria**; the banner will only be displayed if the result of your query is not empty.\n  - **Custom SQL for criteria**: This text field spawns when **Custom query** is selected, use this field to create your SQL statement. The `SELECT` keyword is automatically prepended to queries for you as your queries should all be `SELECT` statements. A simple example may be `* FROM redcap_data WHERE project_id = [project_id]`, which will cause the banner to only appear on projects which have data.\n    - Any reference to `[project_id]` in these queries will be replaced with the current Project ID. That is the only substitution made to the query string.\n\n  \u003e The **_Custom SQL for criteria_** field will always be visible in the configuration page, but will only be used if the **Criteria for display** is set to **Custom query**.\n\n### Custom SQL for data\n\nCreate your own SQL query to provide data. This field behaves similarly to the **Custom SQL for criteria** option for **Criteria for display**: it prepends `SELECT` to your queries and allows piping of `[project_id]` into the query.\nA basic example you may find useful is `* FROM redcap_projects WHERE project_id = [project_id]` which returns the information for the project in which the banner is displayed. This field will always be visible in the configuration page, but wil only be used if the **Criteria for display** is set to \n\n### Display on all pages\n\nCheck this option to display the banner on all pages in the project. If unchecked, the banner will only be displayed on the project home page and the project setup page.\n\n### Data piping fields\n\nIf you use the suggested query in [**Custom SQL for data**](#Custom-SQL-for-data), there are over 110 possible column names to choose from when data piping. These columns are probably the most interesting for data piping:\n\n```\nproject_id\napp_title\nproject_contact_name\nproject_contact_email\nproject_pi_firstname\nproject_pi_mi\nproject_pi_lastname\nproject_pi_email\nproject_pi_alias\nproject_pi_username\nproject_pi_pub_exclude\nproject_pub_matching_institution\nproject_irb_number\nproject_grant_number\n```\n\n\n### Migration from 2.X.X to 3.0.0\nIf you are upgrading from a version prior to 3.0.0, you will need to reconfigure your banner. To make this easier, we have a MySQL query that will help you migrate your current banner to the new configuration format. Your administrator will need to run this query on the REDCap database.\n\n\n```sql\nSTART TRANSACTION;\nSET @module_id = (\n    SELECT external_module_id\n    FROM redcap_external_modules\n    WHERE directory_prefix = 'data_driven_project_banner'\n);\n\nUPDATE redcap_external_module_settings\nSET \n    type = 'json-array',\n    value = CASE\n        WHEN `key` IN ('multi_row_response', 'display_everywhere') THEN\n            CASE \n                WHEN value IS NULL THEN '[]'\n                WHEN LOWER(value) = 'true' THEN '[true]'\n                WHEN LOWER(value) = 'false' THEN '[false]'\n                ELSE CONCAT('[', LOWER(value), ']')\n            END\n        ELSE\n            CASE \n                WHEN value IS NULL THEN '[]'\n                ELSE JSON_ARRAY(value)\n            END\n    END\nWHERE \n    external_module_id = @module_id\n    AND `key` IN (\n        'banner_settings', 'multi_row_response', 'banner_text_top', 'banner_text', \n        'banner_text_bottom', 'bg_color', 'border_color', 'criteria', \n        'custom_criteria_sql', 'custom_data_sql', 'display_everywhere'\n    );\nCOMMIT;\n```\n\n\u003e **Note:**\nThis query requires MySQL 8.0 or later. \n\nIf you run this query shortly before upgrading Data Driven Project Banner, the migrated settings will be in place for the module upgrade. The module will start working correctly immediately. We **strongly** recommend you run this query before upgrading the module.\n\nThe query should be run in against the MySQL database of your REDCap instance. After running the query, you should see a message saying that some rows were inserted. The module will start working immediately. In the project home page go to the **External Module \u003e Manage** and click on the Data Driven Project Banner configure button. You should see your banner migrated to the new configuration format and you should be able to see the existing banner on the project home page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fdata_driven_project_banner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctsit%2Fdata_driven_project_banner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fdata_driven_project_banner/lists"}