{"id":17930934,"url":"https://github.com/jenkinsci/echarts-api-plugin","last_synced_at":"2026-04-18T15:03:56.775Z","repository":{"id":36981125,"uuid":"220239469","full_name":"jenkinsci/echarts-api-plugin","owner":"jenkinsci","description":"Jenkins plug-in that provides ECharts","archived":false,"fork":false,"pushed_at":"2026-04-14T14:47:17.000Z","size":27304,"stargazers_count":9,"open_issues_count":1,"forks_count":28,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-14T16:32:12.168Z","etag":null,"topics":["api-plugin"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/echarts-api/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"community_bridge":"jenkins","custom":["https://www.jenkins.io/donate/#why-donate"]}},"created_at":"2019-11-07T13:08:20.000Z","updated_at":"2026-04-14T14:43:38.000Z","dependencies_parsed_at":"2024-04-05T07:23:12.952Z","dependency_job_id":"4505cf8c-125f-45c5-8ac8-352e5e561176","html_url":"https://github.com/jenkinsci/echarts-api-plugin","commit_stats":null,"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/jenkinsci/echarts-api-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fecharts-api-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fecharts-api-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fecharts-api-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fecharts-api-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/echarts-api-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fecharts-api-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31973205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-plugin"],"created_at":"2024-10-28T21:18:40.569Z","updated_at":"2026-04-18T15:03:56.736Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":["https://funding.communitybridge.org/projects/jenkins","https://www.jenkins.io/donate/#why-donate"],"categories":[],"sub_categories":[],"readme":":tip-caption: :bulb:\n:imagesdir: etc/images\n\n= ECharts Jenkins Plugin\n\nimage:https://github.com/jenkinsci/echarts-api-plugin/workflows/GitHub%20CI/badge.svg[GitHub Actions, link=https://github.com/jenkinsci/echarts-api-plugin/actions]\nimage:https://img.shields.io/github/issues-pr/jenkinsci/echarts-api-plugin.svg[GitHub pull requests, link=https://github.com/jenkinsci/echarts-api-plugin/pulls]\n\nProvides https://echarts.apache.org/en/index.html[ECharts] for Jenkins Plugins.\nECharts is an open-sourced JavaScript visualization tool to create intuitive, interactive, and highly-customizable charts.\nIt can run fluently on PC and mobile devices, and it is compatible with most modern Web Browsers.\n\nThis plugin contains the JS and CSS files of the latest https://echarts.apache.org/en/index.html[ECharts] release and corresponding Jenkins UI elements (model, view, and controller).\n\n== How to use the plugin\n\nA Jenkins plugin typically also reports some kind of trend from build to build. Up to now Jenkins core provides only a quite limited concept of rendering such trends as trend charts.\nThe http://www.jfree.org/jfreechart/[JFreeChart framework] offered by Jenkins core is a server side rendering engine that creates charts as static PNG images that will be included on the job and details pages.\nNowadays, several powerful JS-based charting libraries are available that do the same job(well actually an even better job) on the client side.\nThat has the advantage that these charts can be customized on each client without affecting the server performance.\nMoreover, you get a lot of additional features (like zooming, animation, etc.) for free. Additionally, these charting libraries not only support the typical build trend charts but also a lot of additional charts types that can be used to improve the user experience of a plugin.\nOne of those charting libraries is https://echarts.apache.org/en/index.html[ECharts]. This library has a powerful API and supports literally every chart type one can image of.\nYou can get some impressions of the features on the https://echarts.apache.org/examples/en/[example page] of the library.\n\nTo use these charts, one can embed charts that use this library by importing the corresponding JS files and by defining the chart in the corresponding Jelly file. While that already works quite well, it will be still somewhat cumbersome to provide the corresponding model for these charts from Jenkins build results.\nSo I added a powerful Java API that helps to create the model for these charts on the Java side. This API provides the following features:\n\n- Create trend charts based on a collection of build results.\n- Separate the chart type from the aggregation to simplify unit testing of the chart model.\n- Toggle the type of the X-Axis between build number or build date (with automatic aggregation of results that have been recorded on the same day).\n- Automatic conversion of the Java model to the required JSON model for the JS side.\n- Support for pie and line charts (more to come soon).\n\nThose charts can be used as trend chart in the project page (see \u003c\u003cimg-trend\u003e\u003e) or as information chart in the details view of a plugin (see \u003c\u003cimg-pie\u003e\u003e).\n\n[#pie-charts]\n=== Pie charts\n\nA simple but still informative chart is a pie chart that illustrates numerical proportions of plugin data.\nIn the Forensics plugin such a chart shows the numerical proportions for the number of authors or commits for the source code files in the Git repository.\nIn the warnings plugin such a chart shows the numerical proportions of the new, outstanding, or fixed warnings, see \u003c\u003cimg-pie\u003e\u003e.\n\n.Pie chart in the Warnings plugin\n[#img-pie]\nimage::pie.png[Pie chart example,width=60%]\n\nTo include such a chart in your details view, you can use the provided `pie-chart` tag.\nIn the following snippet you see this tag in action (embedded in a https://github.com/jenkinsci/bootstrap5-api-plugin[Bootstrap card]):\n\n[source,xml,linenums]\n.index.jelly\n----\n\u003c?jelly escape-by-default='true'?\u003e\n\u003cj:jelly xmlns:j=\"jelly:core\"  xmlns:c=\"/charts\" xmlns:bs=\"/bootstrap\"\u003e\n\n    [...]\n    \u003cbs:card title=\"${%Number of authors}\" fontAwesomeIcon=\"users\"\u003e\n      \u003cc:pie-chart id=\"authors\" model=\"${it.authorsModel}\" height=\"256\" /\u003e\n    \u003c/bs:card\u003e\n    [...]\n\n\u003c/j:jelly\u003e\n----\n\nYou need to provide a unique ID for this chart and the corresponding model value.\nThe model must be the JSON representation of a corresponding `PieChartModel` instance.\nSuch a model can be created with a couple of lines:\n\n[source,java,linenums]\n.ViewModel.java\n----\n[...]\nPieChartModel model = new PieChartModel(\"Title\");\n\nmodel.add(new PieData(\"Segment 1 name\", 10), Palette.RED);\nmodel.add(new PieData(\"Segment 2 name\", 15), Palette.GREEN);\nmodel.add(new PieData(\"Segment 3 name\", 20), Palette.YELLOW);\n\nString json = new ObjectMapper().writeValueAsString(model);\n[...]\n----\n\n[#progress-charts]\n=== Progress charts\n\nAnother simple chart (that is based on a pie chart) is the progress chart.\nUsing this chart, you can render a simple progress value using a pie chart as a backend.\n\n.Progress chart in the Autograding plugin\n[#img-progress]\nimage::progress.png[Pie chart example]\n\nTo include such a chart in your details view, you can use the provided `progress-chart` tag.\nIn the following snippet you see this tag in action (embedded in a https://github.com/jenkinsci/bootstrap5-api-plugin[Bootstrap card]):\n\n[source,xml,linenums]\n.index.jelly\n----\n\u003c?jelly escape-by-default='true'?\u003e\n\u003cj:jelly xmlns:j=\"jelly:core\"  xmlns:c=\"/charts\" xmlns:bs=\"/bootstrap\"\u003e\n\n    [...]\n    \u003cbs:card title=\"${%Autograding score}\" fontAwesomeIcon=\"graduation-cap\"\u003e\n      \u003cc:progress-chart id=\"total-progress\" model=\"${it.getProgressModel(80)}\" height=\"150\"\n                        value=\"80\" tooltip=\"80% is very good\"/\u003e\n    \u003c/bs:card\u003e\n    [...]\n\n\u003c/j:jelly\u003e\n----\n\nYou need to provide a unique ID for this chart and the corresponding model value.\nThe model must be the JSON representation of a corresponding `PieChartModel` instance.\nSuch a model can be created with a couple of lines, see the class https://github.com/jenkinsci/autograding-plugin/blob/master/src/main/java/io/jenkins/plugins/grading/PercentagePieChart.java[PercentagePieChart].\n\n[#trend-charts]\n=== Trend charts on the job level view\n\nTo show a trend that renders a line chart on the job page (see \u003c\u003cimg-trend\u003e\u003e) you need to provide a so-called floating box (stored in the file `floatingBox.jelly` of your job action (see \u003c\u003cjenkins-chart-model\u003e\u003e)).\nThe content of this file is quite simple and contains just a `trend-chart` tag:\n\n[source,xml,linenums]\n.floatingBox.jelly\n----\n\u003c?jelly escape-by-default='true'?\u003e\n\u003cj:jelly xmlns:j=\"jelly:core\" xmlns:c=\"/charts\"\u003e\n\n  \u003cc:trend-chart it=\"${from}\" title=\"${%SCM Files Count Trend}\" enableLinks=\"true\"/\u003e\n\n\u003c/j:jelly\u003e\n----\n\nOn the Java side the model for the chart needs to be provided in the corresponding subclass of `JobAction` (which is the owner of the floating box).\nSince the computation of trend charts is quite expensive on the server side as well,\n(several builds need to be read from disk, and the interesting data points need to be computed) this process has been put into a separate background job.\nOnce the computation is done, the result is shown via an Ajax call.\nTo hide these details for plugin authors, you should simply derive your `JobAction` class from the corresponding `AsyncTrendJobAction` class, that already contains the boilerplate code.\nSo your static plugin object model will actually\nbecome a little bit more complex:\n\n[#jenkins-chart-model]\n.Jenkins chart model design\nimage::chart-model.png[Jenkins chart model]\n\nBasically, you need to implement the method `LinesChartModel createChartModel()` to create the line chart.\nThis method is quite simple to implement since most of the hard work is provided by the library.\nYou will be invoked with an iterator of your build actions, starting with the latest build.\nThe iterator advances from build to build until no more results are available (or the maximum number of builds to consider has been reached).\nThe most important thing to implement in your plugin is the way how data points are computed for a given `BuildAction`.\nHere is an example of such a `SeriesBuilder` implementation in the Forensics Plugin:\n\n[source,java,linenums]\n.FilesCountSeriesBuilder.java\n----\npackage io.jenkins.plugins.forensics.miner;\n\nimport java.util.HashMap;\nimport java.util.Map;\n\nimport edu.hm.hafner.echarts.SeriesBuilder;\n\n/**\n * Builds one x-axis point for the series of a line chart showing the number of files in the repository.\n *\n * @author Ullrich Hafner\n */\npublic class FilesCountSeriesBuilder extends SeriesBuilder\u003cForensicsBuildAction\u003e {\n    static final String TOTALS_KEY = \"total\";\n\n    @Override\n    protected Map\u003cString, Integer\u003e computeSeries(final ForensicsBuildAction current) {\n        Map\u003cString, Integer\u003e series = new HashMap\u003c\u003e();\n        series.put(TOTALS_KEY, current.getNumberOfFiles());\n        return series;\n    }\n}\n----\n\nYou are not limited to a single-line chart.\nYou can show several lines in a single chart, you can show stacked values, or even the delta between some values.\nYou can also have a look at the https://github.com/jenkinsci/warnings-ng-plugin/tree/master/plugin/src/main/java/io/jenkins/plugins/analysis/core/charts[charts of the warnings plugin]to see some of these features in detail.\n\n.Trend chart with several lines in the Warnings plugin\n[#img-trend]\nimage::trend-lines.png[Trend with several lines example, width=70%]\n\n.Trend chart with stacked lines in the Warnings plugin\n[#img-stacked]\nimage::trend-stacked.png[Trend chart with stacked lines example, width=70%]\n\nYou can find several examples of Jenkins views that use ECharts in the https://github.com/jenkinsci/warnings-ng-plugin[Warnings Next Generation plugin] and in the https://github.com/jenkinsci/warnings-ng-plugin[Forensics plugin].\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fecharts-api-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fecharts-api-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fecharts-api-plugin/lists"}