ChartsCompiler: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
 
(16 intermediate revisions by the same user not shown)
Line 3: Line 3:
   |__TOC__
   |__TOC__
   |}
   |}
The ChartsCompiler is the "next-generation" method of creating charts for websites on the basis of CumulusMX based systems. Charts are defined in a dedicated [[Charts Definition Language (CDL)|Charts Definition Language]] and compiled into a file (or files) containing both the HTML/javascript menu infrastructure as well as the Highcharts javascript code to create the charts. Data - JSON files as produced by CumulusMX - is assumed to be present in the directory  from where the page is called.
The ChartsCompiler is the "next-generation" method of creating charts for websites on the basis of CumulusMX based systems. Charts are defined in a file ''CutilsCharts.def'' in a dedicated [[Charts Definition Language (CDL)|Charts Definition Language]] and compiled into a file (or files) containing both the HTML/javascript menu infrastructure as well as the Highcharts javascript code to create the charts. Data - in JSON files similar like those produced by CumulusMX - is assumed to be present in the directory  from where the page is called. The ChartsCompiler gives the user the possibility to completely freely define and generate charts for all weather variables within CMX (including userdefined and derivatives) for within any website context.
 
One special feature for all charts in CumulusUtils is the possibility for the background image. This is described in [[Website_Generator#Chart_Background_Images|the chapter on the website]]


The compiler can be used within CumulusUtils website (intrinsic with the Website Generator [[ChartsCompiler#Implicit_activation|(Implicit Activation)]]) and the output can be used standalone (really standalone if you rename the output to .html) or standalone from within a users website (menu or link; [[ChartsCompiler#Explicit_activation|Explicit Activation]]). When used outside the CumulusUtils infrastructure, you must be aware of the [[cumulusutils.ini|parameters]] (section general) ''GeneratejQueryInclude'' and ''DoLibraryIncludes''.
The compiler can be used within CumulusUtils website (intrinsic with the Website Generator [[ChartsCompiler#Implicit_activation|(Implicit Activation)]]) and the output can be used standalone (really standalone if you rename the output to .html) or standalone from within a users website (menu or link; [[ChartsCompiler#Explicit_activation|Explicit Activation]]). When used outside the CumulusUtils infrastructure, you must be aware of the [[cumulusutils.ini|parameters]] (section general) ''GeneratejQueryInclude'' and ''DoLibraryIncludes''.
'''NOTE: with the Website Generator, use of the ''CutilsCharts.def'' is always optional'''. If the file is not present, the  generator will always fall back to the default charts.


== Language ==
== Language ==
There are principally no translations associated with these charts because the user writes his own text (titles), the Y-axis have been translated already through the old system and only when new axis arrive new translations will be needed.  
There are principally no translations associated with these charts because the user writes his own text (titles), the Y-axis have been translated already section [website] or [general] and only when new axis arrive new translations will be needed. New axis titles will be added to the section [Compiler].
 
Be aware that for the '''''Free axis''''', the user sees initially an entry in the section [Compiler] for ''ChartId''Dimensionless with the value Dimensionless. So for the ''SoilMoisture'' chart the Y-axis title will have an entry for ''SoilMoistureDimensionless'' with the value Dimensionless. Then the user has to translate this to e.g. ''Centibar'' or whatever unit the sensor has.


The only exceptions are the legend words as those are formed by the reserved words of the plotvariables. If the users wishes to translate those (give another wording) he can find those terms in the language file under the section Compiler.
== Chart legend translations ==
The legend of the compiler charts however may require some user action. Because the legend is created from the reserved words of the plotvariables, some  of which may be created by the user, the descriptions of the legend may become somewhat incomprehensible for the unknown website user. Therefore, the legend descriptions get their own entries in the language file in the section compiler. You can use those entries for translation and/or change of description.


== Operation ==
== Operation ==
The compiler can be activated/used in two ways: implicit and explicit. Both methods require a file ''CutilsCharts.def'' containing the charts definitions to be present in the ''utils'' directory.
The compiler can be activated/used in two ways: implicit and explicit. Both methods require a file ''CutilsCharts.def'' containing the charts definitions to be present in the ''utils'' directory. A default file can be found in the distribution named: ''CutilsCharts-default-for-use.def''. When the user renames this to ''CutilsCharts.def'' it is ready for use.


=== Implicit activation ===
=== Implicit activation ===
Line 33: Line 40:
=== Data activation ===
=== Data activation ===
If the definition of the charts requires additional data not provided by CMX the the following command will automatically provide those data in a JSON in a way similar to CMX.
If the definition of the charts requires additional data not provided by CMX the the following command will automatically provide those data in a JSON in a way similar to CMX.
   utils/bin/cumulusutils.exe UserAskedData
   utils/bin/cumulusutils.exe [[UserAskedData]]
You have to schedule this command if you wish to use the FTP frequency CMX uses for its JSON's.
You have to schedule this command if you wish to use the FTP frequency CMX uses for its JSON's.


Note that these JSON files specific to CumulusUtils '''always reside in the website root''' of CumulusUtils, even if you have more websites and defined the ''CumulusRealTimeLocation''.
NOTES:
#These JSON files specific to CumulusUtils '''always reside in the website root''' of CumulusUtils, even if you have more websites and defined the ''CumulusRealTimeLocation''.
#To the above rule there is the exception of modular use: if the user decides to use CUtils a modular way it is possible to have a separate directory on the webserver below the webroot which contains the CUtils files for the modules in use.
 
There are the following parameters for this in use:
 
  DoModular=false          // When ''true'', CUtils is used in a modular fashion. Incompatible with the Website command
  ModulePath=              // The path on the server where the CUtils specific JSONs will be uploaded to


== Output ==
== Output ==
Line 47: Line 61:


=== When using the CDL OUTPUT spec ===
=== When using the CDL OUTPUT spec ===
For every OUTPUT specification in the definition file an output is created containing all charts defined from that point, including the chart on which it was defined. ''cumulusutils.txt'' will always be created which means at  least the first chart will  be in there. ''cumulusutils.txt'' will be used to fill the Home button in the CumulusUtils website.
For every OUTPUT specification in the definition file an output is created containing all charts defined from that point, including the chart on which it was defined. ''cumuluscharts.txt'' will always be created which means at  least the first chart will  be in there. ''cumuluscharts.txt'' will be used to fill the Home button in the CumulusUtils website.


So:
So:
#An output spec ''file1.txt'' for the first chart will create ''cumulusutilcharts.txt'' containing the first chart and a ''file1.txt'' also containing the first chart but also the subsequent charts.
#An output spec ''file1.txt'' for the first chart will create ''cumuluscharts.txt'' containing the first chart and a ''file1.txt'' also containing the first chart but also the subsequent charts.
#An output spec ''file2.txt'' for the third chart will create chart 1 and 2 in ''file1.txt'' and chart 3 in ''file2.txt''.
#An output spec ''file2.txt'' for the third chart will create chart 1 and 2 in ''file1.txt'' and chart 3 in ''file2.txt''.
#An output spec ''file3.txt'' for the last and eighth chart will create chart 3,4,5,6,7 in ''file2.txt'' and chart 8 in ''file3.txt''
#An output spec ''file3.txt'' for the last and eighth chart will create chart 3,4,5,6,7 in ''file2.txt'' and chart 8 in ''file3.txt''
Line 60: Line 74:


   [Compiler]
   [Compiler]
  ChartContainerHeight=700      => Provides the means for the  user to adjust the height of the chart which in case of modular use is very usefull (default=700)
   DoneToday=17/04/21            => If the user uses data on ''Daily basis'' or ''All basis'' (from the dayfile), the data need to be prepared only once per day.
   DoneToday=17/04/21            => If the user uses data on ''Daily basis'' or ''All basis'' (from the dayfile), the data need to be prepared only once per day.
                                     This parameter tells us the age of the data present to the website.
                                     This parameter tells us the age of the data present to the website.


== Inner working ==
== Inner working ==
Line 70: Line 82:
When the definition is parsed, a list of chart data structures containing all required information is created. After parsing is successful - one pass - the list is passed to the code generator which creates the output.
When the definition is parsed, a list of chart data structures containing all required information is created. After parsing is successful - one pass - the list is passed to the code generator which creates the output.


The user only has influence on the chart definitions. Errors are logged to the standard logfile. There is currently no true error recovery so when an error is encountered it is logged and the compiler exits to fall back to the default cumuluscharts.txt. The user has to correct the error and run the compiler again. A normal way to develop the charts would be to iterate through the command ''CompileOnly'' and when the generation goes without errors, incorporate the charts in the website.
The user only has influence on the chart definitions. Errors are logged to the standard logfile. There is currently no true error recovery so when an error is encountered it is logged and the compiler exits to fall back to the default cumuluscharts.txt. The user has to correct the error and run the compiler again. A normal way to develop the charts would be to iterate through the command ''CompileOnly'' and when the generation goes without errors, incorporate the charts in the website. When using the command like this, be aware of what is written on the [[Website_Generator#Javascript_libraries|Website Generator page]].


Read the [[Charts Definition Language (CDL)|Charts Definition Language]].
Read the [[Charts Definition Language (CDL)|Charts Definition Language]].


[[Category:CumulusUtils]]
[[Category:CumulusUtils]]

Latest revision as of 15:56, 11 November 2023

Introduction

The ChartsCompiler is the "next-generation" method of creating charts for websites on the basis of CumulusMX based systems. Charts are defined in a file CutilsCharts.def in a dedicated Charts Definition Language and compiled into a file (or files) containing both the HTML/javascript menu infrastructure as well as the Highcharts javascript code to create the charts. Data - in JSON files similar like those produced by CumulusMX - is assumed to be present in the directory from where the page is called. The ChartsCompiler gives the user the possibility to completely freely define and generate charts for all weather variables within CMX (including userdefined and derivatives) for within any website context.

One special feature for all charts in CumulusUtils is the possibility for the background image. This is described in the chapter on the website

The compiler can be used within CumulusUtils website (intrinsic with the Website Generator (Implicit Activation)) and the output can be used standalone (really standalone if you rename the output to .html) or standalone from within a users website (menu or link; Explicit Activation). When used outside the CumulusUtils infrastructure, you must be aware of the parameters (section general) GeneratejQueryInclude and DoLibraryIncludes.

NOTE: with the Website Generator, use of the CutilsCharts.def is always optional. If the file is not present, the generator will always fall back to the default charts.

Language

There are principally no translations associated with these charts because the user writes his own text (titles), the Y-axis have been translated already section [website] or [general] and only when new axis arrive new translations will be needed. New axis titles will be added to the section [Compiler].

Be aware that for the Free axis, the user sees initially an entry in the section [Compiler] for ChartIdDimensionless with the value Dimensionless. So for the SoilMoisture chart the Y-axis title will have an entry for SoilMoistureDimensionless with the value Dimensionless. Then the user has to translate this to e.g. Centibar or whatever unit the sensor has.

Chart legend translations

The legend of the compiler charts however may require some user action. Because the legend is created from the reserved words of the plotvariables, some of which may be created by the user, the descriptions of the legend may become somewhat incomprehensible for the unknown website user. Therefore, the legend descriptions get their own entries in the language file in the section compiler. You can use those entries for translation and/or change of description.

Operation

The compiler can be activated/used in two ways: implicit and explicit. Both methods require a file CutilsCharts.def containing the charts definitions to be present in the utils directory. A default file can be found in the distribution named: CutilsCharts-default-for-use.def. When the user renames this to CutilsCharts.def it is ready for use.

Implicit activation

If the file CutilsCharts.def with the charts definitions is present in the utils directory then the command:

 utils/bin/cumulusutils.exe Website

will activate the compiler and generate the output.

If the file CutilsCharts.def is not present or contains errors, the output will be the default cumuluscharts.txt, containing the original charts for the Home button in the menu.

Explicit activation

If the file CutilsCharts.def with the charts definitions is present in the utils directory then the command:

 utils/bin/cumulusutils.exe CompileOnly

will activate the compiler explicitly outside the context of the Website Generator. This leads to the possibility to use the output also as a separate module.

Data activation

If the definition of the charts requires additional data not provided by CMX the the following command will automatically provide those data in a JSON in a way similar to CMX.

 utils/bin/cumulusutils.exe UserAskedData

You have to schedule this command if you wish to use the FTP frequency CMX uses for its JSON's.

NOTES:

  1. These JSON files specific to CumulusUtils always reside in the website root of CumulusUtils, even if you have more websites and defined the CumulusRealTimeLocation.
  2. To the above rule there is the exception of modular use: if the user decides to use CUtils a modular way it is possible to have a separate directory on the webserver below the webroot which contains the CUtils files for the modules in use.

There are the following parameters for this in use:

 DoModular=false          // When true, CUtils is used in a modular fashion. Incompatible with the Website command
 ModulePath=              // The path on the server where the CUtils specific JSONs will be uploaded to

Output

The Defaults

If the file CutilsCharts.def with the charts definitions is present in the utils directory, then the output for the ChartsCompiler is (until version 5.3.5) the file cumuluscharts.txt. As such it replaces the default cumuluscharts.txt which will always be available as a backup in case of errors in the definitions or processing.

So cumuluscharts.txt contains either:

  1. When an error occurs during parsing of the CutilsCharts.def: the standard (old version) of the charts which contains a mix of RECENT and DAILY charts.
  2. When parsing of CutilsCharts.def is without error: the charts as defined in the CutilsCharts.def.

When using the CDL OUTPUT spec

For every OUTPUT specification in the definition file an output is created containing all charts defined from that point, including the chart on which it was defined. cumuluscharts.txt will always be created which means at least the first chart will be in there. cumuluscharts.txt will be used to fill the Home button in the CumulusUtils website.

So:

  1. An output spec file1.txt for the first chart will create cumuluscharts.txt containing the first chart and a file1.txt also containing the first chart but also the subsequent charts.
  2. An output spec file2.txt for the third chart will create chart 1 and 2 in file1.txt and chart 3 in file2.txt.
  3. An output spec file3.txt for the last and eighth chart will create chart 3,4,5,6,7 in file2.txt and chart 8 in file3.txt

The Compiler outputs can be loaded standalone to present the charts if the data are available in the same directory. The txt files can be loaded in any way needed (PHP or javascript) or renamed HTML and loaded directly. Be aware that the inifile parameters GeneratejQueryInclude and DoLibraryIncludes have impact here depending on how you organise your website or wish to show the charts.

Inifile parameters

The module has two inifile parameter (see cumulusutils.ini):

 [Compiler]
 DoneToday=17/04/21             => If the user uses data on Daily basis or All basis (from the dayfile), the data need to be prepared only once per day.
                                   This parameter tells us the age of the data present to the website.

Inner working

The CutilsCharts.def file contains the chart definitions according to the Charts Definition Language.

When the definition is parsed, a list of chart data structures containing all required information is created. After parsing is successful - one pass - the list is passed to the code generator which creates the output.

The user only has influence on the chart definitions. Errors are logged to the standard logfile. There is currently no true error recovery so when an error is encountered it is logged and the compiler exits to fall back to the default cumuluscharts.txt. The user has to correct the error and run the compiler again. A normal way to develop the charts would be to iterate through the command CompileOnly and when the generation goes without errors, incorporate the charts in the website. When using the command like this, be aware of what is written on the Website Generator page.

Read the Charts Definition Language.