Ctrlk
JavaDocsDownloadTrySourceSupportAI SDK
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Charts

The chart module provides chart generation capabilities to the Boxlang language.

📊 A comprehensive charting module for BoxLang that brings beautiful, interactive charts to your web applications

This module provides powerful chart generation capabilities to the BoxLang language, making it easy to create stunning data visualizations with minimal code.

✨ Features

  • 🎨 10 Chart Types: pie, bar, line, doughnut, radar, polar area, area, horizontal bar, scatter, and bubble charts

  • 📱 Responsive Design: Charts automatically adapt to container sizes and screen dimensions

  • 🎯 Easy to Use: Simple BoxLang component syntax with nested data structure

  • 🎭 Highly Customizable: Extensive styling options including colors, fonts, axes, and grid lines

  • ⚡ Powered by Chart.js: Built on the popular Chart.js library for modern, interactive charts

  • 📊 Advanced Features: Stacked/clustered series, axis titles, custom scales, and tooltips

  • 🔧 Zero Configuration: Sensible defaults get you started quickly

  • 💪 Production Ready: Built by Ortus Solutions with enterprise-grade quality

📦 Installation

Requirements

  • BoxLang 1.0.0 or higher

  • Web support enabled (for htmlHead() BIF)

Install via CommandBox

The module will automatically register and be available as bxcharts in your BoxLang applications.

🚧 Rewrites CAUTION

If you are using a URL rewriting mechanism (like .htaccess for Apache or URL rewrite rules in Nginx), ensure that requests to static assets (like JavaScript and CSS files) are properly routed to the boxlang_modules/bx-charts/assets/ directory. This is crucial for the Chart.js library and any other assets to load correctly. Also, make sure you are not rewriting the following directory from which assets are delivered from the module:`

The following must passthrough with no rewrites.

Local Development Setup

For local development and testing of the module itself:

This creates a symbolic link in boxlang_modules/bx-charts for local module development and testing.

🚀 Quick Start

Here's how to create your first chart in just a few lines:

That's it! 🎉 You now have a beautiful, interactive pie chart.

📊 Chart Types

The module supports 10 different chart types, each optimized for specific data visualization needs:

🥧 Pie Chart (type="pie")

Perfect for showing proportions and percentages of a whole.

  • Best for: Market share, budget allocation, survey results

  • Data structure: Single series with multiple data points

📊 Bar Chart (type="bar")

Great for comparing values across categories.

  • Best for: Comparing quantities, showing rankings, temporal data

  • Features: Supports stacking and clustering

  • Data structure: Single or multiple series

📈 Line Chart (type="line")

Ideal for showing trends over time.

  • Best for: Time series, trend analysis, continuous data

  • Features: Multiple series support, customizable markers

  • Data structure: One or more series with sequential data points

🍩 Doughnut Chart (type="doughnut")

Similar to pie charts but with a hole in the center.

  • Best for: Proportions with emphasis on total value

  • Visual style: Modern, clean look with central focus area

🕸️ Radar Chart (type="radar")

Shows multivariate data on a circular grid.

  • Best for: Comparing multiple variables, skill assessments, product comparisons

  • Data structure: Multiple data points forming a polygon

🎯 Polar Area Chart (type="polarArea")

Like a pie chart but with varying radius.

  • Best for: Showing proportions where magnitude matters

  • Visual style: Circular sectors with different radii

🏔️ Area Chart (type="area")

Line chart with filled area underneath.

  • Best for: Showing volume over time, cumulative data

  • Features: Emphasizes magnitude of change

↔️ Horizontal Bar Chart (type="horizontalbar")

Bar chart with horizontal orientation.

  • Best for: Long category names, rankings, comparisons

  • Layout: Left-to-right instead of bottom-to-top

🔵 Scatter Plot (type="scatter")

Shows relationship between two variables.

  • Best for: Correlation analysis, distribution patterns

  • Data structure: X-Y coordinate pairs

🫧 Bubble Chart (type="bubble")

Shows three-dimensional data using x, y coordinates and bubble size.

  • Best for: Multi-dimensional data analysis, comparative metrics, portfolio analysis

  • Data structure: X-Y coordinate pairs with radius (r) for bubble size

  • Usage: Use x, y, and r attributes in <bx:chartdata> instead of just value

🎯 Choosing the Right Chart Type

Selecting the appropriate chart type is crucial for effective data visualization. Use this guide to choose the best chart for your data:

📊 Quick Selection Guide

Your Goal

Recommended Chart Type

Why

Show parts of a whole

Pie or Doughnut

Best for displaying percentage distribution of 3-6 categories

Compare values across categories

Bar or Horizontal Bar

Clear visual comparison of discrete values

Show trends over time

Line or Area

Excellent for time series and continuous data

Compare multiple variables

Radar

Perfect for multi-dimensional comparisons (e.g., product features)

Show proportions with magnitude

Polar Area

Like pie chart but size indicates importance

Display correlation

Scatter

Shows relationship between two variables

Show 3D relationships

Bubble

Displays three metrics simultaneously (x, y, size)

Compare with long labels

Horizontal Bar

Better readability for lengthy category names

Emphasize volume/magnitude

Area

Highlights total quantity over time

💡 Decision Tree

⚠️ Common Pitfalls to Avoid

Don't Use

When

Use Instead

Pie Chart

More than 6 categories

Bar Chart

Line Chart

Comparing unrelated categories

Bar Chart

3D Effects

Accuracy is important

2D charts (all types)

Radar Chart

Categories aren't comparable

Bar or Column Chart

Bubble Chart

Only 2 dimensions of data

Scatter Plot

📏 Best Practices

  1. Pie/Doughnut Charts: Limit to 5-6 slices maximum. Order slices by size for better readability.

  2. Bar Charts: Always start the Y-axis at zero to avoid misleading visualizations.

  3. Line Charts: Use for continuous data only. Avoid for unrelated categories.

  4. Radar Charts: Ensure all axes use the same scale and are comparable metrics.

  5. Bubble Charts: Make sure bubble sizes are clearly distinguishable. Use radius (r) values that create visible differences.

  6. Color Selection: Use consistent color schemes. Avoid red/green combinations (color blindness).

📚 Components Reference

📊 <bx:chart> Component

The main container component that renders charts using Chart.js.

Core Attributes

Attribute
Type
Default
Description

title

string

""

Chart title displayed at the top

chartWidth

number

400

Chart width in pixels

chartHeight

number

300

Chart height in pixels

backgroundColor

string

"#ffffff"

Background color (hex or named color)

showLegend

boolean

true

Display legend for multi-series charts

📱 Responsive Attributes

Attribute
Type
Default
Description

responsive

boolean

true

Enable responsive resizing

maintainAspectRatio

boolean

true

Maintain width/height ratio

aspectRatio

number

2

Aspect ratio (width/height)

resizeDelay

number

0

Delay before resize (ms)

🎨 Styling Attributes

Attribute
Type
Default
Description

font

string

-

Font family for chart text

fontBold

boolean

false

Bold text

fontItalic

boolean

false

Italic text

fontSize

number

12

Font size in pixels

foregroundColor

string

"#333333"

Text color

dataBackgroundColor

string

-

Data area background color

📏 Axis Configuration

Attribute
Type
Default
Description

xAxisTitle

string

""

X-axis title

yAxisTitle

string

""

Y-axis title

showXGridlines

boolean

false

Show X-axis grid lines

showYGridlines

boolean

true

Show Y-axis grid lines

showXLabel

boolean

true

Display X-axis labels

scaleFrom

number

-

Y-axis minimum value

scaleTo

number

-

Y-axis maximum value

sortXAxis

boolean

false

Sort labels alphabetically

🎯 Display Options

Attribute
Type
Default
Description

showBorder

boolean

false

Display chart border

showMarkers

boolean

true

Show data point markers

showTooltip

boolean

true

Enable tooltips

markerSize

number

4

Marker size in pixels

show3D

boolean

false

3D appearance (limited support)

📐 Advanced Options

Attribute
Type
Default
Description

seriesPlacement

string

"default"

Series layout: "default", "cluster", "stacked"

labelFormat

string

""

Y-axis label format (use {value} placeholder)

categoryLabelPositions

string

"horizontal"

Label rotation: "horizontal", "up_45", "up_90", "down_45", "down_90", "vertical"

url

string

""

URL to open when clicking data points

📈 <bx:chartseries> Component

Defines a data series within a chart. Must be nested inside <bx:chart>.

Attributes

Attribute
Type
Required
Description

type

string

✅ Yes

Chart type: "pie", "bar", "line", "doughnut", "radar", "polarArea", "area", "horizontalbar", "scatter"

colorlist

string

No

Comma-separated color list (hex or named colors)

serieslabel

string

No

Label for this data series

Example:

📍 <bx:chartdata> Component

Defines individual data points within a series. Must be nested inside <bx:chartseries>.

Attributes

Attribute
Type
Required
Description

item

string

✅ Yes

Data point label/name

value

number

✅ Yes*

Data point value (*Required for all chart types except bubble)

x

number

⚠️ Bubble

X-coordinate (required for bubble charts)

y

number

⚠️ Bubble

Y-coordinate (required for bubble charts)

r

number

⚠️ Bubble

Bubble radius (required for bubble charts)

Standard Example:

Bubble Chart Example:

💡 Examples

Basic Examples

🥧 Simple Pie Chart

💡 Use Case: Perfect for showing how a total is divided into parts, like disk space usage or budget allocation.

📊 Bar Chart with Grid Lines

💡 Use Case: Great for comparing different categories or metrics at a glance.

📈 Line Chart for Time Series

💡 Use Case: Ideal for displaying trends and patterns over time.

🍩 Doughnut Chart

💡 Use Case: Similar to pie charts but with a modern look, great for dashboards.

Advanced Examples

Advanced Examples

🏔️ Area Chart with Styling

💡 Use Case: Shows volume or magnitude over time with emphasis on total quantity.

↔️ Horizontal Bar Chart

💡 Use Case: Perfect when you have long category names or want to emphasize horizontal comparison.

📚 Stacked Bar Chart

💡 Use Case: Shows both individual values and totals across categories. Perfect for comparing parts of a whole across different groups.

🎯 Radar Chart for Multi-dimensional Data

💡 Use Case: Excellent for showing multiple variables for comparison, like skill assessments or product features.

🔵 Scatter Plot for Correlation

💡 Use Case: Shows relationships between two variables, useful for correlation analysis.

🫧 Bubble Chart for Multi-dimensional Analysis

Bubble charts display three dimensions of data using x and y coordinates plus bubble size.

💡 Use Case: Perfect for displaying three-dimensional data where the third dimension (bubble size) represents metrics like customer satisfaction, investment size, or population.

Note: For bubble charts, use x, y, and r attributes instead of value in <bx:chartdata> components.

📱 Responsive Chart

BoxLang Charts support responsive sizing that adapts to container width and screen sizes. This is ideal for responsive web applications and dashboards.

💡 Use Case: Perfect for dashboards and mobile-friendly layouts where charts need to adapt to different screen sizes.

Responsive Tips:

  • Charts resize automatically to fit their container width (up to chartWidth)

  • Use maintainAspectRatio="false" to fill specific container heights

  • Set custom aspect ratios: 2 for wide (2:1), 1 for square (1:1), 0.5 for tall (1:2)

  • Add resizeDelay for performance optimization on frequently resizing containers

🚀 Advanced Features

🚀 Advanced Features

📊 Series Placement Options

Control how multiple data series are displayed in bar charts:

Default (Side-by-side):

Clustered (Grouped bars):

Stacked (Bars on top of each other):

🎨 Color Customization

Colors can be specified in multiple formats:

Color Best Practices:

  • Use contrasting colors for better accessibility

  • Limit to 5-7 distinct colors for clarity

  • Consider colorblind-friendly palettes for inclusive design

  • Use ColorBrewer for scientifically-designed palettes

📏 Custom Scales and Ranges

Control axis ranges for better data visualization:

Tips:

  • Set scaleFrom="0" for bar charts to avoid misleading visualizations

  • Use custom scales to zoom into specific data ranges

  • Combine with labelFormat for custom axis labels

🔤 Label Formatting and Rotation

Format axis labels and rotate them for better readability:

Label Position Options:

  • horizontal - Standard horizontal labels (default)

  • up_45 - 45° upward rotation

  • up_90 - 90° upward (vertical)

  • down_45 - 45° downward rotation

  • down_90 - 90° downward

  • vertical - Same as down_90

🎯 Interactive Features

Make charts interactive with click events:

🎭 Font and Style Customization

Complete control over text appearance:

📍 Marker Control

Customize data point markers for line and scatter charts:

🔧 Chart.js Integration

🔧 Chart.js Integration

This module is built on Chart.js v4.x, one of the most popular JavaScript charting libraries.

📚 Chart.js Resources

🎨 Chart.js Features Supported

This module exposes most Chart.js capabilities through BoxLang attributes:

  • ✅ All major chart types (pie, bar, line, doughnut, radar, polar area, scatter)

  • ✅ Responsive and adaptive sizing

  • ✅ Custom colors and styling

  • ✅ Axis configuration and grid lines

  • ✅ Legends and tooltips

  • ✅ Stacked and grouped series

  • ✅ Custom scales and ranges

  • ✅ Font styling and customization

🔌 How It Works

  1. Component Processing: BoxLang components collect your chart data

  2. Configuration Building: Data is transformed into Chart.js configuration

  3. Asset Loading: Chart.js library is automatically included via htmlHead()

  4. Rendering: HTML canvas element is created with inline JavaScript initialization

  5. Interaction: Chart.js handles all user interactions and animations

💡 Chart.js Best Practices

Based on Chart.js documentation, here are some tips:

Performance:

  • Use resizeDelay for charts that resize frequently

  • Limit data points to 100-200 for smooth animations

  • Disable animations for large datasets

Accessibility:

  • Always provide axis titles with xAxisTitle and yAxisTitle

  • Use seriesLabel to describe each data series

  • Ensure color contrasts meet WCAG standards

Visual Design:

  • Keep charts simple - one message per chart

  • Use appropriate chart types for your data

  • Add grid lines (showYGridlines="true") for precise reading

  • Limit colors to 5-7 for clarity

❓ Troubleshooting

❓ Troubleshooting

Charts Not Displaying

Problem: Chart area is blank or not visible.

Solutions:

  • ✅ Ensure BoxLang web support is enabled

  • ✅ Check that htmlHead() BIF is available

  • ✅ Verify Chart.js library loads (check browser console)

  • ✅ Make sure chart container has width/height

Colors Not Working

Problem: Custom colors not appearing correctly.

Solutions:

  • ✅ Use hex format without # or with ## (BoxLang escaping): colorlist="FF6384,36A2EB"

  • ✅ Check color format: hex values should be 6 characters (e.g., FF0000 not F00)

  • ✅ Named colors are case-insensitive: red, Red, RED all work

Responsive Charts Not Resizing

Problem: Charts don't adapt to container size changes.

Solutions:

  • ✅ Set responsive="true" (it's default, but verify)

  • ✅ Ensure parent container has defined width

  • ✅ Use maintainAspectRatio="false" if you need to fill specific heights

  • ✅ Check for CSS that might be constraining the chart

Multiple Series Not Stacking

Problem: Multiple series appear side-by-side instead of stacked.

Solutions:

  • ✅ Add seriesplacement="stacked" to <bx:chart>

  • ✅ Ensure all series have the same chart type

  • ✅ Stacking only works with bar, line, and area chart types

Data Not Showing

Problem: Chart renders but no data appears.

Solutions:

  • ✅ Verify all <bx:chartdata> components have item and value attributes

  • ✅ Check that values are numeric (not strings)

  • ✅ Ensure <bx:chartdata> is nested inside <bx:chartseries>

  • ✅ Verify <bx:chartseries> is nested inside <bx:chart>

Labels Overlapping

Problem: X-axis labels overlap and are unreadable.

Solutions:

  • ✅ Use categoryLabelPositions="up_45" to rotate labels

  • ✅ Increase chartWidth to give more space

  • ✅ Reduce font size with fontSize="10"

  • ✅ Consider using horizontalbar type for long labels

🤝 Contributing

We ❤️ contributions! This project is open source and welcomes your help to make it even better.

🐛 Found a Bug?

If you discover a bug, please:

  1. Check existing issues at GitHub Issues

  2. Create a new issue with:

    • Clear title and description

    • Steps to reproduce

    • Expected vs actual behavior

    • BoxLang version and environment details

    • Sample code that demonstrates the issue

💡 Have an Enhancement Idea?

We'd love to hear your ideas! Please:

  1. Open a Feature Request

  2. Describe the feature and its use case

  3. Explain how it would benefit users

  4. Consider if it aligns with Chart.js capabilities

🔧 Want to Contribute Code?

Excellent! Here's how to get started:

Development Setup

  1. Fork and Clone:

  2. Set up Local Development Environment:

    This script creates a boxlang_modules/bx-charts symbolic link pointing to the current directory, allowing you to test the module locally before publishing.

  3. Install Dependencies:

    The npm install command will automatically:

    • Download the latest Chart.js library

    • Copy it to the public/ folder

  4. Update Chart.js (Optional):

    To manually update Chart.js to the latest version:

  5. Test the Module Locally:

    Start a BoxLang server to test your changes:

    The test files in /tests/ directory provide comprehensive examples of all chart types and features.

  6. Build the Module (Optional):

    To build a distributable version of the module:

  7. Start Format Watcher:

Pull Request Guidelines

  • ✅ Create PRs against the development branch (NOT master)

  • ✅ Follow the existing code style (auto-format with cfformat)

  • ✅ Add tests for new features

  • ✅ Update documentation as needed

  • ✅ Keep commits focused and atomic

  • ✅ Link related issues in PR description

Code Standards

  • BoxLang/CFML: Follow cfformat settings

  • Formatting: Auto-format with box run-script format

  • Coding Standards: Follow Ortus Coding Standards

📚 Improve Documentation

Documentation improvements are always welcome:

  • Fix typos or unclear explanations

  • Add more examples

  • Improve code comments

  • Create tutorials or guides

💰 Financial Support

You can support BoxLang and all Ortus Solutions open source projects:

Patrons get exclusive benefits like:

  • Priority support

  • Early access to new features

  • FORGEBOX Pro account

  • CFCasts account

📞 Support Channels

Need help? Don't create an issue—use our support channels:

🏆 Contributors

Thank you to all our amazing contributors! ❤️

Contributors

Made with contributors-img

🔐 Security Vulnerabilities

If you discover a security vulnerability:

  1. DO NOT create a public issue

  2. Email security@ortussolutions.com

  3. Report in #security channel on Box Team Slack

All vulnerabilities will be promptly addressed.

📄 License

This project is licensed under the Apache License 2.0.

See LICENSE file for full details.

💼 Support & Resources

📖 Documentation

🌐 Links

🎓 Learning Resources

PreviousDocBox - API Docs
NextReference

Last updated

Was this helpful?