Cmsplugin-nvd3 Documentation and Examples

Insert beautiful nvd3-charts into django-cms driven websites

 

About

NVD3 is a tool based on D3.js visualization library. It uses the power of D3.js to plot numerous and beautiful charts easily. WIth help of NVD3 and Javascript it is quite simple to insert different charts into your website pages, but to do it, one needs to know some basics of Javascript.  Cmsplugin-nvd3 is a django-cms plugin developed to be used with all modern versions of django-cms. Using of the plugin does not require any knowledge of Javascript;  all manipulations are performed via django-(cms)-admin interface.  The plugin based on  python-nvd3 library that is used to produce necessary javascript and html code.

Installation

It is assumed that django-cms is already configured and installed in your webserver ecosystem. If not, see django-cms installation procedure.

To get started with cmsplugin-nvd3, you need to install it via pip (python-nvd3 package will be installed automatically):

pip install cmsplugin-nvd3

Insert the plugin app in your django project settings file (settings.py):

INSTALLED_APPS = [
      # ... other apps
      'cmsplugin_nvd3',
        #...    
  ]

Create necessary database tables:

manage.py migrate cmsplugin_nvd3

By default, cmsplugin-nvd3 uses CDN-located resources, but it is recommended to call <collectstatic> command to get copies of these files available locally.

The plugin can be used in a single manner or embedded into text plugins.

Note

By default, the plugin uses sekizai app to handle js and css files. Therefore, it is expected that your base django-cms template includes {% render_block "js" %} and {% render_block "js" %} blocks. Otherwise, you can override "nvd3plugin.html" template that is used for the plugin rendering (in this case, use the latter template as an example).

If you django site uses django-compressor app and the basic template uses compressor as a postprocessor, e.g. {% render_block "css" postprocessor "compressor.contrib.sekizai.compress" %}, this will yield to an error (because cmsplugin_nvd3 uses cdn-sources by default). In this case, you can override your settings as follows (as the another way, you can try to avoid using compressor with external resources):

CMSNVD3_D3JS_SOURCE = 'local'
CMSNVD3_JS_SOURCE = 'local'
CMSNVD3_CSS = 'local'

Setting up these constants to 'local' forces cmsplugin_nvd3 to use local copies of css/js files that are (probably, should be) accessable for compression with django-compressor.
 

Configuration

Cmsplugin-nvd3 behaviour is controlled by the settings, which default values are listed below.

# Value separator for x-data
CMSNVD3_DATASEP = ','

# Group separator for y-series
CMSNVD3_YDATAGROUPSEP = ';'

# Length of random part of id
CMSNVD3_ID_RANDOM_LENGTH = 7

# Container prefix; used only if container name is not specified by user
CMSNVD3_CONT_ID_PREFIX = 'nvd3id_'

# Default container width;
CMSNVD3_CONT_WIDTH = 600

# Default container height;
CMSNVD3_CONT_HEIGHT = 400

# Maximum allowed container size; all values of width or height will be
# reduced to defaults if they exceed this value
CMSNVD3_MAX_CONT_DIM = 3000

# D3, NVD3 sources. You can set up these to 'local' to use copies from static folder
CMSNVD3_D3JS_SOURCE = '//cdnjs.cloudflare.com/ajax/libs/d3/3.5.6/d3.min.js'
CMSNVD3_JS_SOURCE = '//cdn.rawgit.com/novus/nvd3/v1.8.1/build/nv.d3.min.js'
CMSNVD3_CSS = '//cdn.rawgit.com/novus/nvd3/v1.8.1/build/nv.d3.css'

#a path for d3,nvd3 static files, defined as: STATIC_URL+CMSNVD3_URL
CMSNVD3_URL = 'nvd3plugin/'

#Floating point delimiter. You probably will never need to change it.
CMSNVD3_FLT_DELIMITER = '.'

Plugin Model fields

The plugin model includes the following fields:

  • chart_type - mandatory, a django choicefield. It defines the type of the chart. For more information, see python-nvd3 documentation.
  • width, height -  sizes of a chart container in pixels; default is 600 and 400 respectively.
  • container_name - optional field, a name of container id. When it is empty the chart container id is a sum of strings: the <CMSNVD3_CONT_ID_PREFIX> and a random alphnumeric string of length defined by the <CMSNVD3_ID_RANDOM_LENGTH >.
  • color_category - optional field. Defines color scheme for chart rendering. For more information, see python-nvd3 documentation.
  • x_is_date - optional field. If True, x-values are treated as of date format.
  • x_date_format - optional field, a string that defines desirable date formatting. Active only if the pervious field is set up to True.
  • xdata - a string, where x-values are stored. Values assumed to be separated by the <CMSNVD3_DATASEP> separator (which default value is a comma).
  • ydata - a string, where y-values are sotred. Several curves could be defined, but it is expected that they are separated by the <CMSNVD3_YDATAGROUPSEP> separator (which default value is semicolon).
  • ynames - a string, where serie names are stored. Each serie name expected to be separated from others by the <CMSNVD3_DATASEP>. If the number of serie names is not equal to the number of series defined in "ydata", standard names for the series will be used (e.g. serie 1, serie 2 etc.).
  • attrs - additional attributes passed to nvd3 constructor. It is expected that parameters are passed as Python dictionary. The plugin uses abstract syntax tree (ast) package to evaluate extra attrs and insert it into Python-NVD3 chart constructor; For example, if we use lineChart() constructor, then using non-empty attrs in the plugin model is equivalent (in term of Python language) to using lineChart(..., **kwargs=_attrs),  where <_attrs> is evaluated by the ast "attrs". Note, that attrs have higher precedency over the other model fields (e.g. "x_is_date" field); If attrs will be {'x_is_date': True}, "x_is_date" will be forced to "True" anyway.

Note on "xdata" and "ydata" fields

Values of "xdata" and "ydata" fields are treated as numeric (if possible): 1) if  no <CMSNVD3_FLT_DELIMITER> symbol (default is '.') is occured in any series and each value in the field could be converted to integer, the array of values is treated as an array of integers (produced javascript will be, e.g. 10, but not "10"); 2) if  <CMSNVD3_FLT_DELIMITER> is occured and all values could be converted (without errors) to floats, the array of values is treated as an array of floats (produced javascript will be, e.g. 10.2, but not "10.2"); 3) finally, if error is occured during conversion of any type, than array is treated as an array of strings (all values in the produced javascript will be in quotes, e.g. "10.2").

Examples

Plugin model properties

Chart type = lineChart

Width = 400

Height = 300

xdata = 0,1,2,3,4,5

ydata = -2,-1,-1,0,1,4 ; 5,6,5,3,2,1

ynames = first curve, second curve

Plugin model properties

Chart type = pieChart

Width = 400

Height = 300

xdata = apple, orange, tomato, carrot

ydata = 10,40,12,8

 

Plugin model properties

Chart type = discreteBarChart

Width = 400

Height = 300

xdata = A,B,C,D,E,F,G

ydata = 10,30,20,40,50,10,17

 

Plugin model properties

Chart type = multiBarChart

Width = 400

Height = 300

xdata = A,B,C,D

ydata = 6, 1,3, 5; 8, 2, 4, 7

All x-axis ticks apper in the figure at 600x400 container resolution

Plugin model properties

Chart type = scatterChart

Width = 400

Height = 300

xdata = 3, 4, 0, -3, 5, 7

ydata = -1, 2, 3, 3, 15, 2;  1, -2, 4, 7, -5, 3

 

Plugin model properties

Chart type = stackedAreaChart

Width = 400

Height = 300

xdata = 100, 101, 102, 103, 104, 105, 106

ydata = 6, 11, 12, 7, 11, 10, 11; 8, 20, 16, 12, 20, 28, 28

Plugin model properties

Chart type = multiBarHorizontalChart

Width = 400

Height = 300

xdata = -14, -7, 7, 14

ydata =  -6, 5, -1, 9;-23, -6, -32, 9

Plugin model properties

Chart type = lineWithFocusChart

Width = 400

Height = 300

xdata = 1355026400000000, 1355026500000000, 1355026600000000, 1355026700000000, 1355026800000000, 1355026900000000, 1355027000000000

ydata =  -6, 5, -1, 2, 4, 8, 10

x_is_date = True

Plugin model properties

Chart type = linePlusBarChart

Width = 400

Height = 300

xdata = 1338501600000, 1345501600000, 1353501600000

ydata =  -6, 5, -1, 2, 4, 8, 10

x_is_date = True

Plugin model properties

Chart type = cumulativeLineChart

Width = 400

Height = 300

xdata = 1365026400000000, 1365026500000000, 1365026600000000

ydata =  6, 5, 1;36, 55, 11

x_is_date = True

Using plugin extra attributes

Example with attrs = {'show_legend': False}. No legend will be shown ("serie 1" on the top of the plot is absent). For available options, see python-nvd3 documentation.

blog comments powered by Disqus