wagtail-plotly 0.0.3

Plotly for Wagtail CMS

Wagtail Plotly

This project aims to provide content focused management of Plotly.py charts in Wagtail CMS and to give developers and easy way customise and extend plots.

Some more examples

Installation

Install from PyPI:

pip install wagtail-plotly

Then add the following to your project's INSTALLED_APPS.

'wagtail.contrib.table_block',
'wagtail_plotly',
'wagtail_json_widget',

Settings

WAGTAIL_PLOTLY_INCLUDE_PLOTLYJS

Default: 'https://cdn.plot.ly/plotly-1.58.4.min.js'

A url string providing the location of a Plotly JS libarary

DEFAULT_PLOTLY_JSON_DIRECTORY

Default: 'plotly'

The name of the app directory in which to look for custom json plots. Wagtail Plotly will search all installed apps looking for a directory matching the DEFAULT_PLOTLY_JSON_DIRECTORY value and will attempt to load any .json files it contains. See Customising for more information.

Usage overview

There are several plot blocks that you can use out of the box:

• BarChartBlock / LinePlotBlock
• ContourPlotBlock / HeatmapPlotBlock
• PieChartBlock
• ScatterPlotBlock

Adding one of these blocks provides you with input fields to manage the content of your plot, primarily titles and data, and a layout/style option(s). There is one default option out-of-the-box and more can be added by developers via .json files using Plotly's schema. See Customising

This app also provides versions of the above blocks that support case by case customisation via a json field in the CMS UI.

Example use

One way of using it is to create a StreamBlock:

from wagtail.core import blocks

from wagtail_plotly.blocks import (
    BarChartBlock,
    ContourPlotBlock,
    HeatmapPlotBlock,
    LinePlotBlock,
    PieChartBlock,
    ScatterPlotBlock,
)

class MyStreamBlock(blocks.StreamBlock):
    bar_chart = BarChartBlock()
    contour_plot = ContourPlotBlock()
    heatmap_plot = HeatmapPlotBlock()
    line_plot = LinePlotBlock()
    pie_chart = PieChartBlock()
    scatter_plot = ScatterPlotBlock()

Add the StreamBlock to a StreamField on a Wagtail page:

from wagtail.admin.edit_handlers import StreamFieldPanel
from wagtail.core.fields import StreamField
from wagtail.core.models import Page

from .blocks import MyStreamBlock


class MyPage(Page):

    body = StreamField(MyStreamBlock(), null=True)

    content_panels = Page.content_panels + [
        StreamFieldPanel('body'),
    ]

Then in the page template:

{% load static wagtailcore_tags %}

{% include_block page.body %}

Customising

Configuring plotly graphs can be complex because there are a lot of options available. plotly provide Chart Studio from which graphs and layouts can be made and exported as JSON data.

Wagtail Plotly is designed to consume a subset of this data with minimal effort by developers: Wagtail Plotly will look for directories named plotly (by default) in each installed app and any .json files therein are assumed to be configuration options that are presented to users as Graph layout options. In this way developers can provide managed plot configurations to end-users that override the default settings.

For example: my_plot.json might contain:

{
    "layout": {
        "xaxis": {
            "gridcolor": "#dddddd",
            "mirror": true
        },
        "yaxis": {
            "gridcolor": "#dddddd",
            "mirror": true
        },
        "autosize": true,
        "colorway": [
            "#4c78a8",
            "#f58518",
            "#e45756",
            "#72b7b2",
            "#54a24b",
            "#eeca3b",
            "#b279a2",
            "#ff9da6",
            "#9d755d",
            "#bab0ac"
        ]
    }
}

Customising StreamField Blocks

Plots in Wagtail Plotly are a set of Wagtail StreamField blocks that share a common base BasePlotBlock. They can be used as is or extended to create custom plots or features of Plotly that aren't (yet) handled by default.

All of the blocks have a plot_data field for entering plot data (based on wagtail.contrib.table_block) and build_data method for extracting data from the table ready for plotting.

Creating new plot blocks

New plot blocks can be created in the usual way: subclassing from eitherBasePlotBlock or one of the above blocks.