View source for CumulusUtils Runtime Library

== Introduction ==
''CumulusUtils.js'' is the javascript runtime library providing the modular user with functionality otherwise available only in the website. It provides e.g. timing, realtime values, clocks and report loading. It is intended for users who are using CumulusUtils in a [[Modules|modular fashion]] and are willing and able to use javascript. The available globals and functions are described below.

The library can be found in the utils directory (on the CumulusMX machine) and is transferred after generation to the lib directory on the server.

The library is generated implicitly with the Website command parameter or on its own with the CUlib parameter:
 ''utils/bin/cumulusutils.exe CUlib''         => this command creates the library in the lib directory on the server

The user is free to load the library in the editor (formatting required) and make suggestions or modify changes. <br>
When modifying support is not available anymore but modifications can be used for experimenting and testing.

Contact [https://cumulus.hosiene.co.uk/memberlist.php?mode=viewprofile&u=9016 HansR] with suggestions and bugreports.

== Usage ==
'''''NOTE: the publication of the library requires feedback by the  users if anything does not work as expected or as intended!'''''<BR/>
'''''NOTE: Be aware the globals are for internal use and are generated with CUtils parameter values. Changes to these globals is disadvised as they are lost when generating a new version of the  library.'''''<BR/>
'''''NOTE: cumulusutils.js requires ''jquery'' for proper functioning and ''d3'' when using the sun and moon discs.'''''<BR/>

The library is intended to be used when CUtils is used in a modular fashion. Any other use is not supported. When using modules which require javascript to function properly (e.g. the Graphs modules) cumulusutils.js must be included in the users webpage using the following HTML code:
 <script src='lib/cumulusutils.js'></script>

And following the note above:
 <script src='https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js'></script>

And for using the sun and moon discs:
 <script src='https://cdnjs.cloudflare.com/ajax/libs/d3/5.15.1/d3.min.js'></script>"
 <script src='lib/suncalc.js'></script>

== Globals ==

=== Commandline parameters ===

CumulusUtils handles URL parameters and uses the following global for this:
 const urlParams = new URLSearchParams(window.location.search);
The Cutils modules will make use of this global, if the user wishes to handle URL parameters for all pages it would be a good idea to use this parameter.

== Functions ==
All functions are initialised including the timers and output will be displayed in the users website if a DIV with a specific id is used e.g.
 <pre><div id='#d3SunDisc'></div></pre>
will display the Sun disc and update it over the day.

The DIV id's will be shown under the specific caption, all functions below can be called by the user. If the specific DIV IDs does not exist in the website, that should not be a problem.

==== Init function ====

Call:
 ''$(function () {<arguments>} )''

At load time this function is called automatically - so it is h ere just for information, no user call is required - and initialises the library by calling the following functions:
#''loadRealtimeTxt'' => initializes the loading of ''realtime.txt'' and distributes the values over the dashboard
#''RT_timer = setInterval(loadRealtimeTxt, 30 * 1000);'' => Initialize the interval timer for reading realtime.txt (see below)
#''DoGaugeSettings'' => initializes the settings for the gauges as defined within CUtils. Note that Cutils uses its own gauges library and css file.
#''worldClockZone'' => Initializes the clocks
#''CreateSun'' and ''CreateMoon'' => Creates the sun and  moon disc
#''MinuteFunctions'' => initializes the minute function which takes care of the chart refreshes and the moving of the sun disc hand.
#''HourFunctions'' => initializes the hour functions which takes care of the moondisc updates
#''LoadUtilsReport'' => It calls the initial report to load

==== loadRealtime.txt ====

Call:
 No user call

This function is called automatically by the runtime system at the interval defined by the user in CMX (''Menu=>Internet Settings=>Interval Configuration=>Real time Interval Settings''). 

The values are distributed to the DIVs with the (self-explaining) IDs: 
 ''ajxCurTemp, ajxTempChange, ajxTempChangeIndicator, ajxTempMax, ajxTempMin, ajxCurPression, ajxBarChange, [...]'' etcetera... check the code.

The values get the configured change colour which is reset after 3 seconds.

=== DoGaugesSettings ===

Call: 
 ''DoGaugeSettings();''

This applies the gauges settings from ''cumulusutils.ini'' which requires the CUtils specific ''gauges.js''.<br>

Gauges which use the CMX gauges library are untouched.

=== worldClock ===

Call:
 ''worldClock(zone)''

Argument:
 zone := The timezone difference from UTC

Returns:
 string containing the time for the zone in the argument in format "hh:mm:ss"


The three clocks of CUtils are set by a summary function ''worldClockZone(zone)'' using the DIV IDs : ''CUClocktimeutc'', ''CUClocktimetz'' and ''CUClocktimeBrowser''


=== LoadUtilsReport ===

Call:
 ''LoadUtilsReport(string, bool);'' => Loads the intended report in the DIV with ID ''CUReportView''

Argument 1: The name of the report to load into DIV with ID: ''CUReportView''<br>

Argument 2: Boolean (true/false) indicating the report will be refreshed after ''<interval>'' amount of minutes. Normally true for charts.

In principle any text can be loaded in the DIV with ID ''CUReportView'' but for proper formatting it requires HTML. <br>
It can contain any javascript if that is contained in <SCRIPT></SCRIPT> tags.

=== CreateSun / CreateMoon ===

Call:
 ''CreateSun();''
 ''CreateMoon();''

These functions create the sun and the moon discs in the DIVs with the IDs ''d3SunDisc'' and ''d3MoonDisc'' respectively.<br>

These functions require the ''d3 library'' to  be loaded.


[[Category:CumulusUtils]]