JavaScript Charts

Release SSW v4.1.0 of StoneSteps Webalizer adds support for generic JavaScript charts and provides a sample implementation for all existing charts using the Highcharts package.

Highcharts Usage Note

Please note that Highcharts is not an Open Source package and may be used without buying a license only for non-commercial purposes. Read Highcharts' page for additional information about their licensing before enabling Highcharts in the reports:

https://shop.highsoft.com/faq#Non-Commercial-0

JavaScript Charts Configuration

Some existing configuration parameters, such as chart colors, continue to work with JavaScript charts, provided that the 3rd-party JavaScript charts integration layer takes advantage of the Stone Steps Webalizer's JavaScript charts implementation infrastructure. Some chart-related configuration parameters will be ignored.

New Configuration Parameters

JavaScriptCharts specifies the name of the JavaScript charting package and should only contain characters that are safe to be used in file names because it will be appended to the JavaScript file name that contains the integration for a particular JavaScript charting package. For example, if Highcharts is specified as shown below:

JavaScriptCharts    Highcharts

, StoneSteps Webalizer will generate report with references to a JavaScript charting integration file called webalizer_highcharts.js.

JavaScriptChartsPath may be used to specify the location of the JavaScript charts implementation package. If a known charting package is used in JavaScriptCharts, all necessary links to that implementation will be automatically generated in the reports. Only Highcharts is supported in the release SSW v4.1.1.

Ignored Configuration Parameters

GraphFontSmall, GraphFontMedium, GraphFontNormal, and GraphFontBold are not used because layouts used in JavaScript charts are more sensitive to externally-adjusted font types and sizes and instead font properties chosen in the JavaScript integration will be used.

GraphFontSmoothing is not applicable for JavaScript charts because font rendering is performed by the charting engine, such as SVG or Flash, which controls font rendering on its own.

GraphBorderWidth is ignored because each JavaScript charts integration can choose its own charting layout, which may not even have the same border the traditional PNG charts used.

GraphBackgroundAlpha was initially intended to allow users show their own image underneath PNG charts. Various charting packages use different techniques to control the location and transparency of additional images in the plot area, so each integration should provide a way to configure background images.

JavaScript Charts Integration

Overview

Stone Steps Webalizer implements JavaScript Charts in a generic way, without any specific charting package in mind. This means that chart data returned by Stone Steps Webalizer's JavaScript code must be converted to the charting package format, which is accomplished by the JavaScript charts integration layer.

JavaScript charts implementation

JavaScript charts implementation provides a generic layer of code to configure JavaScript charts, extract data from the HTML reports and pass the data to the JavaScript integration layer.

The implementation layer provides a generic configuration object and four chart objects:
  • DailyUsageChart
  • HourlyUsageChart
  • CountryUsageChart
  • MonthlySummaryChart
All charts objects are initialized in each report with a generic configuration object and a report-specific chart configuration object. The former contains information that can be shared between multiple charts, such as chart colors and language, while the latter contains report information, such as series titles, names of the months, etc, but not data. The data is always retrieved from the report HTML tables.

Each chart object contains four data members:

chart Report-specific chart configuration object
config Generic chart configuration object
data Chart data
version Used internally by the implementation

The generic configuration object and individual chart objects are described in the sections below.
Generic Configuration Object
An anonymous generic configuration object is created in each report and is shared between all chart objects in this report. The generic configuration object contains a variable number of data members, depending on whether any chart configuration parameters are specified in webalizer.conf. At the minimum, the generic configuration object contains the current report language and, since v4.2.0, the version of the configuration object itself, which identifies what data members may possibly appear in the configuration object:

{
   version: 2,                          // since v4.2.0
   lang: "en"
}

The generic configuration object is set up with the following prototype object:

var chart_config_prototype = {
   background_color: "#E8E8E8",
   gridline_color: "#808080",
   hits_color: "#00805C",
   files_color: "#0000FF",
   pages_color: "#00C0FF",
   visits_color: "#FFFF00",
   hosts_color: "#FF8000",
   xfer_color: "#FF0000",
   title_color: "#0000FF",
   weekend_color: "#00805C",
   pie_other_color: "#FFFFFF",
   pie_colors: ["#007F5C", "#FF7F00", "#0000FF", "#FF0000", "#00C0FF",
                "#FFFF00", "#7F007F", "#7FFFC0", "#FF00FF", "#FF5C7F"
               ]
};

, and is available in the integration layer via the config object of every chart object.
DailyUsageChart Object
The chart object of a daily usage chart object contains following data members:

{
      title: "Daily usage for May 2016",
      maxDay: 31,
      weekends: [1, 7, 8, 14, 15, 21, 22, 28, 29],
      seriesNames: {
         hits: "Hits",
         files: "Files",
         pages: "Pages",
         xfer: "Transfer",                   // KBytes prior to v4.2.0
         visits: "Visits",
         hosts: "Hosts"
      }
   }

The data object of a daily usage chart contains following data members:

{  
   days: [], 
   hits: [], files: [], pages: [], 
   xfer: [],
   xfer_hr[],                                  // since v4.2.0 
   visits: [], hosts: []
}

The days array contains an element for each day of the month with data. For example, if the report contains data for days 2, 3 and 5, there will be three elements in the days array with values 2, 3 and 5. All remaining arrays contain the same number of elements, one for each day.

DailyUsageChart defines the following member functions:

isWeekend(day) Returns true if day is a weekend and false otherwise
getDailyUsageMaxHits() Returns the maximum value of the hits array
getDailyUsageMaxXfer() Returns the maximum value of the xfer array
getDailyUsageMaxVisits() Returns the maximum value of the visits array

An example of a daily usage chart is shown below:

daily-usage-chart.png
HourlyUsageChart
The chart object of an hourly usage chart object contains following data members:

{
      title: "Hourly usage for May 2016",
      seriesNames: {
         hits: "Hits",
         files: "Files",
         pages: "Pages",
         xfer: "Transfer",                    // KBytes prior to v4.2.0
      }
 }

The data object of an hourly usage chart contains following data members:

{
   hours: [], 
   hits: [], files: [], pages: [], 
   xfer: [],
   xfer_hr[],                            // since v4.2.0 
}

The hours array contains an element for each hour with data. For example, if the report contains data for hours 0, 1, 4 and 5 there will be four elements in the hours array with values 0, 1, 4 and 5. All remaining arrays contain the same number of elements, one for each hour.

HourlyUsageChart defines the following member functions.

getHourlyUsageMaxHits() Returns the maximum value of the hits array
getHourlyUsageMaxXfer() Returns the maximum value of the xfer array

An example of an hourly usage chart is shown below:

hourly-usage-chart.png
CountryUsageChart
The chart object of a country usage chart object contains following data members:

{
     title: "Usage by Country for May 2016",
     totalVisits: 1234,
     otherLabel : "Other",
     seriesNames: {
         visits: "Visits"
      }
}

The data object of a Country Usage chart contains following data members:

{
   countries: [], 
   visits: [], percent: [], 
   visits_other: 0, percent_other: 0
}

The countries array contains an entry for each country in the Countries report, up to the maximum of 10 entries. The visits and percent arrays contain, respectively, the number of visits from a corresponding entry in the Countries report and the percentage of the total visits. The visits_other and percent_other values contain rolled-up data for the remaining countries if the number of countries in the report greater than ten. If there is less than ten countries in the report, these values contain zeros.

CountryUsageChart defines the following member functions:

getValueCount() Returns the number of available data points (pie slices)
getLabel(index) Returns the label for the slice identified by index
getVisits(index) Returns the number of visits for the slice identified by index
getPercent(index) Returns the percentage value for the slice identified by index
getColor(index) Returns the color of the slice identified by index

The index parameter in the methods above is a pie slice index from zero to getValueCount() - 1.
An example of a country usage chart is shown below:

country-usage-chart.png
MonthlySummaryChart
The chart object of a monthly summary usage chart object contains following data members:

{
      title: "Usage summary for X",
      shortMonths: ["Jan", "Feb", "Mar", ... "Dec"],
      longMonths: ["January", "February", ... "December"],
      monthCount: 14,
      firstMonth: {year: 2015, month: 1},
      seriesNames: {
         hits: "Hits",
         files: "Files",
         pages: "Pages",
         xfer: "Transfer",                    // KBytes prior to v4.2.0
         visits: "Visits",
         hosts: "Hosts"
      }
}

The data object of a Monthly Summary Usage chart contains following data members:

{
   months: [{year: 2016, month: 4}], 
   hits: [], files: [], pages: [], 
   visits: [], hosts: [], 
   xfer: [],
   xfer_hr[],                                  // since v4.2.0 
}

The months array contains an element for each history month with data. Each element of the months array is an object with two data members - year and month. The remaining arrays contain the same number of elements, one for each history month.

MonthlySummaryChart defines the following member functions:

getMonthlySummaryMaxHits Returns the maximum value of the hits array
getMonthlySummaryMaxXfer Returns the maximum value of the xfer array
getMonthlySummaryMaxVisits Returns the maximum value of the visits array

An example of a monthly summary chart is shown below:

monthly-summary-chart.png
Utility functions
A utility function called htmlEncode is provided to allow integration functions generate safe HTML for the charting package. For example, if a country name contains a single quote character, such as in Cote D'Ivoire, it may interfere with the charting package code if it appears unencoded in the generated HTML.

JavaScript charts Integration

The JavaScript charts integration layer translates Stone Steps Webalizer chart data into the format of any specific charting package. Each JavaScript chart integration must provide following global functions:
  • setupCharts(config)
  • renderDailyUsageChart(daily_usage_chart)
  • renderHourlyUsageChart(hourly_usage_chart)
  • renderCountryUsageChart(country_usage_chart)
  • renderMonthlySummaryChart(monthly_summary_chart)
The first function will be called once when the report is being loaded and initialized and all other functions will be called with their respective usage charts objects that are described in the implementation section above.

See webalizer_highcharts.js for a sample of the JavaScript charts integration.

Last edited Sep 4, 2016 at 3:15 PM by StoneSteps, version 29