{"id":19713416,"url":"https://github.com/ctsit/redcap_chart_field","last_synced_at":"2025-07-11T03:33:25.370Z","repository":{"id":79003824,"uuid":"124607206","full_name":"ctsit/redcap_chart_field","owner":"ctsit","description":null,"archived":false,"fork":false,"pushed_at":"2020-02-04T16:25:58.000Z","size":671,"stargazers_count":2,"open_issues_count":9,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-29T18:49:39.040Z","etag":null,"topics":["redcap","redcap-external-module","redcap-repo"],"latest_commit_sha":null,"homepage":null,"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":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-10T00:22:06.000Z","updated_at":"2023-05-19T17:24:38.000Z","dependencies_parsed_at":"2023-04-08T06:16:48.037Z","dependency_job_id":null,"html_url":"https://github.com/ctsit/redcap_chart_field","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ctsit/redcap_chart_field","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_chart_field","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_chart_field/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_chart_field/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_chart_field/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctsit","download_url":"https://codeload.github.com/ctsit/redcap_chart_field/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctsit%2Fredcap_chart_field/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264721541,"owners_count":23653949,"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:22:04.785Z","updated_at":"2025-07-11T03:33:25.340Z","avatar_url":"https://github.com/ctsit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# REDCap Chart Field\nProvides a chart drawing feature for data entries and surveys. Integrates REDCap with third-party chart libraries - currently [Charts.js](http://www.chartjs.org/) and [Chartist](https://gionkunz.github.io/chartist-js/) are supported. [Piping](https://redcap.vanderbilt.edu/redcap_v5.5.0/DataEntry/piping_explanation.php) can be used on field configuration, so charts may display facts to survey participants based on their previous answers.\n\n## Prerequisites\n- REDCap \u003e= 8.0.3\n\n## Installation\n- Clone this repo into `\u003credcap-root\u003e/modules/redcap_chart_field_v\u003cversion_number\u003e`.\n- Go to **Control Center \u003e Manage External Modules** and enable REDCap Chart Field.\n\n## Choosing your chart library\nTwo amazing third-party chart libraries are supported by this module - Chart.js and Chartist.\n\n![Configuration screen](img/config_screen.png)\n\n## Setting up a chart field (Chart.js example)\nThis section will walk you through a few steps to setup a [Charts.js](http://www.chartjs.org/) chart, dynamically populated via [Piping](https://redcap.vanderbilt.edu/redcap_v5.5.0/DataEntry/piping_explanation.php).\n\n### 1. Setting up source data (for Piping purposes)\n\nThe following fields will be used to provide data to populate our chart example. Note the variable names - they will be referenced later on.\n\n![Chart.js source data configuration](img/chart_source_data_config.png)\n\nTo configure a chart it helps to have data in the input fields.  For this example we'll use the data shown here.\n\n![Chart.js source data](img/chart_source_data.png)\n\n### 2. Creating a chart field\nTo create a chart field, access Online Designer's field creation modal, and then select _Descriptive Text_. You may see a checkbox named _Is chart_.\n\n![Field type](img/field_type.png)\n\n### 3. Mapping an example provided by the selected third-party library\nOnce you click on _Is chart_ checkbox, a few extra fields are shown:\n\n![Chart.js configuration](img/chartjs_config_empty.png)\n\nTo fill these fields out it is very important to get familiar with the documentation provided by the third-party chart library you chose. The inputs are expected to be Javascript objects that follow a particular structure defined by the library. The better you understand the configuration syntax the richer your charts can be.\n\nThough this sounds very technical, no software development skills are required to manipulate these parameters. For most of cases you need only copy \u0026 paste a suitable example from documentation.  Then make slight changes to adapt it to your needs.\n\nLet's create a _bar_ chart by using [the main example from Chart.js official documentation](http://www.chartjs.org/docs/latest/#creating-a-chart) as base.\n\n\u003cdetails\u003e\u003csummary\u003eClick to see the code provided by Chart.js website\u003c/summary\u003e\n\n``` html\n\u003ccanvas id=\"myChart\" width=\"400\" height=\"400\"\u003e\u003c/canvas\u003e\n\u003cscript\u003e\nvar ctx = document.getElementById(\"myChart\").getContext('2d');\nvar myChart = new Chart(ctx, {\n    type: 'bar',\n    data: {\n        labels: [\"Red\", \"Blue\", \"Yellow\", \"Green\", \"Purple\", \"Orange\"],\n        datasets: [{\n            label: '# of Votes',\n            data: [12, 19, 3, 5, 2, 3],\n            backgroundColor: [\n                'rgba(255, 99, 132, 0.2)',\n                'rgba(54, 162, 235, 0.2)',\n                'rgba(255, 206, 86, 0.2)',\n                'rgba(75, 192, 192, 0.2)',\n                'rgba(153, 102, 255, 0.2)',\n                'rgba(255, 159, 64, 0.2)'\n            ],\n            borderColor: [\n                'rgba(255,99,132,1)',\n                'rgba(54, 162, 235, 1)',\n                'rgba(255, 206, 86, 1)',\n                'rgba(75, 192, 192, 1)',\n                'rgba(153, 102, 255, 1)',\n                'rgba(255, 159, 64, 1)'\n            ],\n            borderWidth: 1\n        }]\n    },\n    options: {\n        scales: {\n            yAxes: [{\n                ticks: {\n                    beginAtZero:true\n                }\n            }]\n        }\n    }\n});\n\u003c/script\u003e\n```\n\n\u003c/details\u003e\n\u0026nbsp;\n\nNote the sections above labeled _type_, _data_, and _options_.  Those map to the REDCap Chart Field properties _Chart type_, _Chart data_, and _Chart options_, respectively. The _canvas\\_width_ and _canvas\\_height_ fields map to the _Chart width_ and _Chart height_ REDCap Chart Field properties.\n\n__1. Type:__ Bar\n\u003cbr\u003e\n__2. Data:__\n\n``` javascript\n{\n    labels: [\"Red\", \"Blue\", \"Yellow\", \"Green\", \"Purple\", \"Orange\"],\n    datasets: [{\n        label: '# of Votes',\n        data: [12, 19, 3, 5, 2, 3],\n        backgroundColor: [\n            'rgba(255, 99, 132, 0.2)',\n            'rgba(54, 162, 235, 0.2)',\n            'rgba(255, 206, 86, 0.2)',\n            'rgba(75, 192, 192, 0.2)',\n            'rgba(153, 102, 255, 0.2)',\n            'rgba(255, 159, 64, 0.2)'\n        ],\n        borderColor: [\n            'rgba(255,99,132,1)',\n            'rgba(54, 162, 235, 1)',\n            'rgba(255, 206, 86, 1)',\n            'rgba(75, 192, 192, 1)',\n            'rgba(153, 102, 255, 1)',\n            'rgba(255, 159, 64, 1)'\n        ],\n        borderWidth: 1\n    }]\n}\n```\n\n__3. Options:__\n\n``` javascript\n{\n    scales: {\n        yAxes: [{\n            ticks: {\n                beginAtZero:true\n            }\n        }]\n    }\n}\n```\n\n__4. Canvas width:__ 400\n\u003cbr\u003e\n__5. Canvas height:__ 400\n\n\n### 4. Setting up chart properties\n\nHere's how those values look pasted into the REDCap Chart Field properties.\n\n![Chartjs configuration](img/chartjs_config.png)\n\nNote the highlighted area on image above - Piping is being used in order to dynamically populate the chart data (`[data_1]`, `[data_2]`, etc) - so each record entry or survey has its own chart results.\n\nObs.: as the example above, Piping wildcards must be used between quotes (single or double), e.g. `'[data_1]'`.\n\nNote also that piping data from a REDCap field is optional. You could present a chart with static data or use a mix of static and piped data.\n\n### 5. The result\nFor this particular case - recall the input given on [Chart source data section](#chart-source-data-for-piping-purposes) - we have the following result chart when accessing the field in a survey:\n\n![Chartjs chart](img/chartjs_chart.png)\n\n## Analogous example using Chartist\nIn this section we will go through the analogous example for Chartist library, using the same source data. This time we'll draw a _line_ chart.\n\nThe process of mapping a [Chartist example](https://gionkunz.github.io/chartist-js/#responsive-charts-configuration) is  similar to the previous section on Chart.js\n\n\u003cdetails\u003e\u003csummary\u003eClick to see the code provided by Chartist website\u003c/summary\u003e\n\n``` javascript\n/* Add a basic data series with six labels and values */\nvar data = {\n  labels: ['1', '2', '3', '4', '5', '6'],\n  series: [\n    {\n      data: [1, 2, 3, 5, 8, 13]\n    }\n  ]\n};\n\n/* Set some base options (settings will override the default settings in Chartist.js *see default settings*). We are adding a basic label interpolation function for the xAxis labels. */\nvar options = {\n  axisX: {\n    labelInterpolationFnc: function(value) {\n      return 'Calendar Week ' + value;\n    }\n  }\n};\n\n/* Now we can specify multiple responsive settings that will override the base settings based on order and if the media queries match. In this example we are changing the visibility of dots and lines as well as use different label interpolations for space reasons. */\nvar responsiveOptions = [\n  ['screen and (min-width: 641px) and (max-width: 1024px)', {\n    showPoint: false,\n    axisX: {\n      labelInterpolationFnc: function(value) {\n        return 'Week ' + value;\n      }\n    }\n  }],\n  ['screen and (max-width: 640px)', {\n    showLine: false,\n    axisX: {\n      labelInterpolationFnc: function(value) {\n        return 'W' + value;\n      }\n    }\n  }]\n];\n\n/* Initialize the chart with the above settings */\nnew Chartist.Line('#my-chart', data, options, responsiveOptions);\n```\n\n\u003c/details\u003e\n\u0026nbsp;\n\nAgain, __you don't need to be a developer__ to manipulate this information.  You need only to copy and paste the correct sections of some example code into the appropriate form fields and make some minor edits:\n\n__1. Type:__ Line\n\u003cbr\u003e\n__2. Data:__\n\n``` javascript\n{\n  labels: ['1', '2', '3', '4', '5', '6'],\n  series: [\n    {\n      data: [1, 2, 3, 5, 8, 13]\n    }\n  ]\n}\n```\n\n__3. Options:__\n\n``` javascript\n{\n  axisX: {\n    labelInterpolationFnc: function(value) {\n      return 'Calendar Week ' + value;\n    }\n  }\n}\n```\n\n__3. Responsive options:__\n\n``` javascript\n[\n  ['screen and (min-width: 641px) and (max-width: 1024px)', {\n    showPoint: false,\n    axisX: {\n      labelInterpolationFnc: function(value) {\n        return 'Week ' + value;\n      }\n    }\n  }],\n  ['screen and (max-width: 640px)', {\n    showLine: false,\n    axisX: {\n      labelInterpolationFnc: function(value) {\n        return 'W' + value;\n      }\n    }\n  }]\n]\n```\n\n### Filling out the form:\n\n![Chartist configuration](img/chartist_config.png)\n\nAs we've done on Chart.js section, we are using Piping to make chart data dynamic.\n\nNote that the configuration for Chartist is slightly different - there are no canvas dimension fields, and _Chart responsive options_ field is added. Check the [official Chartist documentation](https://gionkunz.github.io/chartist-js/) to understand how it works.\n\nIn our example, width and height are specified to the __Chart options__ field to show that is also possible to define chart dimensions with Chartist.\n\n### The Result\n\nHere is a line chart drawn using Chartist\n\n![Chartist line chart](img/chartist_chart.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fredcap_chart_field","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctsit%2Fredcap_chart_field","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctsit%2Fredcap_chart_field/lists"}