Configuring

Chartwerk allows you to set a number of configuration options. Some add additional features to the app.

App settings

Default settings
CHARTWERK_AUTH_DECORATOR = "django.contrib.auth.decorators.login_required"
CHARTWERK_API_AUTHENTICATION_CLASSES = ("rest_framework.authentication.SessionAuthentication",)
CHARTWERK_API_PERMISSION_CLASSES = ("rest_framework.permissions.IsAuthenticatedOrReadOnly",)
CHARTWERK_COLOR_SCHEMES = {} # Uses default color scheme in chartwerk-editor

CHARTWERK_AUTH_DECORATOR

String module path to a decorator that should be applied to Chartwerk views to authenticate users.

Warning

This decorator is not applied to views if DEBUG is True in your settings.

CHARTWERK_API_AUTHENTICATION_CLASSES

Iterable of string module paths to valid Django REST authentication classes that should be applied to Django REST Framework’s browsable API viewsets.

CHARTWERK_API_PERMISSION_CLASSES

Iterable of string module paths to valid Django REST permission classes that should be applied to Django REST Framework’s browsable API viewsets.

CHARTWERK_COLOR_SCHEMES

Set this variable in your project settings to declare a default set of color schemes your users can select for chart elements. The schemes must be organized by type as a dictionary with keys categorical, sequential and diverging. Name each color scheme and then provide a list of hexadecimal color codes. For example:

# settings.py

CHARTWERK_COLOR_SCHEMES = {
  'categorical': {
      'default': [
          '#AAAAAA',
          '#BBB',
          # etc.
      ],
  }
  'sequential': {
      'reds': [
          '#FF0000',
          '#8B0000',
          # etc.
      ],
      'blues': [
          '#0000FF',
          '#000080',
          # etc.
      ]
  },
  'diverging': {
      'redBlue': [
          '#FF0000',
          '#0000FF',
          # etc.
      ]
  }
}

Warning

You should specify a default color scheme under the categorical key. You can name all other schemes whatever you want.

AWS

Default settings
CHARTWERK_AWS_ACCESS_KEY_ID = None  # Required
CHARTWERK_AWS_SECRET_ACCESS_KEY = None  # Required
CHARTWERK_AWS_BUCKET = None  # Required
CHARTWERK_AWS_PATH = "charts"
CHARTWERK_AWS_REGION = "us-east-1"
CHARTWERK_CACHE_HEADER = "max-age=300"
CHARTWERK_CLOUDFRONT_DISTRIBUTION = None
CHARTWERK_DOMAIN = None  # Required

CHARTWERK_AWS_ACCESS_KEY_ID (Required)

Amazon Web Services access key ID.

CHARTWERK_AWS_SECRET_ACCESS_KEY (Required)

AWS secret access key.

CHARTWERK_AWS_BUCKET (Required)

AWS S3 bucket name to publish charts to.

CHARTWERK_DOMAIN (Required)

The domain of the app running Chartwerk. For example, your app may be hosted at http://myapp.mydomain.com.

CHARTWERK_AWS_REGION

Region of your AWS bucket.

CHARTWERK_AWS_PATH

Path within your S3 bucket to append to your charts when publishing. For example, setting to chartwerk/charts would result in charts published to chartwerk/charts/<chart_id>.html in your bucket.

CHARTWERK_CACHE_HEADER

Cache header to add to chart files when published to S3.

CHARTWERK_CLOUDFRONT_DISTRIBUTION

If you’re using Amazon CloudFront in front of your S3 bucket and would like to create an invalidation whenever charts are updated, add your distribution ID to this setting.

Compiling JavaScript

CHARTWERK_JS_SUBPROCESS

If you’d like to write your template scripts using modern JavaScript syntax, you can pipe them through a compiler before publishing by specifying arguments to pass to Python’s subprocess module.

For example, if you’d like to compile ES2015 syntax using Babel, you could specify subprocess args like this:

CHARTWERK_JS_SUBPROCESS = ['npx', 'babel', '--presets=es2015']

This option assumes you have already installed the dependencies referenced in your subprocess on your server. Obviously, you can only use CLI compilers with this method.

Note

This method does not compile scripts in the Editor. You should use a browser that supports the syntax features you’re targeting when you and your users develop charts. JavaScript will be compiled before baking your charts to S3.

GitHub

Django-chartwerk can commit your chart templates to a GitHub repository for safe keeping.

Default settings
CHARTWERK_GITHUB_ORG = None
CHARTWERK_GITHUB_REPO = "chartwerk_chart-templates"
CHARTWERK_GITHUB_USER = None
CHARTWERK_GITHUB_PASSWORD = None
CHARTWERK_GITHUB_TOKEN = None

CHARTWERK_GITHUB_ORG

To keep templates in a repo under a GitHub organization, set this variable to the GitHub org name.

CHARTWERK_GITHUB_REPO

The name of the repo to save chart templates to.

CHARTWERK_GITHUB_USER

GitHub username to access GitHub API.

Note

We recommend you use a personal access token instead of setting your username and password in these settings.

CHARTWERK_GITHUB_PASSWORD

Password for your GitHub username.

CHARTWERK_GITHUB_TOKEN

GitHub personal access token with rights to edit private repositories.

Slack

Chartwerk can send notifications to a Slack channel whenever a new chart is created.

Default settings
CHARTWERK_SLACK_CHANNEL = "#chartwerk"
CHARTWERK_SLACK_TOKEN = None

CHARTWERK_SLACK_CHANNEL

Name of the Slack channel to post notifications to.

CHARTWERK_SLACK_TOKEN

A Slack API token.

oEmbed

Chartwerk can act as an oEmbed provider, returning embeddable charts using an oEmbed endpoint at api/oembed.

Default settings
CHARTWERK_OEMBED = False
CHARTWERK_OEMBED_EXTRA_PATTERNS = []

CHARTWERK_OEMBED

Set to True to have the oEmbed endpoint returned in the API’s context object.

CHARTWERK_OEMBED_EXTRA_PATTERNS

If you’d like the oEmbed endpoint to support any additional URL patterns, provide them here. This can be useful if, for example, you alter your root URL configuration and all of the chart URLs change. Each pattern should be provided as a regular expression, with named capture groups that can be used to lookup charts. For example:

# settings.py

CHARTWERK_OEMBED_EXTRA_PATTERNS = (
  r'^old-chartwerk/chart/(?P<slug>[-\w]+)/$',
)

Configuring an oEmbed integration

Configure your CMS’s oEmbed integration to make GET requests to django-chartwerk’s oEmbed endpoint at /api/oembed/. An example might look like: https://myapp.com/chartwerk/api/oembed/.

At minimum, you need to send an encoded URI for the chart you’d like to embed in a url query parameter. In django-chartwerk, charts have two canonical URIs:

  • /chart/<chart ID>/
  • /api/charts/<chart ID>/

The embed code generator in chartwerk-editor will return the latter to the user when CHARTWERK_OEMBED = True.

So an oEmbed request might look like:

https://myapp.com/chartwerk/api/oembed/?url=https%3A%2F%2Fmyapp.com%2Fchartwerk%2Fchart%2F<chart ID>%2F

Remember, django-chartwerk will bake out two chart sizes, double and single-wide. Your integration is responsible for passing a user’s preferred chart size in the oEmbed request as an additional query string parameter, size={single|double}.

A response – using the default embed code – may look like this:

{
  "version": "1.0",
  "url": "https:\/\/myapp.com\/chartwerk\/chart\/<chart ID>\/",
  "title": "A map",
  "provider_url": "https:\/\/myapp.com\/chartwerk\/",
  "provider_name": "Chartwerk",
  "author_name": "user@email.com",
  "chart_id": "<chart ID>",
  "type": "rich",
  "size": "double",
  "width": 600,
  "height": 494,
  "single_width": 290,
  "single_height": 329,
  "html": "<div id=\"chartwerk_<chart ID>\" class=\"chartwerk\" data-id=\"<chart ID>\" data-dimensions=\"{&quot;double&quot;: {&quot;width&quot;: 600, &quot;height&quot;: 494}, &quot;single&quot;: {&quot;width&quot;: 290, &quot;height&quot;: 329}}\" data-size=\"double\" data-src=\"https:\/\/myS3bucket.com\/charts\/chartwerk\/\" ><\/div> <script src=\"https:\/\/myS3bucket.com\/charts\/chartwerk\/embed-script\/v1.js\"><\/script>"
}

The html property in the response object will be generated using CHARTWERK_EMBED_TEMPLATE. Your integration should use it to inject your embed code into your page.

Embed code

These settings configure the code used to embed your charts in a page. The code is either returned to your users directly in the Editor or sent as part of the oEmbed response object, if oEmbed is configured.

The embed code is responsible for injecting an iframe into a page, setting its source to either the single or double-wide chart and, usually, setting its height, width, margins and float styles. (The default embed code uses Pym.js.)

By templatizing the embed code, django-chartwerk gives you the freedom to write exactly the code you need for your CMS. The settings consist of a template string, which you can write to include any arbitrary HTML, CSS, or JavaScript, and a context object that allows you to render your tempate with context from a chart instance.

Note

These aren’t required settings, but the defaults will be generally useless. At minimum, you should change the embed template context, CHARTWERK_EMBED_TEMPLATE_CONTEXT.

Default settings
CHARTWERK_EMBED_TEMPLATE = """
<div
  id="chartwerk_{{id}}"
  class="chartwerk"
  data-id="{{id}}"
  data-dimensions="{{dimensions|safe}}"
  data-size="{{size}}"
  data-src="{{chart_path}}"
></div>
<script src="{{embed_script}}"></script>
"""

CHARTWERK_EMBED_TEMPLATE_CONTEXT = lambda chart: {
    'chart_path': 'http://www.somesite.com/path/to/charts/',
    'embed_script': '<CHARTWERK_DOMAIN>/chartwerk/js/main-embed.bundle.js',
}

CHARTWERK_EMBED_TEMPLATE

A template string which will be rendered with context as the embed code returned to your users. The template will be rendered using the syntax of the template engine you specify in your project settings.

CHARTWERK_EMBED_TEMPLATE_CONTEXT

A function which takes one parameter, a chart instance, and returns a dictionary to use as context when rendering your template string. Any extra context you set is added to three default context items:

  • id - the chart slug
  • size - the preferred chart size specified by the user
  • dimensions - stringified, escaped JSON object specifying the pixel dimensions of both chart sizes

Tips for configuring your embed code

While these settings give you room to completely customize your embed code, in most cases, you can easily use Chartwerk’s default embed template by simply setting the chart_path and embed_script template context variables.

CHARTWERK_EMBED_TEMPLATE_CONTEXT = lambda chart: {
    'chart_path': 'http://www.yourawsbucket.com/path/to/your/charts/',
    'embed_script': '<CHARTWERK_DOMAIN>/chartwerk/js/main-embed.bundle.js',
}

Note

The embed_script path references the script used to inject an iframe on the parent page within your CMS. It is included with the static files in django-chartwerk, but we highly recommend you host it on S3 next to your charts.

When writing your own template string, remember that Chartwerk adds three additional pieces of context: the slug of the chart, the preferred size of the embed specified by the user and the dimensions of each chart size.

The id is the chart slug used to save the chart file to your S3 bucket, either <slug>.html or <slug>_single.html, for double and single-wide, respectively.

The size is either double or single.

The dimensions are a stringified JSON object specifying the height and width of both chart dimensions. You can parse it into an object and use it to set the correct dimensions of your iframe.

// Assuming an templated element like:
// <div data-dimensions="{{dimensions}}"></div>
var dimensions = JSON.parse(<element>.dataset.embed);

// dimensions will be an object like:
{
  double: {
    width: 500,
    height: 300,
  },
  single: {
    width: 290,
    height: 240,
  },
}

You can add any additional properties from your chart as template context.

Remember, that your embed template must include the scripts used to inject, configure and style the iframe on your page.

Custom templates

Customizing the Editor

You can customize the Editor with styles to better reflect your CMS by overriding the chartwerk/editor.html template. Add the template to your project and extend from chartwerk/django-chartwerk-editor.html.

<!-- chartwerk/editor.html -->
{% extends "chartwerk/django-chartwerk-editor.html" %}

{% block head_block %}
<link rel="stylesheet" type="text/css" href="some_styles.css" />
{% endblock %}

{% block body_block %}
<script src="some_script.js"></script>
{% endblock %}

Customizing the child page

If you need to customize charts’ embaddable child page, you can override the template used to bake charts to S3. Add a chartwerk/bake.html template to your project that extends from chartwerk/bake_base.html and add scripts or styles within the available blocks:

<!-- chartwerk/bake.html -->
{% extends "chartwerk/bake_base.html" %}

{% block head_block %}
<link rel="stylesheet" type="text/css" href="some_styles.css" />
{% endblock %}

{% block body_block %}
<script src="some_script.js"></script>
{% endblock %}