Timill Platform Documentation

Chart Source Files

Downloadable JavaScript sources for the scripted chart examples.

This directory contains example JavaScript code for creating custom charts using the Scripted Charts feature.

How to Use These Examples#

These are example scripts that demonstrate how to write JavaScript code for scripted charts. To use them:

  1. Navigate to a group’s page in Timill
  2. Add a new widget and select “Scripted Chart”
  3. In the widget configuration:
    • Set a title for your chart
    • Select the group to query data from
    • Copy and paste the example JavaScript code into the Monaco Editor
    • Optionally set a chart type hint and auto-refresh interval
  4. Save the widget

The JavaScript code will execute on the backend when the widget is rendered, querying your data and generating an ECharts configuration.

Available Examples#

1. Status Distribution Pie Chart (01_status_pie_chart.js)#

Shows the distribution of tasks by status using a pie chart.

Use Case: Quickly visualize how many tasks are in each status (open, in progress, closed, etc.)

2. User Workload Bar Chart (02_user_workload_bar.js)#

Displays the number of open tasks assigned to each user as a bar chart.

Use Case: Identify workload distribution and potential bottlenecks across team members.

3. Priority vs Status Scatter Chart (03_priority_scatter.js)#

Visualizes the relationship between task priority and status using a scatter plot.

Use Case: Identify patterns like high-priority tasks stuck in certain statuses.

Creating Your Own Charts#

Basic Structure#

Every scripted chart follows this pattern:

// 1. Query your data
const items = api.queryItems("your query here");

// 2. Transform/process the data
const processedData = /* your processing logic */;

// 3. Return an ECharts configuration
return {
  title: { text: 'Your Chart Title' },
  // ... ECharts options
};

Using Helper Functions#

For common chart types, use the built-in helpers:

// Pie Chart
return echarts.createPieChart(data, { title: 'My Pie Chart' });

// Bar Chart
return echarts.createBarChart(values, { 
  title: 'My Bar Chart',
  categories: labels 
});

// Line Chart
return echarts.createLineChart(values, {
  title: 'My Line Chart',
  categories: dates
});

// Scatter Chart
return echarts.createScatterChart(points, { title: 'My Scatter' });

Available API Functions#

  • api.queryItems(query) - Query items with RBAC enforcement
  • api.getItem(itemId) - Get a single item
  • api.countItems(query) - Count matching items
  • api.groupBy(items, field) - Group items by field
  • api.aggregate(items, field, fn) - Aggregate values (sum, avg, min, max, count)
  • api.filterItems(items, predicate) - Filter with custom function
  • api.getCurrentUser() - Get current user info
  • api.getCurrentGroup() - Get current group info

Context Variables#

Access execution context:

context.userId      // Current user ID
context.groupId     // Current group ID
context.instanceId  // Instance ID

Tips#

  1. Start Simple: Begin with a basic query and chart, then add complexity
  2. Test Queries: Test your query strings in the items list first
  3. Use Console: console.log() outputs to browser console for debugging
  4. Check Data: Validate your data structure before charting
  5. Read Docs: See Scripted Charts for complete API reference

Security#

All scripts run in a sandboxed environment with:

  • Read-only access (cannot modify items)
  • RBAC enforcement (only see items you have permission to view)
  • Resource limits (10s timeout, 50 API calls, 25MB memory)
  • No file system or network access

Need Help?#