# DjangoCMS_Charts
[](https://badge.fury.io/py/djangocms-charts)
[](https://crate.io/packages/djangocms-charts/)
A plugin for DjangoCMS that creates easy to use and fully customisable ChartJs (ver 2.x) charts - with a table and csv upload interface.
## Updates
- 3.0.0
- **CAUTION** - This is a complete refactoring of DjangoCMS Charts to ChartJS version 2.x
- ***All Models, Fields, and Options have changed***
- ***Due to changes in ChartJS 1.x > 2.x - Not all Custom settings will be migrated***
- The migrations attempt to bring over any settings changed from the default values from each previous chart.
- ChartJS is enabled by default - update settings to disable as below
- All chart types are now available in the ChartsJS Plugin
- Multiple Datasets can be added as Child Plugins of the parent ChartJS Plugin
- Global Options are added in the Admin, as required.
- All Options come from the ChartJS object/dictionary and are using a Select2 list
## Quick start
1. Add 'djangocms_charts' to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [
...
'djangocms_charts',
]
2. Run `python manage.py migrate` to create the djangocms_charts models.
3. Ensure you have your own version of jQuery added to block 'js'. See here: https://django-sekizai.readthedocs.io/en/latest/#example
4. Add a DjangoCMS ChartJS Plugin to your web page!
## Caching [Optional]
The queries and building up of each chart can be expensive for many options/data rows/charts etc.
To speed this up set up a dedicated DjangoCMS Charts cache.
This **should be a unique cache** as it will require to be cleared after saving any charts object due to the complex relationship between all objects.
1. In `settings.py` add `DJANGOCMS_CHARTS_CACHE = 'djangocms_charts'` which should map to a unique cache.
2. In your `CACHES` add the charts cache - sample backend below - use your own cache system:
```
CACHES = {
'default': {
...
},
'djangocms_charts':{
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
'LOCATION': 'djangocms_charts',
'TIMEOUT': CACHE_MIDDLEWARE_SECONDS,
'OPTIONS': {
'MAX_ENTRIES': 5000
}
},
}
```
## URLS [Optional]
If access to the JSON Vesion of the chart is required add the following to your `urls.py` :
```
urlpatterns = [
...
url(r'^chartjs/', include('djangocms_charts.urls')),
...
]
```
The JSON view can then be accessed via:
- Chart View: `[url]/chartjs/get_chart_as_json/[chart_id]/`
- Global Options View: `[url]/get_global_options_as_json/[options_id]/`
## ChartJs-Sass [Optional]
All chart dataset colours (backgroundColor, borderColor, etc) can be set using CSS via ChartJS-Sass. This JS library will update any unspecified colors with those specified in the CSS and built using SASS.
For more details see: https://github.com/mcldev/ChartJS-Sass
1. To disable/enable, in `settings.py` add `DJANGOCMS_CHARTS_ENABLE_CHARTJS_SASS = True or False (default=True)`
## Usage
### Chart Types
The following chart types can be selected with options (see below)
- Line
- Line XY (Scatter with line)
- Bar
- Horizontal Bar
- Radar
- Polar
- Pie
- Doughnut
- Bubble
- Scatter
- Mixed (see Multiple Datasets)
### Input Data
All input data will be used as below.
NB: Multiple datasets can be added as either:
- Dataset Plugins as child to each Chart Plugin (customisable colours/formats etc)
- Multiple rows or columns within a Chart input table (scriptable colours/formats)
```
# Line, Bar, Radar, Doughnut, Pie, PolarArea
# ------------------------------------------
# Datasets in 'cols' > TRANSPOSED
# Label_1, Label_2, ...
# Jan-20 10 30
# Feb-20 20 40
# ...
#
# OR
#
# Datasets in 'rows' > USES THIS FORMAT INTERNALLY
# Jan-20 Feb-20, ...
# Label_1 10 20
# Label_2 30 40
# ...
#
# Bubble [r], Scatter, Line_XY
# ----------------------------
# [r - radius - is ignored for line and scatter]
#
# Datasets in 'cols' > TRANSPOSED
# x 10 20 ...
# y 30 40 ...
# [r] 5 10 ...
#
# OR
#
# Datasets in 'rows' > USES THIS FORMAT INTERNALLY
# x, y, [r]
# 10 30 5
# 20 40 10
# ...
```
### Axes
https://www.chartjs.org/docs/latest/axes/
Multiple Axes can be added using X Axis or Y Axis. Each Axis can be used multiple times (e.g. Linear axis).
Options for Axes are set below.
### Multiple Datasets
https://www.chartjs.org/docs/latest/charts/mixed.html#drawing-order
Multiple datasets can be added as rows/columns of the main chart, or added as Dataset child plugins.
The rendering order for ChartJS is that the first dataset is top-most - this plugin prepends the subsequent child datasets so the last dataset is top-most.
### Mixed Types
https://www.chartjs.org/docs/latest/charts/mixed.html
Each child Dataset can have a different type, thus creating a Mixed Chart.
**NB:** Some types do not mix well (Radar/Bar etc) - we make no validation on each possible combination.
## Dataset Colors
Dataset Color Groups can be specified as a user-friendly list of colors, with a click-and-drag sortable feature.
### Specifying the color group
Specifications for each group require the following:
- Type (select multiple types with Ctrl)
- the Chart/Dataset type that these colors will be applied to
- Namespace Labels (select multiple types with Ctrl)
- the dataset namespace labels that will use these colors
- e.g. `backgroundColor, borderColor, pointBackgroundColor, ...`
- Colors
- a text list of **hex only** colors
- these can be selected/edited/rearranged through the interface
### Application of Color Groups
These color groups can then be applied as follows:
- Globally
- by assigning the color group to the Global Settings
- any Chart/Dataset (without colors specified) will use these colors
- By Chart
- all of the Chart datasets and any sub-datasets (without colors specified) will have these colors applied
- By Dataset
- any Dataset can specifically use this Color Group
### Color By Dataset or Series
The flag to set 'Color by Dataset' will do the following:
- Color by Dataset: `True`
- Each individual Dataset will use one color from the color array based on its index
- e.g. with a color array of `[red, green, blue]`
```
# Jan-20 Feb-20, ...
# Label_1 10 20 <- red
# Label_2 30 40 <- green
# Label_3 50 60 <- blue
```
- Color by Series: `False`
- Each individual Dataset will get the full color array to use for each element in Series
- e.g. with a color array of `[red, green, blue]`
```
# Jan-20 Feb-20, ...
# Label_1 10 <- red 20 <- green
# Label_2 30 <- red 40 <- green
# Label_3 50 <- red 60 <- green
```
## Options
https://www.chartjs.org/docs/latest/configuration/
Options are set in JavaScript using the settings provided by ChartJS - Use this documentation: https://www.chartjs.org/docs/latest/
The Options are assigned in ascending order of priority as:
- `Chart.defaults.global.<option>` - see GlobalOptionsGroup in Admin
- `chart.options.<option>` - see ChartOptions Group selectable for each chart
- `chart.options.<option>` - see ChartSpecificOptions assigned to each chart individually
- `dataset.<option>` - see DatasetOptionsGroup selectable for each dataset
- `dataset.<option>` - see DatasetSpecificOptions assigned to each dataset individually
- `chart.options.scales.<axes>.<option>` - see AxisOptionsGroup selectable for each axis
### Option Input Types
https://www.chartjs.org/docs/latest/general/options.html
ChartJS accepts various input option formats, some can be scripted, functions, numbers, or text.
DjangoCMS Charts options can be input as any one of the following types:
**NB. there is no validation of input types - Errors will appear in the console**
- text
- Any form of text input, such as a colour. e.g. `#28aece`
- Sample output: `{"option_name": "#28aece"}`
- number
- Either an integer or float can be input e.g. `2 or 3.5`
- A float (with a '.') will be converted to float
- Sample output: `{"option_name": 2}`
- boolean
- Text or number be cast to a boolean, can be any of `'true', 'false', 1, 0`
- Sample output: `{"option_name": true}`
- json
- Text to be parsed and loaded as valid Json, e.g. `['red', 'blue', 'green']`
- Sample output: `{"option_name": ["red", "blue", "green"]}`
- array
- Will split a string array into elements using the following (in order):
- `"\n"` (new line)
- `","` (comma)
- `"\t"` (tab)
- `" "` (space)
- Sample input: `red blue green`
- Sample output: `{"option_name": ["red", "green", "blue"}]`
- function
- A js function string that will be cleaned (new lines etc.) and injected into the code.
- Can be a valid function name or complete function **without comments**
- Sample:
```
function(context) {
var index = context.dataIndex;
var value = context.dataset.data[index];
return value < 0 ? 'red' :
index % 2 ? 'blue' :
'green';
}
```
# More details on ChartJs
http://www.chartjs.org/
ChartJs is a dynamic JS charting application giving users an interactive and visually appealing chart in an html 5 canvas. Each type of chart is available:
Raw data
{
"_id": null,
"home_page": "https://github.com/mcldev/djangocms-charts",
"name": "djangocms-charts",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Michael Carder Ltd",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/73/e5/6c989cc77ba33f82a77e6958cac611fd3995335edb1eb985b0849c5c06af/djangocms_charts-3.0.4.tar.gz",
"platform": null,
"description": "# DjangoCMS_Charts\r\n\r\n\r\n[](https://badge.fury.io/py/djangocms-charts)\r\n[](https://crate.io/packages/djangocms-charts/)\r\n\r\nA plugin for DjangoCMS that creates easy to use and fully customisable ChartJs (ver 2.x) charts - with a table and csv upload interface.\r\n\r\n## Updates\r\n\r\n- 3.0.0\r\n - **CAUTION** - This is a complete refactoring of DjangoCMS Charts to ChartJS version 2.x\r\n - ***All Models, Fields, and Options have changed***\r\n - ***Due to changes in ChartJS 1.x > 2.x - Not all Custom settings will be migrated***\r\n - The migrations attempt to bring over any settings changed from the default values from each previous chart.\r\n - ChartJS is enabled by default - update settings to disable as below\r\n - All chart types are now available in the ChartsJS Plugin\r\n - Multiple Datasets can be added as Child Plugins of the parent ChartJS Plugin\r\n - Global Options are added in the Admin, as required.\r\n - All Options come from the ChartJS object/dictionary and are using a Select2 list\r\n\r\n## Quick start\r\n1. Add 'djangocms_charts' to your INSTALLED_APPS setting like this::\r\n\r\n INSTALLED_APPS = [\r\n ...\r\n 'djangocms_charts',\r\n ]\r\n\r\n2. Run `python manage.py migrate` to create the djangocms_charts models.\r\n\r\n3. Ensure you have your own version of jQuery added to block 'js'. See here: https://django-sekizai.readthedocs.io/en/latest/#example\r\n\r\n4. Add a DjangoCMS ChartJS Plugin to your web page!\r\n\r\n## Caching [Optional]\r\nThe queries and building up of each chart can be expensive for many options/data rows/charts etc. \r\nTo speed this up set up a dedicated DjangoCMS Charts cache.\r\nThis **should be a unique cache** as it will require to be cleared after saving any charts object due to the complex relationship between all objects.\r\n\r\n1. In `settings.py` add `DJANGOCMS_CHARTS_CACHE = 'djangocms_charts'` which should map to a unique cache.\r\n\r\n2. In your `CACHES` add the charts cache - sample backend below - use your own cache system:\r\n```\r\nCACHES = {\r\n 'default': {\r\n ...\r\n },\r\n 'djangocms_charts':{\r\n 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',\r\n 'LOCATION': 'djangocms_charts',\r\n 'TIMEOUT': CACHE_MIDDLEWARE_SECONDS,\r\n 'OPTIONS': {\r\n 'MAX_ENTRIES': 5000\r\n }\r\n },\r\n}\r\n```\r\n\r\n## URLS [Optional]\r\nIf access to the JSON Vesion of the chart is required add the following to your `urls.py` :\r\n\r\n```\r\nurlpatterns = [\r\n ...\r\n url(r'^chartjs/', include('djangocms_charts.urls')),\r\n ...\r\n]\r\n```\r\nThe JSON view can then be accessed via:\r\n - Chart View: `[url]/chartjs/get_chart_as_json/[chart_id]/`\r\n - Global Options View: `[url]/get_global_options_as_json/[options_id]/`\r\n\r\n\r\n## ChartJs-Sass [Optional]\r\nAll chart dataset colours (backgroundColor, borderColor, etc) can be set using CSS via ChartJS-Sass. This JS library will update any unspecified colors with those specified in the CSS and built using SASS.\r\nFor more details see: https://github.com/mcldev/ChartJS-Sass\r\n\r\n1. To disable/enable, in `settings.py` add `DJANGOCMS_CHARTS_ENABLE_CHARTJS_SASS = True or False (default=True)` \r\n\r\n\r\n## Usage\r\n\r\n### Chart Types\r\nThe following chart types can be selected with options (see below)\r\n- Line\r\n- Line XY (Scatter with line)\r\n- Bar\r\n- Horizontal Bar\r\n- Radar\r\n- Polar\r\n- Pie\r\n- Doughnut\r\n- Bubble\r\n- Scatter\r\n- Mixed (see Multiple Datasets)\r\n\r\n\r\n### Input Data\r\nAll input data will be used as below.\r\n \r\nNB: Multiple datasets can be added as either:\r\n- Dataset Plugins as child to each Chart Plugin (customisable colours/formats etc)\r\n- Multiple rows or columns within a Chart input table (scriptable colours/formats)\r\n\r\n```\r\n # Line, Bar, Radar, Doughnut, Pie, PolarArea\r\n # ------------------------------------------\r\n # Datasets in 'cols' > TRANSPOSED\r\n # Label_1, Label_2, ...\r\n # Jan-20 10 30\r\n # Feb-20 20 40\r\n # ...\r\n #\r\n # OR\r\n #\r\n # Datasets in 'rows' > USES THIS FORMAT INTERNALLY\r\n # Jan-20 Feb-20, ...\r\n # Label_1 10 20\r\n # Label_2 30 40\r\n # ...\r\n #\r\n # Bubble [r], Scatter, Line_XY\r\n # ----------------------------\r\n # [r - radius - is ignored for line and scatter]\r\n #\r\n # Datasets in 'cols' > TRANSPOSED\r\n # x 10 20 ...\r\n # y 30 40 ...\r\n # [r] 5 10 ...\r\n #\r\n # OR\r\n #\r\n # Datasets in 'rows' > USES THIS FORMAT INTERNALLY\r\n # x, y, [r]\r\n # 10 30 5\r\n # 20 40 10\r\n # ...\r\n```\r\n\r\n### Axes\r\nhttps://www.chartjs.org/docs/latest/axes/\r\n\r\nMultiple Axes can be added using X Axis or Y Axis. Each Axis can be used multiple times (e.g. Linear axis).\r\nOptions for Axes are set below.\r\n\r\n### Multiple Datasets\r\nhttps://www.chartjs.org/docs/latest/charts/mixed.html#drawing-order\r\n\r\nMultiple datasets can be added as rows/columns of the main chart, or added as Dataset child plugins.\r\nThe rendering order for ChartJS is that the first dataset is top-most - this plugin prepends the subsequent child datasets so the last dataset is top-most.\r\n\r\n### Mixed Types\r\nhttps://www.chartjs.org/docs/latest/charts/mixed.html\r\n\r\nEach child Dataset can have a different type, thus creating a Mixed Chart. \r\n**NB:** Some types do not mix well (Radar/Bar etc) - we make no validation on each possible combination.\r\n\r\n## Dataset Colors\r\nDataset Color Groups can be specified as a user-friendly list of colors, with a click-and-drag sortable feature.\r\n\r\n### Specifying the color group\r\nSpecifications for each group require the following:\r\n- Type (select multiple types with Ctrl)\r\n - the Chart/Dataset type that these colors will be applied to\r\n- Namespace Labels (select multiple types with Ctrl)\r\n - the dataset namespace labels that will use these colors\r\n - e.g. `backgroundColor, borderColor, pointBackgroundColor, ...`\r\n- Colors \r\n - a text list of **hex only** colors\r\n - these can be selected/edited/rearranged through the interface\r\n\r\n### Application of Color Groups \r\nThese color groups can then be applied as follows:\r\n- Globally \r\n - by assigning the color group to the Global Settings\r\n - any Chart/Dataset (without colors specified) will use these colors\r\n- By Chart\r\n - all of the Chart datasets and any sub-datasets (without colors specified) will have these colors applied\r\n- By Dataset\r\n - any Dataset can specifically use this Color Group \r\n\r\n### Color By Dataset or Series\r\nThe flag to set 'Color by Dataset' will do the following:\r\n- Color by Dataset: `True`\r\n - Each individual Dataset will use one color from the color array based on its index\r\n - e.g. with a color array of `[red, green, blue]`\r\n ```\r\n # Jan-20 Feb-20, ...\r\n # Label_1 10 20 <- red\r\n # Label_2 30 40 <- green\r\n # Label_3 50 60 <- blue\r\n ```\r\n- Color by Series: `False`\r\n - Each individual Dataset will get the full color array to use for each element in Series\r\n - e.g. with a color array of `[red, green, blue]`\r\n ```\r\n # Jan-20 Feb-20, ...\r\n # Label_1 10 <- red 20 <- green\r\n # Label_2 30 <- red 40 <- green\r\n # Label_3 50 <- red 60 <- green\r\n ```\r\n\r\n## Options\r\nhttps://www.chartjs.org/docs/latest/configuration/\r\n\r\nOptions are set in JavaScript using the settings provided by ChartJS - Use this documentation: https://www.chartjs.org/docs/latest/ \r\n\r\nThe Options are assigned in ascending order of priority as:\r\n- `Chart.defaults.global.<option>` - see GlobalOptionsGroup in Admin\r\n- `chart.options.<option>` - see ChartOptions Group selectable for each chart\r\n- `chart.options.<option>` - see ChartSpecificOptions assigned to each chart individually\r\n- `dataset.<option>` - see DatasetOptionsGroup selectable for each dataset\r\n- `dataset.<option>` - see DatasetSpecificOptions assigned to each dataset individually\r\n- `chart.options.scales.<axes>.<option>` - see AxisOptionsGroup selectable for each axis \r\n\r\n### Option Input Types\r\nhttps://www.chartjs.org/docs/latest/general/options.html\r\n\r\nChartJS accepts various input option formats, some can be scripted, functions, numbers, or text.\r\nDjangoCMS Charts options can be input as any one of the following types:\r\n\r\n**NB. there is no validation of input types - Errors will appear in the console** \r\n- text\r\n - Any form of text input, such as a colour. e.g. `#28aece`\r\n - Sample output: `{\"option_name\": \"#28aece\"}`\r\n- number\r\n - Either an integer or float can be input e.g. `2 or 3.5`\r\n - A float (with a '.') will be converted to float\r\n - Sample output: `{\"option_name\": 2}` \r\n- boolean\r\n - Text or number be cast to a boolean, can be any of `'true', 'false', 1, 0`\r\n - Sample output: `{\"option_name\": true}`\r\n- json\r\n - Text to be parsed and loaded as valid Json, e.g. `['red', 'blue', 'green']`\r\n - Sample output: `{\"option_name\": [\"red\", \"blue\", \"green\"]}`\r\n- array\r\n - Will split a string array into elements using the following (in order): \r\n - `\"\\n\"` (new line)\r\n - `\",\"` (comma)\r\n - `\"\\t\"` (tab)\r\n - `\" \"` (space)\r\n - Sample input: `red blue green`\r\n - Sample output: `{\"option_name\": [\"red\", \"green\", \"blue\"}]`\r\n- function\r\n - A js function string that will be cleaned (new lines etc.) and injected into the code.\r\n - Can be a valid function name or complete function **without comments**\r\n - Sample: \r\n ```\r\n function(context) {\r\n var index = context.dataIndex;\r\n var value = context.dataset.data[index];\r\n return value < 0 ? 'red' :\r\n index % 2 ? 'blue' : \r\n 'green';\r\n }\r\n ```\r\n\r\n# More details on ChartJs\r\nhttp://www.chartjs.org/\r\n \r\nChartJs is a dynamic JS charting application giving users an interactive and visually appealing chart in an html 5 canvas. Each type of chart is available:\r\n\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "DjangoCMS Plugin to add and edit ChartJs charts",
"version": "3.0.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d1e8cd8d0c590d21b8b93ed388203ed45eb4955a132a07285dff21195365306b",
"md5": "42b0aa0beb033da57c41232a8b6b12e6",
"sha256": "2507df585c33a68b79e144cd0c0dfbc370204ad07185ea40165f19f5b6c6ad8f"
},
"downloads": -1,
"filename": "djangocms_charts-3.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42b0aa0beb033da57c41232a8b6b12e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 888744,
"upload_time": "2023-03-26T06:47:58",
"upload_time_iso_8601": "2023-03-26T06:47:58.470724Z",
"url": "https://files.pythonhosted.org/packages/d1/e8/cd8d0c590d21b8b93ed388203ed45eb4955a132a07285dff21195365306b/djangocms_charts-3.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73e56c989cc77ba33f82a77e6958cac611fd3995335edb1eb985b0849c5c06af",
"md5": "acf36eb4f29572b4a91e7f44d2eecf36",
"sha256": "f07820aee1033daeb2e90fb730f0558e5ba47021e681c16c95421d7e6523b9d6"
},
"downloads": -1,
"filename": "djangocms_charts-3.0.4.tar.gz",
"has_sig": false,
"md5_digest": "acf36eb4f29572b4a91e7f44d2eecf36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 864786,
"upload_time": "2023-03-26T06:48:18",
"upload_time_iso_8601": "2023-03-26T06:48:18.645674Z",
"url": "https://files.pythonhosted.org/packages/73/e5/6c989cc77ba33f82a77e6958cac611fd3995335edb1eb985b0849c5c06af/djangocms_charts-3.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-26 06:48:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mcldev",
"github_project": "djangocms-charts",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "djangocms-charts"
}
JSON
