@esri/cedar

@esri/cedar

Cedar is a library for crafting and sharing data visualizations powered by ArcGIS Services.

You are looking at the documentation for cedar v1.x, which is currently in alpha. You can also view the v0.x documentation.

View live examples of how to use cedar

Currently Esri Cedar is in development and should be thought of as a beta or preview.

Types of Charts

Cedar currently provides a set of commonly used chart types including bar, line, area, and pie, scatter, and bubble. In the future it will be possible for developers to create unique and custom charts that can be used by other developers with new data sources.

Getting Started

Installing Cedar

You can install cedar and it's dependencies from npm:

npm install @esri/cedar

Alternatively, you can get cedar from the unpkg.com CDN as shown below.

Loading Cedar

You can load Cedar and its dependencies by including script tags that point to the CDN or your locally installed versions of these libraries. This will make the cedar global available to your application.

<!-- load the amCharts base library -->
<script src="https://www.amcharts.com/lib/3/amcharts.js"></script>
<!-- in this case, we only need bar charts, so we'll load the appropriate amCharts script -->
<script src="https://www.amcharts.com/lib/3/serial.js"></script>
<!-- optionally load an amcharts theme -->
<script src="https://www.amcharts.com/lib/3/themes/light.js"></script>
<!-- load cedar -->
<script src="https://unpkg.com/@esri/cedar/dist/umd/cedar.js"></script>
<script>
  var chart = new cedar.Chart({"type":"bar"});
</script>

If you need to use other chart types, or want to use amCharts plugins, load the appropriate amCharts scripts before loading cedar:

<!-- for pie charts -->
<script src="https://www.amcharts.com/lib/3/pie.js"></script>
<!-- for scatter and bubble charts -->
<script src="https://www.amcharts.com/lib/3/xy.js"></script>
<!-- for radar charts -->
<script src="https://www.amcharts.com/lib/3/radar.js"></script>
<!-- optioinally load the amcharts plugin to export the chart as and image or table -->
<script src="https://www.amcharts.com/lib/3/plugins/export/export.min.js"></script>
<link rel="stylesheet" href="https://www.amcharts.com/lib/3/plugins/export/export.css" type="text/css" media="all" />

Using Cedar

Once cedar is loaded you can create and show the chart at a designated element as follows:

  //create a cedar chart using the known 'bar' type
  var chart = new cedar.Chart({"type": "bar"});

  // connect to the data
  var datasets = [{
    "url": "https://services.arcgis.com/uDTUpUPbk8X8mXwl/arcgis/rest/services/Public_Schools_in_Onondaga_County/FeatureServer/0",
    "id": 1,
    "query": {
      "orderByFields": "Number_of_SUM DESC",
      "groupByFieldsForStatistics": "Type",
      "outStatistics": [{
        "statisticType": "sum",
        "onStatisticField": "Number_of",
        "outStatisticFieldName": "Number_of_SUM"
      }]
    }
  }];

  // designate a one or more series to show the data on the chart
  var series = [{
    "category": {"field": "Type", "label": "Type"},
    "value": {"field": "Number_of_SUM", "label": "Number of Students"},
    "source": 1
  }];

  // optinally override any of the cart type's default styles
  var overrides = {
    "categoryAxis": {
      "labelRotation": -45
    }
  }

  // render the chart
  var elementId = 'chart';
  chart.show(elementId);

Components of a Cedar Chart

Cedar charts are defined by the following ingredients:

• an array of datasets, each has, either:
• a url to an ArcGIS Feature Layer along with optional query parameters;
• ...or data can be an array of inline features
• an array of series that bind the Feature Layer attributes to bars, lines, points, etc on the chart
• and overrides are specific modifications to the cart type's default styles

Development Instructions

This repository is a monoreop managed using lerna

1. Fork this repository and clone 'cedar' locally
2. cd into the cedar folder
3. Install the dependencies with npm install
4. to run the docs site locally, start a web server at the root folder and visit /docs
5. to rebuild the script files used by the docs page whenver the source code is updated, run npm start
6. Create a pull request

Tests

To run tests one time for all packages, run npm test from the monorepo root.

To run tests continually for any package as you update it's soruce code, cd into that package and run npm run:watch to continually run that package's tests as you update the source code

Dependencies

Cedar currently uses the amCharts JavaScripts Charts library as it's charting engine. You will need to include this along with cedar in your application.

Cedar supports the same browsers as ArcGIS Online, however you may need to include polyfills for fetch and Promise, if your application has to support browers that don't support fetch or Promise (i.e. IE or older versions of Safari/Android).

Versioning

For transparency into the release cycle and in striving to maintain backward compatibility, Cedar is maintained under the Semantic Versioning guidelines and will adhere to these rules whenever possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major while resetting minor and patch
• New additions without breaking backward compatibility bumps the minor while resetting the patch
• Bug fixes and misc changes bumps only the patch

For more information on SemVer, please visit http://semver.org/.

Licensing

Copyright 2017 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.