ui5-lib-visualization

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.

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:

• ui5.viz.Chart
• ui5.viz.ChartSeries
• ui5.viz.ChartDataPoint
• ui5.viz.ChartAxis
• ui5.viz.ChartAxisLabel
• ui5.viz.ChartLine
• ui5.viz.ChartArea
• ui5.viz.Color

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 chart annotations, like lines and areas in various designs.
• 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 Explore 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 yarn2 before you continue.

Install dependencies:

yarn

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

yarn dev

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 dev:verbose instead.

Distribution

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

yarn dist

This will build the app, test the code with linters and updates all docs automatically. 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

Increase version number according to semantic versioning e.g.

yarn version patch

If the app build matches your requirements, upload your build to npm:

yarn npm 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 🤔

License

This project is licensed under the MIT license. Copyright 2017 PulseShift GmbH