{"id":18038845,"url":"https://github.com/matthisk/django-jchart","last_synced_at":"2025-04-09T18:18:01.348Z","repository":{"id":57420520,"uuid":"79930708","full_name":"matthisk/django-jchart","owner":"matthisk","description":"📈 A Django package for plotting charts using the excellent Chart.JS library.","archived":false,"fork":false,"pushed_at":"2020-07-30T09:32:35.000Z","size":77,"stargazers_count":121,"open_issues_count":13,"forks_count":24,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-01T05:22:27.606Z","etag":null,"topics":["chart","charting-library","chartjs","django"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matthisk.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}},"created_at":"2017-01-24T16:36:44.000Z","updated_at":"2024-03-04T22:06:59.000Z","dependencies_parsed_at":"2022-09-16T09:22:09.310Z","dependency_job_id":null,"html_url":"https://github.com/matthisk/django-jchart","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthisk%2Fdjango-jchart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthisk%2Fdjango-jchart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthisk%2Fdjango-jchart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthisk%2Fdjango-jchart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthisk","download_url":"https://codeload.github.com/matthisk/django-jchart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085328,"owners_count":21045139,"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":["chart","charting-library","chartjs","django"],"created_at":"2024-10-30T14:06:36.417Z","updated_at":"2025-04-09T18:18:01.320Z","avatar_url":"https://github.com/matthisk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-jchart\n\n[![Build Status](https://travis-ci.org/matthisk/django-jchart.svg?branch=master)](https://travis-ci.org/matthisk/django-jchart) [![Coverage Status](https://coveralls.io/repos/github/matthisk/django-jchart/badge.svg?branch=master)](https://coveralls.io/github/matthisk/django-jchart?branch=master)\n[![PyPI version](https://badge.fury.io/py/django-jchart.svg)](https://badge.fury.io/py/django-jchart)\n\nThis Django app enables you to configure and render \u003ca href=\"http://www.chartjs.org/\"\u003eChart.JS\u003c/a\u003e charts directly from your Django codebase. Charts can than either be rendered directly into your Django template or served asynchronously to the webbrowser.\n\n- Authors: Matthisk Heimensen\n- Licence: BSD\n- Compatibility: Django 1.5+, python2.7 up to python3.5\n- Project URL: https://github.com/matthisk/django-jchart\n\n### Getting Started\n\ninstall ``django-jchart``\n\n```\npip install django-jchart\n```\n\nAdd ``django-jchart`` to your installed apps.\n\n```\nINSTALLED_APPS = (\n    '...',\n    'jchart',\n)\n```\n\n\u003cp\u003e\n    Enable template loading from app folders by adding the following property to your \u003ci\u003eTEMPLATES\u003c/i\u003e django configuration:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003eTEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'APP_DIRS': True,\n        # ...\n    }]\n\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-frontend-deps\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-frontend-deps\"\u003e\n        Frontend Dependencies\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\nFor the charts to be rendered inside the browser you will\nneed to include the Chart.JS library. Add the following\nHTML before your closing \u003ccode\u003e\u0026lt;/body\u0026gt;\u003c/code\u003e tag: \n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-html\"\u003e\u0026lt;script src=\"https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.4.0/Chart.bundle.min.js\"\u0026gt;\u0026lt;/script\u0026gt;\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\nIf you want to make use of \u003ca href=\"#async-charts\"\u003easynchronous loading charts\u003c/a\u003e\nyou will also need to include jQuery:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-html\"\u003e\u0026lt;script src=\"https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js\"\u0026gt;\u0026lt;/script\u0026gt;\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-chart-objects\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-chart-objects\"\u003e\n        The Chart Class\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\n    At the heart of this charting library lies the \u003ccode\u003eChart\u003c/code\u003e class. This class describes a chart and defines which data it should display. The chart's 'class fields' map to \u003ca href=\"http://www.chartjs.org/docs/#chart-configuration\"\u003eChart.JS options\u003c/a\u003e which describe how the chart should render and behave. By overriding the \u003ccode\u003eget_datasets\u003c/code\u003e method on your \u003ccode\u003eChart\u003c/code\u003e instance you can define which data should be displayed.\n\u003c/p\u003e\n\n\u003cp\u003e\n    To define which type of chart you want to render (e.g. a line or bar chart), your chart class should set its class field \u003ccode\u003echart_type\u003c/code\u003e to one of \"line\", \"bar\", \"radar\", \"polarArea\", \"pie\", or \"bubble\". A chart class without this field is invalid and initialization will result in an \u003ccode\u003eImproperlyConfigured\u003c/code\u003e exception.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\n\nclass LineChart(Chart):\n    chart_type = 'line'\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch5 class=\"section-title\" id=\"docs-get-datasets\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-get-datasets\"\u003e\n        get_datasets\n    \u003c/a\u003e\n\u003c/h5\u003e\n\n\u003cp\u003e\n    The \u003ccode\u003eget_datasets\u003c/code\u003e method should return a list of datasets this chart should display. Where a dataset is a dictionary with key/value configuration pairs (see the Chart.JS \u003ca href=\"http://www.chartjs.org/docs/#line-chart-dataset-structure\"\u003edocumentation\u003c/a\u003e).\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\n\nclass LineChart(Chart):\n    chart_type = 'line'\n\n    def get_datasets(self, **kwargs):\n        return [{\n            'label': \"My Dataset\",\n            'data': [69, 30, 45, 60, 55]\n        }]\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch5 class=\"section-title\" id=\"docs-get-labels\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-get-labels\"\u003e\n        get_labels\n    \u003c/a\u003e\n\u003c/h5\u003e\n\n\u003cp\u003e\n    This method allows you to set the Chart.JS \u003ccode\u003edata.labels\u003c/code\u003e parameter. Which allows you to configure \u003ca href=\"http://www.chartjs.org/docs/#scales-category-scale\"\u003ecategorical axes\u003c/a\u003e. For an example on how to use this feature see this \u003ca href=\"#pie-chart\"\u003epie chart\u003c/a\u003e.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\n\nclass PieChart(Chart):\n    chart_type = 'pie'\n\n    def get_labels(self, **kwargs):\n        return ['Red', 'Blue']\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-configuring-charts\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-configuring-charts\"\u003e\n        Configuring Charts\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\n    A chart can be configured through the following class fields:\n\u003c/p\u003e\n\n\u003cp\u003e\n        \u003ccode\u003escales\u003c/code\u003e\n        \u003ccode\u003elayout\u003c/code\u003e\n        \u003ccode\u003etitle\u003c/code\u003e\n        \u003ccode\u003elegend\u003c/code\u003e\n        \u003ccode\u003etooltips\u003c/code\u003e\n        \u003ccode\u003ehover\u003c/code\u003e\n        \u003ccode\u003eanimation\u003c/code\u003e\n        \u003ccode\u003eelements\u003c/code\u003e\n        \u003ccode\u003eresponsive\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n    All of these fields map to the same key in the Chart.JS \u003ca href=\"http://www.chartjs.org/docs/#chart-configuration-creating-a-chart-with-options\"\u003e'options' object\u003c/a\u003e. For instance, if you wanted to create a chart that does not render responsively you would set the responsive class field to false:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\n\nclass UnresponsiveLineChart(Chart):\n    chart_type = 'line'\n    responsive = False\n    # ...\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    Most of these class fields require either a list of dicitonaries or a dictionary. With the exception of \u003ccode\u003eresponsive\u003c/code\u003e which should be a boolean value. Be sure to read the Chart.JS \u003ca href=\"http://www.chartjs.org/docs/#chart-configuration-common-chart-configuration\"\u003edocumentation\u003c/a\u003e on how to use these configuration options.\n\u003c/p\u003e\n\n\u003cp\u003e\n    For your convenience there are some methods located in \u003ccode\u003ejchart.config\u003c/code\u003e which can be used to produce correct dictionaries to configure Chart.JS properties. Most of these methods only serve as a validation step for your input configuration but some can also transform their input. Let's take a look at an example, how would you configure the X-Axis so it is not to be displayed:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\nfrom jchart.config import Axes\n\nclass LineChart(Chart):\n    chart_type = 'line'\n    scales = {\n        'xAxes': [Axes(display=False)],\n    }\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    \u003ccode\u003ejchart.config\u003c/code\u003e also contains a method to create dataset configuration dictionaries. One of the advantages of using this method is that it includes a special property \u003ccode\u003ecolor\u003c/code\u003e which can be used to automatically set the values for: 'backgroundColor', 'pointBackgroundColor', 'borderColor', 'pointBorderColor', and 'pointStrokeColor'.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\nfrom jchart.config import Axes\n\nclass LineChart(Chart):\n    chart_type = 'line'\n    \n    def get_datasets(self, **kwargs):\n        return [DataSet(color=(255, 255, 255), data=[])]\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    The \u003ccode\u003ejchart.config\u003c/code\u003e module contains methods for the properties listed below. Keep in mind that you are in no way obligated to use these methods, you could also supply Python dictionaries in the place of these method calls.\n    \n    \u003ch5\u003eAvailable configuration methods:\u003c/h5\u003e\n    \u003ccode\u003eAxes\u003c/code\u003e, \u003ccode\u003eScaleLabel\u003c/code\u003e, \u003ccode\u003eTick\u003c/code\u003e, \u003ccode\u003eDataSet\u003c/code\u003e, \u003ccode\u003eTooltips\u003c/code\u003e, \u003ccode\u003eLegend\u003c/code\u003e, \u003ccode\u003eLegendLabel\u003c/code\u003e, \u003ccode\u003eTitle\u003c/code\u003e, \u003ccode\u003eHover\u003c/code\u003e, \u003ccode\u003eInteractionModes\u003c/code\u003e, \u003ccode\u003eAnimation\u003c/code\u003e, \u003ccode\u003eElement\u003c/code\u003e, \u003ccode\u003eElementArc\u003c/code\u003e, \u003ccode\u003eElementLine\u003c/code\u003e, \u003ccode\u003eElementPoint\u003c/code\u003e, \u003ccode\u003eElementRectangle\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n    \u003ch5\u003eCustom configuration options\u003c/h5\u003e\n    There is another special class field named \u003ccode\u003eoptions\u003c/code\u003e this has to be set to a dictionary and can be used to set any other Chart.JS configuration values that are not configurable through a predefined class field (e.g. \u003ccode\u003emaintainAspectRatio\u003c/code\u003e). The class fields have precedence over any configuration applied through the \u003ccode\u003eoptions\u003c/code\u003e dictionary.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\n\nclass OptionsChart(Chart):\n    chart_type = 'line'\n    options = {\n        'maintainAspectRatio': True\n    }\n    # ...\n\u003c/pre\u003e\u003c/code\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-rendering-charts\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-rendering-charts\"\u003e\n        Rendering Charts\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\n    Chart instances can be passed to your Django template context.\n    Inside the template you can invoke the method `as_html` on the\n    chart instance to render the chart.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003e# LineChart is a class inheriting from jchart.Chart\n\ndef some_view(request):\n    render(request, 'template.html', {\n        'line_chart': LineChart(),\n    })\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    The following code is an example of how to render this line chart\n    inside your html template:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003e\u0026#123;\u0026#123; line_chart.as_html \u0026#125;\u0026#125;\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-asynchronous-charts\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-asynchronous-charts\"\u003e\n        Asynchronous Charts\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\n    When rendering the chart directly into your HTML template, all the data needed for the chart is transmitted on the page's HTTP request. It is also possible to load the chart (and its required data) asynchronous.\n\u003c/p\u003e\n\n\u003cp\u003e\n    To do this we need to setup a url endpoint from which to load the chart's data. There is a classmethod available on \u003ccode\u003ejchart.views.ChartView\u003c/code\u003e to automatically create a view which exposes the chart's configuration data as JSON on a HTTP get request:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart.views import ChartView\n\n# LineChart is a class inheriting from jchart.Chart\nline_chart = LineChart()\n\nurlpatterns = [\n    url(r'^charts/line_chart/$', ChartView.from_chart(line_chart), name='line_chart'),\n]\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    You can use a custom templatetag inside your Django template to load this chart asynchronously. The custom tag behaves like the Django url templatetag and any positional or keyword arguments supplied to it are used to resolve the url for the given url name. In this example the url does not require any url parameters\n    to be resolved:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003e{\u0026#37; load jchart \u0026#37;}\n\n{\u0026#37; render_chart 'line_chart' \u0026#37;}\n\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    This tag will be expanded into the following JS/HTML code:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-html\"\u003e\u0026lt;canvas class=\"chart\" id=\"unique-chart-id\"\u0026gt;\n\u0026lt;/canvas\u0026gt;\n\n\u0026lt;script type=\"text/javascript\"\u0026gt;\nwindow.addEventListener(\"DOMContentLoaded\", function() {\n    $.get('/charts/line_chart/', function(configuration) {\n        var ctx = document.getElementById(\"unique-chart-id\").getContext(\"2d\");    \n\n        new Chart(ctx, configuration);\n    });\n});\n\u0026lt;/script\u0026gt;\u003c/code\u003e\u003c/pre\u003e\n\n\u003ch4 class=\"section-title\" id=\"docs-chart-parameterization\"\u003e\n    \u003ca class=\"fragment-link\" href=\"#docs-chart-parameterization\"\u003e\n        Chart Parameterization\n    \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp\u003e\n    It can often be useful to reuse the same chart for different datasets. This can either be done by subclassing an existing chart class and overriding its \u003ccode\u003eget_datasets\u003c/code\u003e method. But there is another way to do this. Any arguments given to the \u003ccode\u003eas_html\u003c/code\u003e method are supplied to your \u003ccode\u003eget_datasets\u003c/code\u003e method. This makes it possible to parameterize the output of \u003ccode\u003eget_datasets\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n    Let's have a look at an example. Imagine we have price point data stored in a model called \u003ccode\u003ePrice\u003c/code\u003e and this model has a field called \u003ccode\u003ecurrency_type\u003c/code\u003e. We could render the chart for different currency types by accepting the value for this field as a parameter to \u003ccode\u003eget_datasets\u003c/code\u003e.    \n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart import Chart\nfrom core.models import Price\n\nclass PriceChart(Chart):\n    chart_type = 'line'\n\n    def get_datasets(self, currency_type):\n        prices = Price.objects.filter(currency_type=currency_type)\n\n        data = [{'x': price.date, 'y': price.point} for price in prices]\n\n        return [DataSet(data=data)]\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    If we supply an instance of this chart to the context of our template, we could use this to render two different charts. This is done by using the \u003ccode\u003erender_chart\u003c/code\u003e template tag to supply additional parameters to the \u003ccode\u003eget_datasets\u003c/code\u003e method:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003e{\u0026#37; render_chart price_chart 'euro' \u0026#37;}\n\n{\u0026#37; render_chart price_chart 'dollar' \u0026#37;}\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    For asynchronous charts any url parameters are passed to the \u003ccode\u003eget_datasets\u003c/code\u003e method.\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003efrom jchart.views import ChartView\nfrom .charts import PriceChart\n\nprice_chart = PriceChart()\n\nurlpatterns = [\n    url(r'^currency_chart/(?P\u003c\u003e\\w+)/$',\n        ChartView.from_chart(price_chart))\n]\u003c/code\u003e\u003c/pre\u003e\n\n\u003cp\u003e\n    To render this chart asynchronously we have to supply the url parameter as a second argument to the \u003ccode\u003erender_chart\u003c/code\u003e template tag, like so:\n\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"language-python\"\u003e{\u0026#37; load jchart \u0026#37;}\n\n{\u0026#37; render_chart 'price_chart' 'euro' \u0026#37;}\n\n{\u0026#37; render_chart 'price_chart' 'dollar' \u0026#37;}\u003c/code\u003e\u003c/pre\u003e\n\n\n### ToDO\n\n* Composable datasources (instead of having to rely on inheritance)\n* Compare django-jchart to other Django chartig libraries (in the readme)\n\n\n### Contributing\n\n#### Releasing\n\n* To release update the version of the package in `setup.py`.\n* Add release to `CHANGELOG.md`.\n* Run commands:\n\n```\npython setup.py sdist bdist_wheel --universal\ntwine upload dist/*\n```\n\n* Add git tag to commit","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthisk%2Fdjango-jchart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthisk%2Fdjango-jchart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthisk%2Fdjango-jchart/lists"}