Custom OpenUI5 Data Vizualization library

This library provides an OpenUI5 API that acts as a wrapper for D3-based charting library C3.js. It offers a more detailed and attractive API design than sap.viz chart controls, which interacts harmoniously especially in XML Views in combination with data binding.

Furthermore, this project is also a Boilerplate for all UI5 control libraries that rely completely on Open Source and uses 100% internally the same Gulp based build script as our OpenUI5 Starter Kit. One build script to rule them all, I mean, how cool is that? Probably pretty cool, at least as long as we haven't found an alternative with Webpack yet. So take a look at our Starter Kit to learn more about the features and functionality of the build process.

Usage

There are two options how to use the chart library in your UI5 project, depending of the project boilerplate you are using.

a) projects based on OpenUI5 Starter Kit

Add ui5-lib-visualization as dev dependency:

yarn add ui5-lib-visualization --dev

Update ui5 library config in your package.json:

"ui5" {
  // ...
  "library":[
      {
        "name": "ui5.viz",
        "path": "node_modules/ui5-lib-visualization/dist/ui5/viz",
        "prebuild": true
      }
  ]
  // ...
}

Finished, you can now use the library in your XML Views via e.g. xmlns:viz="ui5.viz" or in your controllers etc. If you want to upgrade the library, just use default yarn commands, the build process of the starter kit will handle the rest for you:

yarn upgrade ui5-lib-visualization

b) other UI5 projects (see also UI5Lab)

Download or clone this repository:

git clone git@github.com:pulseshift/ui5-lib-visualization.git

Copy the complete ready-to-use library from /dist to a target destination in your UI5 project (please keep the folder structure as is ui5/viz/).

Add the library to the sap-ui-bootstrap resourceroots in your index.html:

data-sap-ui-resourceroots="{ "ui5.viz": "pathToTargetDestination/ui5/viz" }"

Please be aware that for option b) all manual steps must be repeated every time when you want to update the library version. Because this variant is more susceptible to errors, we recommend to use the OpenUI5 Starter Kit.

Documentation

How to test real live samples please see section Example. Till then, please enjoy our first beta version of our automatcally created markdown API documentation:

Features

Hint: This overview is not yet complete. In the course of time we will point out all important new functions and add these points to the new demo app, too.

A brief overview of features, additional to C3.js line and area charts:

Complete API coverage of properties and aggregations for a fully integrated feature set in XML views.
If supported by C3.js, rerender will be avoided by the chart control to ensure smooth transitions in case of changes in the data.
Support of pins and areas.
Support for special designs such as animated dashed lines or hatched areas.
Convergence interval as a new display type of series.
Simple color management by implementing color palettes or individual colors for specific series.

Example

To execute the demo, please follow the instructions described in section Development. At the time the demo is being refactored with the goal to provide you an SAP explored like experience.

Here a basic sample of how to use the charts in an XML view:

<!-- ensure that the series data points and the x-axis labels have the exact same amount of entries -->
<Chart
  width="{store>/width}"
  height="{store>/height}"
  showTooltip="{store>/showTooltip}"
  groupedTooltip="{store>/groupedTooltip}"
  showLegend="{store>/showLegend}"
  xAxisType="Category"
  series="{store>/series}">
  <series>
    <ChartSeries
      type="{store>type}"
      name="{store>name}"
      data="{
        path: 'store>dataPoints',
        templateShareable: false
      }">
      <ChartDataPoint value="{store>}" />
    </ChartSeries>
  </series>
  <xAxis>
    <ChartAxis labels="{ path: 'store>/xAxis/labels'}">
      <ChartAxisLabel value="{store>}" />
    </ChartAxis>
  </xAxis>
  <yAxis>
    <ChartAxis title="{store>/yAxis/title}" />
  </yAxis>
</Chart>

Respective controller code:

// define series color palette with a preset based on material design colors
ui5.viz.setDefaultColorPalette(ui5.viz.ColorPalette.Material500)

// define model
const oModel = new JSONModel({
  title: 'Chart',
  width: '100%',
  height: '300px',
  showTooltip: true,
  groupedTooltip: true,
  showLegend: true,
  xAxis: {
    labels: ['April', 'May', 'June', 'July', 'August', 'September']
  },
  yAxis: {
    title: 'Sightings in the woods 🌲'
  },
  series: [
    {
      name: 'Foxes 🦊',
      dataPoints: [2, 5, 3, 5, 8, 9],
      type: ui5.viz.ChartSeriesType.Spline
    },
    {
      name: 'Bears 🐻',
      dataPoints: [1, 2, 0, 2, 1, 3],
      type: ui5.viz.ChartSeriesType.Spline
    },
    {
      name: 'Deers 🦌',
      dataPoints: [14, 20, 18, 23, 17, 18],
      type: ui5.viz.ChartSeriesType.Spline
    }
  ]
})

this.getView().setModel(oModel, 'store')

Development

Download or clone this repository:

git clone git@github.com:pulseshift/ui5-lib-visualization.git

Please ensure that you have installed node and yarn before you continue.

Install dependencies:

yarn

Start developing: Will build all resources start watcher task and start a HTTP server

yarn start

The app should open in your browser automatically, otherwise open: http://localhost:3000/demo/index.html

Info: To get a more detailed logging, use yarn start:verbose instead.

Distribution

Start build: Will create a dist directory in your project root.

yarn build

Afterwards, the production app build can be tested by run yarn start:dist. The app should open in your browser automatically, otherwise open: http://localhost:3000/demo/index.html

Info: To get a more detailed logging, use yarn build:verbose instead.

Publish new version (please use correct semantic versioning): Will execute tests, update docs and create a dist directory in your project root as prepublish step.

yarn publish

Contributing & Troubleshooting

Contributions, questions and comments are all welcome and encouraged.

Check our current issues or, if you have something in mind how to make it better, create your own issue. We would be happy to discuss how they can be solved.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Lena Serdarusic} 💻💡🤔	_{Jascha A. Quintern} 💻💬	_{Michael Dell} 🤔

verfehlix/ui5-lib-visualization